Molayo

© 2026 Molayo

Qiita헤드라인2026. 06. 20. 00:21

AI agent의 PR은 diff만 봐서는 부족하다

요약

AI agent가 생성한 PR(Pull Request)을 리뷰할 때는 단순한 코드 변경점(diff)을 넘어, 에이전트의 작업 로그와 컨텍스트를 확인하는 것이 필수적입니다. 에이전트의 작업 과정을 투명하게 공개하기 위한 워크 로그(work log) 도입의 중요성을 강조합니다.

핵심 포인트

  • AI agent의 PR은 diff만으로 의도를 파악하기 어려워 작업 로그 확인이 필요함
  • GitHub Copilot Chat의 세션 참조 기능처럼 에이전트의 중간 과정이 리뷰의 재료가 됨
  • PR 템플릿에 에이전트 전용 리뷰 노트(Task, Changed paths 등)를 포함할 것을 권장
  • 프론트엔드 작업 시 CSS 영향 범위나 테스트 조건 등 에이전트가 확인하지 않은 범위를 식별해야 함

AI agent가 만든 PR에서 가장 무서운 것은 거대한 diff가 아니라, 묘하게 깔끔하고 작은 diff라고 생각합니다.

인간이 작성한 PR이라면, "이 부분은 왜 이렇게 하셨나요?"라고 물어볼 수 있습니다. 답변이 성의 없더라도, 적어도 본인의 머릿속에는 작업의 문맥 (context)이 있습니다.

agent의 PR은 다릅니다. 설명문은 자연스럽게 쓸 수 있습니다. 하지만 그 설명이 정말로 작업 흐름을 반영하고 있는지는 별개의 문제입니다. 특히 frontend repo에서는 diff가 20줄이라 하더라도, CSS의 적용 방식, viewport, form state, route의 경계, Playwright의 실패 조건 등이 얽혀 있습니다.

따라서 agent PR의 review는 최종 diff만 읽는 작업이 아니게 됩니다. 작업 로그를 읽는 작업이 됩니다.

GitHub Copilot Chat이 agent session을 참조할 수 있게 되었다는 이야기는 상당히 상징적입니다. agent의 중간 과정이 단순한 뒷단의 실행 로그가 아니라, review나 follow-up의 재료가 되어 갑니다.

Claude Code나 Codex와 같은 tool도 terminal, browser, MCP, hooks, remote task 등 작업 영역이 넓어지고 있습니다. 편리합니다. 다만, 그만큼 PR의 diff만으로는 "무엇을 확인했는지"가 보이기 어렵습니다.

최소한, reviewer가 보고 싶은 것은 이 정도입니다.

  • PR diff
  • agent session log / chat context
  • 실행한 command
  • 확인한 CI / test log
  • browser preview / screenshot / Playwright 확인 사항
  • agent가 확인하지 않은 범위

여기서 중요한 것은, agent의 설명을 믿기 위해 로그를 보는 것이 아니라는 점입니다. 의심할 곳을 줄이기 위해 보는 것입니다.

"pnpm test를 실행했습니다"인지, "대상 test만 실행했습니다"인지. "mobile screenshot을 봤습니다"인지, "desktop의 happy path만 봤습니다"인지. 이 부분이 섞이면 review는 갑자기 힘들어집니다.

우선은 PR template에 작은 work log 칸을 넣는 것이 확실한 방법입니다.

## Agent review note
- Task:
- Changed paths:
...

전부를 채울 수 없는 PR은 그것만으로 review의 진입점이 결정됩니다. 정보가 없는 곳을 인간이 봅니다.

예를 들어 SearchPanel의 mobile layout 깨짐을 agent에게 수정하게 했다면, 다음과 같은 입도(granularity)로도 충분합니다.

## Agent review note
- Task: SearchPanel의 mobile layout 깨짐을 수정
- Changed paths: `src/components/SearchPanel.tsx`, `src/components/SearchPanel.css`
...

이 칸이 있는 것만으로도 reviewer는 처음에 볼 곳을 선택할 수 있습니다.

SearchPanel.css의 selector가 global하게 새어 나가지 않았는지. 390px뿐만 아니라 768px에서는 어떤지. dark mode를 보지 않았다면 색상이나 border의 변경을 중점적으로 볼 것인지. 그런 판단을 할 수 있습니다.

agent PR의 review에서 frontend는 은근히 어렵습니다. build가 통과해도 화면이 깨지고, test가 통과해도 CSS의 영향 범위를 놓치기 쉽습니다.

저라면 우선 이 5가지를 보겠습니다.

CSS는 작은 diff라도 피해가 확산됩니다.

