서브에이전트에게 검토를 위임하고 보고서를 확인하는 방법

"페이지를 확인해 주세요"라는 요청은 리뷰어에게 많은 선택지를 남깁니다. 동작의 오류를 찾거나, 디자인을 평가하거나, 코드를 작성하는 다른 방법을 제안할 수 있습니다. 그 결과 깔끔한 의견 목록을 받을 수 있지만, 이 목록이 여러분의 작업에 거의 도움이 되지 않을 수 있습니다. Claude Code의 서브에이전트에게 명확한 작업 지시를 전달하는 방법과 완료 여부를 확인하는 방법을 살펴봅시다.

reviewer를 아직 설정하지 않았다면 먼저 역할을 생성하고 첫 번째 실행을 수행하세요. 여기서는 작업 지시 자체와 응답의 완전성에 집중합니다.

1. 리뷰어에게 전달할 사항

리뷰어는 다른 사람의 작업을 확인하고 근거가 있는 의견을 반환합니다. 이 글의 예시에서는 이미 설정된 사용자 정의 서브에이전트 reviewer가 이 역할을 맡으며, 파일 읽기와 검색만 할 수 있습니다: Read, Grep, Glob. 코드를 읽지만 수정하지 않으며 브라우저에서 페이지를 실행하지 않습니다. reviewer라는 이름이 자동으로 이 역할을 생성하지는 않습니다. 이 역할이 이미 프로젝트에 설정되어 있다고 가정합니다.

일반적인 방식으로 새로 실행하면 이러한 서브에이전트는 여러분의 대화 기록 전체를 자동으로 받지 않습니다. 여러분과 대화하는 주 에이전트가 서브에이전트를 위한 별도의 작업을 작성합니다. 따라서 "같은 이름의 두 항목은 다른 레코드로 간주된다"와 같은 중요한 요구사항은 작업 지시에 포함되거나 리뷰어가 읽도록 지정된 문서에 포함되어야 합니다. 이 동작은 서브에이전트 컨텍스트 문서에 설명되어 있습니다. 여기서 다루는 것은 사용자 정의 역할의 실행이며, 대화 복사본을 가진 fork가 아닙니다.

"프로젝트를 봐 주세요"와 "항목 삭제 및 카운터 업데이트를 확인하세요. 코드는 변경하지 마세요"를 비교해 보세요. 두 번째 경우, 어디를 봐야 하고 어떤 작업을 기대하지 않는지는 이미 분명합니다. 이제 무엇을 올바른 결과로 볼지만 정하면 됩니다.

짧은 일회성 확인의 경우 메시지로 충분합니다. 기준이 많거나 수정 후 확인을 반복해야 하는 경우, 브리핑을 저장하는 것이 더 편합니다. 10페이지 분량의 별도의 명세서가 아닌, 프로젝트 옆에 두는 짧은 작업 설명입니다. 그것이 없으면 리뷰어가 추측해야 하는 몇 가지 조건입니다.

모든 질문을 예상할 수는 없으며, 그럴 필요도 없습니다. 입력 데이터가 부족하면, 리뷰어는 보고서에서 빈틈을 표시해야 합니다. 주 에이전트가 그 부분을 여러분에게 확인할 수 있습니다. 좋은 작업 지시는 해석의 차이를 줄이지만 좋은 응답을 보장하지는 않습니다. 명확한 작업일 때도 모델이 오류를 범할 수 있습니다.

2. 작업 지시의 네 부분

목표는 어떤 동작을 확인해야 하는지에 대한 질문에 답합니다. 쇼핑 목록 페이지의 경우, 이것은 항목 추가, 삭제 및 카운터입니다. "프로젝트를 더 낫게 하세요"는 너무 광범위합니다. 어떤 개선이 지금 중요한지는 불명확합니다.

입력은 파일과 예상 동작을 나타냅니다. 코드만 보고 같은 이름이 허용되는지 알 수 없다면 app.js의 경로만으로는 부족합니다. 이 제품 결정은 명시적으로 전달되어야 합니다. 무엇으로 확인할지도 함께 적어 두세요. 이 예시에서는 브라우저 없이 코드 읽기만 합니다.

범위는 이 확인을 인접한 작업과 분리합니다. 예를 들어, 스타일, 모바일 보기 및 세션 간 목록 저장은 지금 고려하지 않습니다. 파일은 변경하지 않습니다. 필요한 파일이 없으면, 그에 의존하는 확인 부분을 중지하고 이를 보고합니다. 내용을 추측하지 않습니다.

