Claude Code에는 메인 대화와는 별개의 컨텍스트(Context)에서 동작하는 **서브 에이전트 (Sub-agent)**를 정의하는 메커니즘이 있습니다. .claude/agents/ 디렉토리에 Markdown 파일을 두기만 하면 됩니다.

저는 이것을 '리뷰 담당 동료'로 사용하고 있습니다. 블로그 기사 초안을 AI에게 작성하게 한 뒤, 별도의 AI(팩트 체크 담당)에게 공식 문서와 대조하게 한 다음 인간의 리뷰로 넘기는 흐름입니다. 이 기사에서는 실제로 운용 중인 팩트 체크 담당을 예로 들어, 만드는 방법과 주의할 점을 정리합니다.

직접 쓴 본인에게 셀프 체크를 시키면 인간과 마찬가지로 관대해집니다. 생성 당시의 문맥(이렇게 쓰려고 했던 이유)을 그대로 간직한 채 읽기 때문입니다. 서브 에이전트는 메인 대화의 문맥을 가지지 않는 별도의 컨텍스트에서 기동되므로, 초안을 '처음 보는 타인'으로서 읽을 수 있습니다. 또한 툴(Tool) 권한을 제한할 수 있으므로, '지적은 하지만 편집은 할 수 없는' 검사 전담으로 만들 수 있습니다.

파일은 YAML frontmatter + 본문(시스템 프롬프트) 구성입니다.

---
name: ai-fact-check
description: 블로그 기사 초안 내의 AI 관련 사실 기술(모델명, 가격, 기능, 제한 등)
...

이렇게 하면 메인 대화에서 "초안을 팩트 체크해줘"라고 요청하면 (또는 description에 부합하는 상황에서 자동으로) 이 에이전트가 별도의 컨텍스트에서 기동됩니다.

description은 에이전트 자동 기용의 판단 재료입니다. "~을 대조하여 정오를 판정한다"뿐만 아니라, "초안 완성 후, 사용자 리뷰 전에 반드시 사용한다"라는 타이밍까지 작성하면 워크플로우의 정해진 위치에서 안정적으로 호출됩니다.

위의 예시에서는 Read, Grep, Glob, WebFetch, WebSearch만 허용했습니다. Edit나 Write를 부여하지 않았기 때문에, 구조적으로 지적만 할 수 있습니다. 본문에도 "파일 편집은 하지 않는다(지적만 수행)"라고 적어두었지만, 문장으로 된 지시는 깨질 가능성이 제로가 아니므로 권한 측면에서도 제약을 거는 이중화가 안심됩니다.

서브 에이전트의 최종 메시지는 호출 측에 그대로 반환됩니다. 출력 형식을 고정해 두면 호출 측(메인 Claude)이 결과를 기계적으로 처리할 수 있습니다. "판정: 문제 없음/수정 필요"라는 한 줄이 있는 것만으로도, 후속 분기(수정할 것인가, 인간 리뷰로 진행할 것인가)가 안정화됩니다.

정/오의 이지선다로 만들면, 근거를 찾을 수 없는 주장을 억지로 "오류"라고 단정 짓기 쉽습니다. "공식 정보를 찾을 수 없는 것은 미확인으로 처리한다(오류라고 단정 짓지 않는다)"라는 문구 하나로 과도한 지적이 상당히 줄었습니다.

저희 팀에서는 팩트 체크 담당 전에 "공개 안전 체크 담당"(내부 숫자나 개인 식별로 이어질 수 있는 정보가 섞여 있지 않은지 검사)을 거칩니다. 관점마다 에이전트를 나누면 한 명에게 전부 시키는 것보다 지적의 정밀도가 올라갑니다. 인간의 리뷰 체제와 마찬가지입니다.

frontmatter 앞에 제목 등을 쓰지 말 것. frontmatter가 해석되지 않아 description이 무효화됩니다 (1패)

tools를 생략하면 모든 툴을 사용할 수 있는 상태가 됩니다. 리뷰 전담이라면 명시적으로 제한할 것

도메인 지식(예: "이 가격 표기는 우리 회사에서는 세금 포함으로 작성한다")은 에이전트 측에 적어두지 않으면, 올바른 사내 규칙을 "공식 정보와 다르다"라고 지적합니다. 프로젝트 고유의 예외 사항은 에이전트 정의에 명기할 것

.claude/agents/<name>.md (frontmatter + 시스템 프롬프트)만으로 리뷰 담당을 만들 수 있음

description=언제 사용할지, tools=편집 불가, 출력=템플릿 고정, 판정=미확인 포함, 이 조합이 안정적인 운용 패턴

관점별로 나누어 직렬로 통과시키면 인간 리뷰 전의 품질이 크게 향상됨

서브 에이전트 자체에 대한 입문은 블로그에 작성해 두었습니다: Claude Code의 서브 에이전트란 | AI의 "부하" 8명에게 조사를 맡겼더니 하루 업무가 1시간 만에 끝났다