Claude Code의 서브 에이전트(Agent tool / .claude/agents/)에 작업을 위임하면, 검증도 없이 '완료했습니다'라고 돌아오는 경우가 있습니다. 실제로 운영하면서 빈번하게 발생한 이 문제를, 위임 프롬프트 작성법으로 해결합니다.

• 서브 에이전트가 조기 종료하는 4가지 원인

• 위임 프롬프트에 반드시 포함해야 할 5개 항목의 템플릿 (복사/붙여넣기 가능) - 에이전트 정의 파일 측에 넣을 '자가 점검 체크리스트' 예시

• 애초에 위임해야 하는지 판단하는 기준

• Claude Code가 설치되어 있고, 서브 에이전트(Agent tool)를 사용해 본 경험이 있는 경우

• 커스텀 에이전트는 ~/.claude/agents/ 또는 .claude/agents/에 Markdown으로 정의할 수 있습니다.

참고로, 서브 에이전트의 모델을 전환하여 비용을 낮추는 이야기는 다른 글에 작성했습니다 → Claude Code의 Agent tool에서 서브 에이전트 모델을 전환하여 토큰 비용을 낮추기

수개월간 서브 에이전트를 운영하면서 반복적으로 발생한 실패 패턴은 다음 3가지였습니다.

'대충 완성'으로 종료하는 경우 — 지시의 80%만 수행하고 완료 보고를 함 -
검증 없이 완료 보고하는 경우 — build도 test도 실행하지 않고 '구현했습니다' -
에러를 독단적으로 무마하는 경우 — 도중에 에러를 만나면, 보고하지 않고 범위를 임의로 축소하여 완료 처리함

서브 에이전트는 메인 세션과 컨텍스트를 공유하지 않습니다. 우리가 암묵적으로 기대하는 '당연히 테스트가 통하고 돌아오겠지'는 프롬프트에 쓰지 않는 한 존재하지 않는 것이 모든 원인입니다.

위의 4가지 원인을 막기 위해, 위임 프롬프트에 반드시 다음 5개 항목을 넣습니다. 그대로 사용할 수 있는 템플릿입니다.

## 작업
(작업 내용을 1~2문장으로)
## 완료 조건 (모두 충족할 때까지 완료라고 보고하지 말 것)
...

포인트는 두 가지입니다.

완료 조건은 파일명・함수명・커맨드명까지 구체화합니다. '검증을 추가'가 아니라 'parseConfig()를 구현하고 bar.test.ts를 통과시키는'. 모호한 만큼 에이전트는 느슨한 쪽으로 기울어집니다 -
검증 로그의 원시 출력을 보고에 포함시키도록 합니다. '테스트 통과했습니다'라는 자가 신고는 신뢰하지 않고, 로그로 확인합니다

매번 위임 프롬프트 외에도, .claude/agents/ 정의 파일 측에도 반환 전의 자가 점검을 심어두면, 프롬프트 작성 시 빠뜨린 부분을 보완할 수 있습니다.

실제로 운영하는 감사계 에이전트의 정의 파일 끝부분은 다음과 같습니다.

# 체크리스트 (반환 전에 자가 점검)
- [ ] 대상 파일・라이브 페이지・실제 데이터를 실제로 획득했음 (기억으로 판단하지 않음)
- [ ] 각 지적에 근거를 첨부함 (불명확한 것은 '판단 필요'라고 명시함)
...

특히 효과적인 것은 마지막 항목입니다. '본 범위의 목록'을 보고하게 하면, '모두 확인했습니다(실제로는 일부)'라는 포괄성의 오인식을 우리가 감지할 수 있습니다.

템플릿 이전의 문제로, 위임하지 않는 편이 빠른 태스크를 위임하고 있는 경우도 많았습니다. 서브 에이전트는 컨텍스트 비공유이기 때문에, 상황 설명을 하는 비용이 매번 발생합니다. 운영 결과, 위임에 구조적 이점이 있는 것은 다음 3가지 유형뿐이었습니다.

템플릿과 병용하여 효과가 있었습니다.

• 체크리스트 기반으로 운영하기 — 「먼저 태스크의 체크리스트를 작성하고, 각 항목이 완료될 때마다 업데이트할 것」이라고 지시한다. 진척도가 구조화되어 중간에 포기하는 상황을 파악하기 쉬워진다.

• worktree로 격리하기 — 파일을 변경하게 할 경우 git worktree 상에서 작업하게 하면, 실패하더라도 메인 환경이 오염되지 않아 재시도(retry)가 안전해진다.

• 작게 나누어 위임하기 — 1 에이전트 = 1 파일 변경 정도까지 분해한다. 범위를 크게 넘길수록 「대충 완성」할 여지가 생긴다.

• 서브 에이전트의 조기 종료는,
  완료 조건 · 검증 · 금지 사항 · 막혔을 때의 행동 · 보고 포맷의 5가지 항목을 프롬프트에 명시하면 대부분 방지할 수 있다. 검증은 「실행한 로그의 생출력(raw output)」으로 확인한다. 자기 보고(self-reporting)는 신뢰하지 않는다.

• 판단이 필요한 태스크를 하위 모델에 넘기지 않는다.

• 애초에 위임은 「대량 읽기 · 독립 검증 · 병렬 배치(batch)」의 3가지 유형으로 한정하고, 그 외에는 메인 세션에서 직접 수행한다.

서브 에이전트를 「부서」로 간주한 조직 운영 설계론은 이곳에 정리되어 있습니다 → 「AI 조직」은 조직도부터 만들면 실패한다｜1인 회사를 AI 회사로 만드는 올바른 순서

SEO 스코어 체크 도구: SEO_CHECK — RINIA 디렉터 도구.

웹 제작 · SEO 관련 기술 정보 사이트: CodeQuest.work