결과는 받고 싶은 것을 설명합니다. 어디까지 확인했는지, 근거가 있는 발견사항, 제한사항입니다. 반드시 5개의 오류를 찾도록 요구하지 마세요. Claude Code 검토 권장사항에서는 이런 식의 요청이 가진 위험을 별도로 언급합니다. 결함을 찾으라고 지시하면 작업이 올바르게 수행된 곳에서도 지적을 만들어 내게 됩니다.

각 부분은 다른 부분이 주지 못하는 것을 더합니다. 파일 경로는 예상 동작을 정하지 않고, 목표는 수정 금지를 정하지 않습니다. 이 조건들을 한데 모아 리뷰어가 확인할 때 서로 대조할 수 있게 하세요.

그래서 "쇼핑 목록 페이지를 확인해 줘" 대신 다음 작업 지시를 전달합니다. 메시지로 보내거나 프로젝트 루트의 REVIEW_BRIEF.md에 저장할 수 있습니다:

# 쇼핑 목록 확인
목표: 코드로 추가, 삭제, 카운터를 확인한다.
입력: 프로젝트 루트의 index.html과 app.js.
예상: 추가한 항목이 목록에 나타난다.
카운터는 항목 수와 같다. 레코드 하나를 삭제해도
같은 이름의 다른 레코드는 삭제되지 않는다.
범위: 파일은 변경하지 않는다. 스타일, 모바일 화면, 세션 간
목록 저장은 이번 확인에 포함되지 않는다.
필요한 파일이나 요구사항이 부족하면 빈틈을 표시하고,
추측으로 채우지 말고, 가능한 부분에 대한 결과를 반환해.
결과: reviewer 형식을 따르고, 무엇을 확인했는지와
무엇이 확인되지 않았는지 표시해. 발견사항이 없어도 된다.

reviewer 형식은 바로 아래에서 다룹니다. 여러분의 역할에 아직 고정된 형식이 없다면, 같은 일회성 메시지에 포함할 수 있습니다. 필드 이름은 꼭 이대로일 필요가 없습니다. 중요한 것은 필드 덕분에 빠뜨리지 않게 되는 정보입니다.

"보고서에서 가장 중요한 발견 3개를 먼저 보여 줘"라는 요청은 응답의 분량을 제한할 뿐, 확인의 깊이를 제한하지 않습니다. 이런 제한이 필요하다면 다른 발견사항이 더 있는지도 따로 알려 달라고 요청하세요. 세 번째 지적 후에 멈추고 작업을 확인했다고 선언해서는 안 됩니다.

3. 파일에 저장할 사항

특정 작업의 조건은 바뀝니다. 오늘은 카운터를 확인하고, 내일은 목록 저장을 확인합니다. 이런 조건은 브리핑에 둡니다. 반면 오류의 위치와 근거를 보여 달라는 요청은 거의 모든 리뷰에서 필요합니다. 이것은 역할 지침에 한 번 적어 두는 편이 낫습니다.

Output contract, 즉 결과 계약은 여기서 합의된 응답 형식을 뜻합니다. 이름은 실제보다 거창하게 들립니다. 리뷰어를 위한 평범한 지침일 뿐이며, Claude Code의 특수 설정도 자동 품질 확인도 아닙니다. 형식은 보고서에서 필요한 정보를 찾는 데 도움이 되지만, 그 정보가 신뢰할 수 있음을 보장하지는 않습니다.

위쪽 두 부분은 서로 다른 것을 맡습니다. 브리핑은 확인할 내용을 정하고, 역할 지침은 보고서 형식까지 정합니다. 리뷰어가 저장된 브리핑을 사용하게 하려면 파일을 읽으라고 지시하세요. 스스로 그 파일을 열어 보지는 않습니다. 아래쪽에 나오는 보고서는 근거와 완전성을 여러분이 다시 평가해야 합니다.

다음은 기존 역할 파일 .claude/agents/reviewer.md의 텍스트 부분, 즉 설정 다음에 추가할 수 있는 섹션입니다:

## 결과 형식
확인한 파일과 기준을 적어.
각 발견사항마다: 위치, 예상 동작, 근거,
확인 조건과 영향. 우선순위는 이유를 설명해.
코드로 확인된 것과 확인되지 않은 추측을 구분해.
제한사항과 부족한 데이터는 따로 밝혀.
기준에 따른 문제를 찾지 못했으면 그렇게 적어.

