Claude Code 리뷰를 설정하는 일반적인 방법은 "버그, 누락된 테스트 및 보안 문제를 위해 이 diff를 리뷰해줘"라는 하나의 프롬프트를 가진 단일 서브에이전트(subagent)를 사용하는 것입니다. 마지막에 하나의 보고서를 생성하죠. 이것은 어느 정도 작동은 하지만, 보고서가 특정한 방식으로 예측 가능하게 얕아지는 경향이 있습니다. 즉, 프롬프트에서 먼저 언급되는 관심사가 가장 많은 주의를 받게 되고, 마지막에 언급되는 것은 토큰 한 문장 정도로 끝나거나 아예 무시됩니다.

이것은 모델 품질의 문제가 아닙니다. 구조적인 문제입니다.

하나의 에이전트가 세 가지 일을 수행할 때 성능이 떨어지는 이유

단일 서브에이전트는 해당 작업을 위한 하나의 컨텍스트 윈도우(context window)와 하나의 출력 예산(output budget)을 가집니다. 동일한 패스(pass)에서 논리적 정확성, 테스트 커버리지(test coverage), 보안에 대해 추론하도록 요청하면, 에이전트는 세 가지 서로 다른 멘탈 모델(mental models)에 주의를 동시에 할당해야 합니다: "이 코드가 주장하는 대로 작동하는가", "어떤 입력값이 커버리지에서 누락되었는가", 그리고 "이것이 어떻게 악용될 수 있는가". 이들은 서로 다른 관점입니다. 논리적 버그를 스캔하는 리뷰어는 의도(intent)에 맞춰 패턴 매칭(pattern-matching)을 수행합니다. 보안 감사관(security auditor)은 공격자의 행동에 맞춰 패턴 매칭을 수행합니다. 한 번의 패스로 이 두 가지를 모두 수행하도록 강제하면, 에이전트는 지배적인 관점을 선택하고 나머지를 부차적인 것으로 취급하거나, 아니면 모든 곳에 균등하게 분산하여 모든 면에서 얕게 다루게 됩니다.

실제로 이는 다음과 같은 현상으로 나타납니다: 리뷰 에이전트가 명명 규칙의 불일치와 off-by-one 오류를 지적한 뒤, 구체적인 내용 없이 "테스트 추가를 고려하세요"와 같은 불렛 포인트를 추가하고, diff가 명백히 인증(auth)에 관한 것이 아니라면 보안 관련 사항은 거의 드러내지 않습니다.

프롬프트만이 아닌, 관심사의 분리

해결책은 더 나은 프롬프트가 아닙니다. 각각 좁은 작업 범위를 가지고 실제로 필요한 도구에만 접근할 수 있는 세 개의 별도 서브에이전트를 만드는 것입니다:

• code-reviewer: diff(차이점) 및 주변 파일에 대한 읽기 전용 (read-only) 액세스 권한을 가집니다. 전체 프롬프트는 정확성 (correctness), 보안 (security), 설계 문제 (design issues)에 집중하며, 심각도 순으로 정렬됩니다.
• test-writer: 읽기 권한과 더불어 테스트 파일로 범위가 제한된 쓰기 (write) 액세스 권한을 가집니다. 이 에이전트의 역할은 diff가 건드리는 코드 경로 중 커버리지 (coverage)가 없는 부분을 찾아내고, 저장소 (repo)에 이미 있는 프레임워크를 사용하여 결정론적 (deterministic) 테스트를 작성하는 것입니다.
• security-auditor: 읽기 전용이지만, diff뿐만 아니라 전체 저장소에 대해 grep을 수행할 수 있는 권한을 가집니다. 인젝션 위험 (injection risks), 안전하지 않은 역직렬화 (unsafe deserialization), 코드 내 비밀 정보 (secrets-in-code) 등은 보통 값이 즉각적인 변경 사항 외부로 어떻게 흐르는지 확인해야 하는데, diff만 보는 방식으로는 이를 놓치게 됩니다.

각 에이전트는 하나의 길고 일반적인 보고서 대신, 짧고 집중된 보고서를 생성합니다. 이들을 함께 (서로 의존하지 않으므로 병렬로) 배치하면, 전체 리뷰는 마치 세 명의 전문가가 각각 검토를 수행한 것처럼 읽힙니다. 실제로 그렇게 일어난 일이기 때문입니다.

차이점은 개별 서브에이전트가 통합된 에이전트보다 더 "똑똑해지는" 것이 아닙니다. 도구 액세스 (tool access)와 프롬프트 (prompt)의 범위를 단일 관심사로 제한함으로써, 깊이 (depth)와 너비 (breadth) 사이의 트레이드오프 (tradeoff)를 제거하는 것입니다. security-auditor는 "이 변수 이름이 잘 지어졌는가"와 같은 문제와 주의력을 경쟁하지 않습니다. 오직 하나의 작업만 수행하므로, 세 가지 작업 중 3분의 1을 수행하는 대신 그 작업에만 집중합니다.

실수하기 쉬운 부분

"만약을 대비해서" 모든 서브에이전트에게 전체 저장소 액세스 권한을 주고 싶은 유혹이 생길 수 있습니다. 그러지 마세요. 이는 에이전트의 속도를 늦출 뿐만 아니라, 더 나쁜 것은 추론 (reasoning) 단계가 아닌 도구 선택 (tool-selection) 단계에서 당신이 해결하려 했던 것과 동일한 주의력 분산 (attention dilution) 문제를 다시 불러온다는 점입니다. 최소 권한 원칙 (least-privilege)에 따른 도구 액세스는 여기서 단순한 보안상의 미덕이 아니라, 각 서브에이전트의 작업 범위를 충분히 좁게 유지하여 실제로 그 일을 잘 해낼 수 있게 만드는 핵심 요소입니다.

(AI의 도움을 받아 작성되었습니다.)