-.search-panel .button {
+button {
width: 100%;
...

이런 변경은 typecheck에서는 절대로 걸러지지 않습니다. agent가 "layout을 수정했습니다"라고 써 놓았더라도, selector scope는 인간이 직접 보는 편이 좋습니다.

Tailwind에서도 마찬가지입니다. class가 하나 늘어난 것처럼 보여도, responsive prefix나 dark mode 조건이 빠지는 경우가 있습니다.

UI 수정 의도였으나, form state나 validation 조건까지 바뀌어 있는 PR은 주의해야 합니다.

// 외관상의 disabled 수정을 의도했으나, submit 조건도 바꾸고 있음
const canSubmit = hasInput && !isLoading;

disabled 클래스만 수정하는 것이라면 괜찮습니다. 하지만 canSubmit 조건까지 바뀌어 있다면, 리뷰 대상은 레이아웃 (layout)이 아니라 사양 변경 (specification change)이 됩니다.

Next.js나 Remix에서는 컴포넌트 (component) 수정처럼 보여도 로더 (loader), 서버 액션 (server action), 캐시 (cache)의 경계를 건드리고 있는 경우가 있습니다.

에이전트 (agent)가 작동하면 관련 파일 (file)을 한꺼번에 수정해 주기도 합니다. 그 자체는 도움이 됩니다. 다만, 경계를 넘나드는 시점에서는 리뷰의 강도를 높여야 합니다.

"브라우저 (browser)에서 확인했습니다"라는 말은 약합니다.

프론트엔드 (frontend) PR에서는 어떤 뷰포트 (viewport)를 확인했는지 적어주길 바랍니다.

Browser / screenshot checks:
- 390x844: search panel open / keyboard hidden
- 768x1024: sidebar collapsed
...

모든 PR에서 3개의 뷰포트를 볼 필요는 없습니다. 하지만 모바일 (mobile) 버그를 수정했다면 모바일 스크린샷 (mobile screenshot)이 필요합니다. 반대로 데스크톱 (desktop)만 확인했다면, Not verified 항목에 모바일을 적어야 합니다.

pnpm test가 통과했다는 사실보다, 무엇을 테스트 (test)하지 않았는지가 더 유용할 때가 있습니다.

- Commands run: `pnpm test SearchPanel`, `pnpm typecheck`
- Not verified: production build, Safari, visual regression, real API response

이렇게 작성하면, 사람은 보완해야 할 확인 사항을 즉시 결정할 수 있습니다.

에이전트 세션 로그 (agent session log)를 너무 맹신하는 것도 위험합니다.

로그가 있다고 해서 옳은 것은 아닙니다. 에이전트는 잘못된 가설로 파일을 읽고 있을 수도 있고, 실패한 커맨드 (command)를 간과하고 있을 수도 있습니다. 도중에 "아마 여기겠지"라고 판단하여 필요한 화면 확인을 건너뛰기도 합니다.

그럼에도 로그는 도움이 됩니다.

  • 어떤 파일 (file)을 읽었는지
  • 어떤 커맨드 (command)에서 실패했는지
  • 무엇을 재실행했는지
  • 어떤 툴 (tool) / MCP / 훅 (hook)을 사용했는지
  • 외부 컨텍스트 (external context)에 접근했는지

이 정보가 있으면 리뷰어 (reviewer)는 "처음부터 전부 읽어야 하는" 상태에서 벗어날 수 있습니다.

설명문의 유려함이 아니라, 작업의 흔적을 보는 것. 에이전트 PR에서는 이것이 매우 효과적입니다.

규모가 큰 에이전트 PR은 먼저 분할하는 것이 좋습니다. 이는 인간의 PR과 마찬가지입니다.

다만, 작은 PR이라도 템플릿 (template)은 필요합니다. 오히려 작은 PR일수록 "뭐, 괜찮겠지"라며 그냥 넘어가기 쉽기 때문입니다.

## Agent review note
- Task: ProductCard의 price 표시 깨짐 수정
- Changed paths: `src/components/ProductCard.tsx`
...

이 PR은 머지 (merge)해도 괜찮을지도 모릅니다. 하지만 스크린샷 (screenshot)이 없다면 UI는 사람이 확인합니다. 로케일 (locale)을 확인하지 않았다면 포맷터 (formatter)를 확인합니다. 리뷰의 초점이 명확해집니다.

반대로, 이것이 없으면 다음과 같이 됩니다.

ProductCard의 표시 깨짐을 수정했습니다.
테스트는 통과했습니다.

이것만으로는 리뷰어가 결국 diff를 전부 읽을 수밖에 없습니다. 에이전트에게 맡겼음에도 인간 측의 인지 부하 (cognitive load)가 줄어들지 않습니다.

AI 에이전트의 PR 리뷰는 똑똑한 에이전트를 믿는 문제가 아닙니다.

레포지토리 (repo) 측에 작업의 흔적을 읽기 쉽게 만드는 형식을 갖추는 문제입니다.

처음 시작한다면, 이 정도면 충분하다고 생각합니다.

  • PR 템플릿 (template)에 Agent review note를 추가한다.
  • Commands run과 Not verified를 추가한다.

필수로 만든다 - frontend bug fix의 경우 viewport / screenshot 항목을 마련한다

  • MCP, hooks, external context를 건드렸다면 명시한다
  • 큰 agent PR은 분할한 뒤에 review 한다

사소해 보입니다. 하지만, 이 사소함이 필요합니다.

agent가 만든 PR을 diff만으로 읽는 것은, CI log를 보지 않고 flaky test를 판단하는 것과 비슷합니다. 어쩌다 운 좋게 통과한 것인지, 제대로 확인한 것인지 알 수 없습니다.

앞으로 agent workflow를 repo에 도입한다면, 첫 번째 observability layer(관측성 계층)는 PR template이면 충분하다고 생각합니다. 거창한 dashboard보다 먼저, reviewer가 "무엇을 봐야 하는가"를 고민하지 않게 만드는 것입니다.

그것만으로도 agent PR은 훨씬 읽기 쉬워집니다.

  • GitHub Changelog: Copilot Chat now sees your agent sessions
  • GitHub Copilot app: agent-native desktop experience
  • OpenAI Codex remote workflow
  • Claude Code docs

AI 자동 생성 콘텐츠

본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0