이것은 지침의 일부일 뿐, 서브에이전트 파일 전체가 아닙니다. 이 역할은 읽기와 검색만 하므로 고정된 "변경된 파일" 필드는 필요 없습니다. 더 넓은 범위의 보고서라면 변경사항에 대한 내용은 사실을 반영해야 합니다. 실제로 무슨 일이 있었는지와 관계없이 "변경된 파일: 없음"이라는 줄을 미리 정해 둘 수는 없습니다.

브리핑을 저장했다면 주 에이전트에게 다음 요청을 보내세요:

reviewer에게 프로젝트 루트의 REVIEW_BRIEF.md를 읽고
지정된 파일을 그 기준에 따라 확인하라고 지시해.
최종 보고서를 전부 반환해.

파일 이름만 언급한 것이 아니라, 문서를 읽으라고 명시적으로 지시했습니다. 그래도 파일 자체가 무언가를 보장하지는 않습니다. 리뷰어는 여전히 조건을 놓칠 수 있습니다. 저장된 브리핑의 장점은 결과를 대조하고 확인을 반복할 수 있다는 것입니다. 요구사항이 바뀌면 먼저 문서를 업데이트하세요. 그렇지 않으면 다음 패스는 예전 작업을 기준으로 평가하게 됩니다.

4. 보고서를 확인하는 방법

먼저 실제로 확인된 것을 살펴보세요. 브리핑에는 추가, 삭제, 카운터, 같은 이름을 가진 레코드의 독립성이 있었습니다. 보고서가 카운터만 다룬다면, 아직 작업 전체에 대한 결과가 아닙니다. 유일한 발견사항이 완전히 정확하더라도 말이죠.

브리핑의 기준 하나하나를 응답과 대조해 보면 편합니다. 예를 들어, 학습용으로 만든 부분 보고서에서는 이렇게 나왔습니다:

같은 이름에 대한 줄이 없다고 해서 오류가 없다는 뜻은 아닙니다. 또한 카운터에 대한 근거 있는 발견사항 하나가 빠뜨린 작업 부분을 대신하지도 않습니다. 구체적으로 무엇을 보완할지 적어 보고서를 돌려보내세요:

브리핑에는 같은 이름을 가진 두 레코드 중 하나를 삭제하는 경우가 있어.
보고서에는 이 기준이 반영되지 않았어. 사용할 수 있는 수단으로 확인하고
결과의 근거를, 또는 확인하지 못한 이유를 적어 줘.
다른 결론은 그대로 반복할 필요 없어. 코드는 변경하지 마.

중요한 발견사항의 신뢰성은 따로 평가합니다. 지목된 위치, 요구사항, 결론의 근거를 대조하세요. 자세한 예시는 리뷰 보고서 읽기에 관한 글에 있습니다. 여기서는 두 가지 확인이 모두 필요합니다. 작업 범위를 다 다뤘는지, 그리고 결론이 타당한지입니다. 제안된 실행 시나리오는 이미 수행한 테스트와 같지 않습니다.

첫 번째 갈림길에서는 이 작업에 필요한 만큼 확인되었는지 판단합니다. 그렇지 않다면 부족한 부분을 요청하거나, 확인된 부분의 근거도 평가한 뒤 그 부분만 수용합니다. 두 번째 갈림길에서는 근거 있는 결론을 논란의 여지가 있거나 잘못된 결론과 구분합니다. 불분명한 근거는 되물어 보는 것이 좋습니다. 잘못되었음이 입증된 지적이나 작업과 무관한 조언은 거절해도 됩니다.

발견사항이 없는 보고서도 이 확인을 통과할 수 있습니다. 예를 들어: "index.html과 app.js에서 추가 및 삭제 경로, 같은 이름을 가진 레코드의 독립성, 카운터 업데이트를 확인했습니다. 이 기준에서는 문제를 찾지 못했습니다. 브라우저에서 실행하지는 않았습니다". 이런 결론이 프로젝트에 오류가 전혀 없다고 약속하지는 않습니다. 명시된 범위 안의 결과를 알려 줄 뿐이며, 필요하다면 핵심 경로는 여러분이 직접 대조해 봅니다.

