기존 리포지토리 조사에 활용하기──구현 전에 읽게 하고, 재현하게 하고, 멈추게 하기 제6회

AI 에이전트(AI Agent)에게 일을 맡길 때, 많은 사람은 바로 구현을 요청합니다.

이 버그를 수정해 줘.

이 기능을 추가해 줘.

이 에러를 해결해 줘.

물론, 작동할 때도 있습니다.

하지만 기존 리포지토리(Existing Repository)에서는 갑자기 구현에 들어갈수록 사고가 늘어납니다.

이름이 비슷한 파일이 있다.

오래된 구현이 남아 있다.

테스트의 진입점(Entry Point)을 알기 어렵다.

사양이 issue, PR, Slack, docs에 흩어져 있다.

로그에 찍힌 에러와 실제 원인이 다르다.

작은 수정처럼 보이지만, 사실 인증이나 DB를 건드린다.

이런 곳에서 에이전트(Agent)에게 갑자기 고치라고 시키면, 금방 길을 잃습니다.

제5회에서는 MCP와 tools의 권한을 나누었습니다.

이번에는 코드를 쓰기 전의 사용법입니다.

읽게 한다.

정리하게 한다.

재현하게 한다.

가설을 내게 한다.

멈춰야 할 곳에서 멈춘다.

구현보다 앞선 공정에서 에이전트(Agent)를 사용할 수 있게 되면, 기존 리포지토리에서의 안정감이 상당히 달라집니다.

첫 번째 의뢰를 바꿉니다.

나쁜 의뢰입니다.

상품 검색이 고장 났으니 수정해 주세요.

이것은 에이전트(Agent)에게 조사, 판단, 구현, 검증을 전부 한꺼번에 넘기는 것입니다.

좋은 의뢰입니다.

상품 검색이 고장 난 원인을 조사해 주세요.
아직 파일은 변경하지 마세요.
출력해 주었으면 하는 것:
...

이렇게 하면 에이전트(Agent)는 우선 읽는 역할을 하게 됩니다.

읽는 것만으로도 가치가 있습니다.

사람이 30분 동안 걸려 찾던 진입점 찾기를 상당히 단축할 수 있습니다.

단, 여기서는 아직 고치지 않습니다.

고치기 전에 지도를 만들게 합니다.

읽기 전용(read-only) 조사에는 유형이 있습니다.

## Investigation Task
Goal:
- 무엇을 조사하고 싶은가
...

여기서 중요한 것은 '사실(Facts)'과 '가설(Hypothesis)'을 분리하는 것입니다.

에이전트(Agent)는 그럴듯한 설명을 만드는 데 능숙합니다.

그래서 이렇게 나누게 합니다.

## Facts
- `ProductSearch.tsx`는 `useProductQuery`를 호출하고 있다.
- `useProductQuery`는 URL query의 `q`를 읽는다.
...

이 출력이라면 사람이 판단할 수 있습니다.

재현 테스트(Reproduction Test)만 만들게 하는 것도 유효합니다.

구현은 변경하지 마세요.
먼저 failing test만 추가해 주세요.
그 테스트가 이번 보고 내용을 재현하고 있는 이유를 설명해 주세요.

이것이 가능해지면, 수정하기 전에 승리할 수 있는 경로(winning path)가 보입니다.

수정했다고 생각했는데 다른 동작을 망가뜨리는 일도 줄어듭니다.

failing test를 만들게 했다면, 그것도 리뷰(review)합니다.

테스트가 있으니 안심이다, 라는 뜻이 아닙니다.

agent가 만든 테스트는 구현의 편의에 치우칠 수 있습니다.

확인해야 할 점은 이것입니다.

## Reproduction Test Review
- 정말로 보고된 버그를 재현하고 있는가.
- 구현 상세 내용에 너무 치우쳐 있지 않은가.
...

재현 테스트가 약하면 그 이후의 수정도 약해집니다.

그래서 구현 수정 전에 test review를 끼워 넣습니다.

장애 조사에서는 가설을 하나로 너무 좁히지 않는 것이 좋습니다.

agent에게 처음부터 "원인이 뭐야?"라고 물으면 하나의 설명에 치우치기 쉽습니다.

대신에 가설을 여러 개 내놓게 합니다.

원인 후보를 3가지 제시해 주세요.
각각에 대해, 이를 뒷받침하는 증거, 반증이 되는 확인 사항, 다음에 살펴볼 파일을 작성해 주세요.

출력 예시입니다.

## Hypothesis 1: query builder composition
Supports:
- combined filter only fails
...

이런 형태라면 다음에 무엇을 봐야 할지가 결정됩니다.

가설은 설명이 아니라 조사의 도구입니다.

로그를 agent에게 전달할 때는 그대로 대량으로 붙여넣지 않는 것이 좋습니다.

먼저 필요한 범위로 자릅니다.

• 시간 범위
• request id
• user id는 필요하다면 익명화
• error code
• deploy 전후
• 관련 service

그리고 이렇게 요청합니다.