반면 "지정된 경로에서 app.js를 찾지 못해 삭제 동작을 확인할 수 없었습니다"는 데이터 부족을 뜻하지, 오류가 없다는 뜻이 아닙니다. 이때는 올바른 경로를 알려 주고 확인을 계속해야 합니다. 짧고 정직한 응답이 빈틈을 숨긴 긴 보고서보다 낫습니다.

보고서를 수용한다고 해서 나열된 것을 모두 고치라고 지시하는 것은 아닙니다. 확인 결과가 근거 있다고 인정했을 뿐이고, 지금 무엇을 변경할지는 따로 결정합니다.

5. 패스가 한 번 더 필요할 때

보고서에 근거가 부족하다고 해서 리뷰를 처음부터 다시 시작할 필요는 없습니다. 구체적인 빈틈을 짚어 돌려보내세요. 예를 들어, 카운터에 대한 발견사항의 축약된 버전에는 호출 분석 없이 오류 이름만 있습니다. 그러면 주 에이전트에게 보내는 요청은 이렇게 될 수 있습니다:

reviewer에게 보고서를 보완하라고 돌려보내. 카운터 발견사항에
삭제 후 카운터가 업데이트되는 경로가 나와 있지 않아.
이 경로를 확인하고 결론의 근거를 추가하게 해.
코드는 변경하지 않는다.

업데이트가 이미 다른 함수에서 일어나고 있다고 밝혀지면, 그 지적은 철회해야 합니다. 이전의 항목 수를 맞추려고 대신할 지적을 찾을 필요는 없습니다. 오류가 확인되면 주 에이전트에게 별도의 요청으로 수정을 맡기면서, 해당 발견사항과 허용되는 변경 범위를 지정할 수 있습니다.

수정 후에는 같은 브리핑으로 패스를 한 번 더 하는 것도 유용합니다:

reviewer에게 REVIEW_BRIEF.md를 다시 읽고 현재 코드의
삭제와 카운터를 확인하라고 지시해. 이전 발견사항:
삭제 후 카운터가 업데이트되지 않았음.
문제가 해결되었는지, 결론이 무엇에 근거하는지 적게 하고,
같은 이름을 가진 레코드의 독립성이 영향을 받지 않았는지도
확인하게 해. 코드는 변경하지 않는다.

이제 구체적인 질문의 답을 찾습니다. 문제가 해결되었는지, 그리고 수정이 건드렸을 수 있는 인접 동작이 망가지지 않았는지입니다. 페이지에서의 동작을 확인하려면 브라우저에서 같은 시나리오를 반복하세요. 재리뷰를 코드만으로 했다면 이 제한은 새 보고서에도 그대로 남습니다.

보고서는 더 짧아질 수도, 길어질 수도, 새로운 발견사항이 없을 수도 있습니다. 성공은 거기에 있지 않습니다. 중요한 것은 이전 결함이 해결되었고, 결론이 현재 코드에 근거하며, 확인되지 않은 부분이 계속 드러나 있는 것입니다. 수정을 미루기로 했나요? 그렇다면 확인된 발견사항과 미루는 이유를 기록해 두세요. 바뀌지 않은 코드를 새 답변을 얻으려고 다시 리뷰할 이유는 없습니다.

6. 작업 지시에서 확인된 결과까지

Claude Code로 작업할 때 브리핑은 주 에이전트가 리뷰어에게 작업을 넘기는 동안 여러분의 기대를 지켜 줍니다. 고정된 형식은 응답을 읽기 쉽게 만듭니다. 하지만 여러분이 참여해야 하는 부분은 여전히 있고, 구체적으로는 다음과 같습니다:

• 주 에이전트는 작업 지시를 작성해 적절한 역할에 전달합니다. 여러분은 예상 동작과 범위를 정합니다.
• 리뷰어는 파일을 살펴보고 결론의 근거를 반환합니다. 범위와 중요한 발견사항을 확인하는 것은 여러분의 몫입니다.
• 주 에이전트는 별도의 작업 지시로 보고서를 보완하거나 확인된 오류를 수정할 수 있습니다. 무엇을 변경하고 결과를 어떻게 확인할지는 여러분이 결정합니다.

쇼핑 목록의 경우 결과는 "함수 호출을 추가해"라는 단순한 조언이 아니라 확인된 설명입니다. 어떤 동작에서 숫자가 어긋났는지, 어디서 업데이트가 끊겼는지, 수정 후 무엇이 달라졌는지. 이런 결과라면 바로 작업에 쓸 수 있습니다.