다음 로그를 읽어 주세요.
원인을 단정하지는 마세요.
출력:
...

로그 읽기에서 중요한 것은 노이즈(noise)를 분리하는 것입니다.

agent는 관계가 있어 보이는 것을 너무 많이 집어낼 때가 있습니다.

그래서,

이번 원인과 관계가 없어 보이는 로그도 분리해 주세요.
왜 관계가 옅다고 판단했는지도 작성해 주세요.

라고 요청합니다.

관계있는 것뿐만 아니라, 관계없어 보이는 것도 분리합니다.

이것만으로 조사가 조금 더 정돈됩니다.

조사, 재현, 가설이 갖춰지면 바로 구현해도 될 것처럼 보입니다.

하지만 그전에 한 번 리뷰합니다.

아직 구현하지 마세요.
지금까지의 조사 결과를 review해 주세요.
확인할 것:
...

이것은 사소해 보이지만 효과적입니다.

구현 전에 한 번 멈추는 것만으로도 불필요한 수정을 줄일 수 있습니다.

조사가 끝나더라도 수정은 작게 유지합니다.

먼저 service의 query builder만 수정해 주세요.
UI는 건드리지 마세요.
테스트는 `tests/product-search.test.ts`만 실행해 주세요.

또는,

먼저 failing test를 통과시키는 최소한의 수정만 해주세요.
refactor는 하지 마세요.

기존 리포지토리에서는 올바른 수정이라도 범위가 너무 넓어지면 리뷰가 어려워집니다.

그래서 최소 수정과 개선을 분리합니다.

이번 작업:
- bug fix
- 회귀 테스트 (regression test)
...

이렇게 나누면 PR(Pull Request)을 읽기 쉬워집니다.

그대로 사용할 수 있는 템플릿입니다.

## Task
기존 리포지토리에서 `<기능명>`의 구현 위치와 변경 리스크를 조사한다.
## Do Not
...

장애 조사라면 다음과 같습니다.

## Incident Investigation
Goal:
- `<증상>`의 원인 후보를 정리한다.
...

수정 전에 끼워 넣는 템플릿입니다.

## Pre-Fix Review
지금까지의 조사 결과를 review해 주세요.
아직 구현하지 마세요.
...

장애 조사에서 얻은 것은 다음으로 넘깁니다.

예를 들어, 이번에 알게 된 사실이 다음과 같다고 가정해 봅시다.

• combined filter는 깨지기 쉽다
• pagination default가 누락되기 쉽다
• mobile path만 URL query 동기화 방식이 다르다
• logs에서는 request id를 추적해야 한다

이것을 그 자리의 PR 코멘트로만 남기면 사라집니다.

runbook에 기록합니다.

Product Search 장애 대응 런북 (Incident Runbook)

상품 검색이 실패할 때:

1. 키워드 전용 요청(keyword-only request)이 작동하는지 확인합니다.
   ...

다음에 동일한 종류의 장애가 발생했을 때, 에이전트(agent)에게 다음과 같이 요청할 수 있습니다.

Product Search Incident Runbook에 따라 조사해 주세요.
아직 수정하지 마세요.

이것이 Compound입니다.

매번 적용하고 싶은 조사 규칙은 AGENTS.md로 돌려보냅니다.

## 조사 규칙 (Investigation Rules)
- 버그 수정 (Bug fix) 전에, 재현 조건과 실패 테스트 (failing test) 후보를 제시한다.
- 사실과 가설을 분리한다.
...

여기까지 작성해 두면, 다음번 에이전트는 처음부터 다른 움직임을 보입니다.

"고쳐줘"가 아니라, "조사하고, 재현하고, 멈춰라"가 기본이 됩니다.

기존 리포지토리에서 AI 에이전트를 사용한다면, 갑자기 구현하게 하는 것보다 안정적입니다.

먼저 읽기 전용 (read-only)으로 조사합니다.

진입 파일(entry file)을 찾습니다.

기존 패턴을 읽습니다.

로그를 시계열로 정리합니다.

사실과 가설을 분리합니다.

재현 조건을 만듭니다.

실패 테스트 (failing test)를 리뷰합니다.

수정 전 리뷰를 거칩니다.

최소 수정에 집중합니다.

배운 점을 런북 (runbook)과 AGENTS.md로 돌려보냅니다.

이것만으로도 에이전트는 실무 흐름에 상당히 잘 올라타게 됩니다.

코드를 쓰는 능력보다 앞서서, 읽는 능력과 멈추는 능력을 사용합니다.

기존 리포지토리에서는 이 방법이 효과적입니다.

다음 회차에서는 Codex App을 다룹니다.

CLI뿐만 아니라 화면, 파일, 스레드 (thread), 리뷰 (review)를 어떻게 작업대로 사용할 것인가에 대해 다룹니다.

특히, 비엔지니어(non-engineer)나 주변 직군 사람들이 Codex App을 어떻게 사용할 수 있는지까지 깊이 있게 살펴봅니다.