AGENTS.md 심화

AGENTS.md의 명세 포맷, 도구별 구현 방식, 작성 원칙, 검증 절차를 정리한다. 5장에서 개념적으로 소개한 AGENTS.md를 실무 관점에서 심화한다.

표준 명세: agents.md · 실습 예시: 4장 §2-A / 4장 §2-B

명세 포맷

AGENTS.md의 각 에이전트 항목은 ## Agent: {이름}으로 시작하는 마크다운 섹션이다. 이 섹션 안에 역할·입력·출력·권한·handoff 등의 필드를 자유 형식으로 기술한다. 표준 명세는 strict schema를 강제하지 않고, 도구가 공통으로 인식하는 관례(convention)에 의존한다.

완성 예시

4장 실습(G-1, D-1)에서 작성한 두 에이전트가 들어간 AGENTS.md 전체 모습이다.

## Agent: reviewer

역할: 텍스트 파일의 오탈자, 논리적 허점, 개선점을 검토한다.
입력: 검토 대상 텍스트 파일 경로
출력: 오탈자 · 논리적 허점 · 개선점 목록
권한: 읽기 전용 — 파일을 직접 수정하지 않는다.

## Agent: writer

역할: 주어진 주제로 3~5문장 분량의 짧은 초안을 작성한다.
입력: 주제, 저장할 파일 경로
출력: 초안 텍스트 파일
권한: 쓰기 허용 — 지정된 파일에만 저장한다.
handoff_to: reviewer (초안 완료 후 검토로 이어짐)

도구별 구현 매핑

AGENTS.md는 도구 중립적인 공통 명세다. 하지만 실제로 서브에이전트를 "구현"하는 방식은 Claude 계열, Antigravity 계열, Codex 계열에서 서로 다르다.

작성 가이드

1. 섹션으로 시작

## Agent: {이름}으로 에이전트 항목을 시작한다. 이름은 영문 소문자로 하되 여러 단어는 -로 연결한다(code-reviewer, api-tester). 이 이름이 Claude 계열에서는 subagent_type 값으로 사용된다.

2. 역할을 간결하게

역할은 "무엇을 하는가"를 1~2문장으로 명확히 기술한다. 다른 에이전트와의 중복을 피하고, 각 에이전트가 독립적으로 책임지는 영역이 명확하도록 한다.

3. 최소 권한으로 권한 설정

권한 필드는 파일 접근 범위를 제한한다. 이 원칙을 지키지 않으면 서브에이전트가 실수로 중요 파일을 덮어쓰 수 있다. Claude 계열에서는 이 권한이 .claude/agents/*.md의 tools 필드(Read, Grep, Write 등)로 번역된다.

4. handoff로 선후 관계 선언

handoff_to는 "이 에이전트가 작업을 마치면 결과를 어디로 넘길 것인가"를 선언한다. 이것은 명령이 아니라 힌트다. 실제로 순차 파이프라인을 구성하는 것은 메인 세션(오케스트레이터)의 몫이다.

## Agent: draft-writer
역할: 주어진 주제로 초안을 작성한다.
handoff_to: reviewer (초안 완료 후 검토로 이어짐)

## Agent: reviewer
역할: 텍스트의 오탈자와 논리를 검토한다.
handoff_to: editor (검토 완료 후 최종 편집으로 이어짐)

## Agent: editor
역할: 피드백을 반영해 최종 문서를 완성한다.

5. 검증

작성이 완료되면 bun run agent:verify로 구조를 검증한다. 이 스크립트는 에이전트 frontmatter의 완결성, 필수 섹션 존재, AGENTS.md 로스터와의 정합성을 확인한다.

검증과 생애주기

AGENTS.md에 에이전트를 등록하는 것은 생애주기의 Create 단계에 해당한다(8장 §2 참조). 등록된 에이전트는 다음 단계를 거친다.

에이전트를 새로 만들거나 변경할 때마다 agent:verify를 실행하는 것을 습관화하면, "로스터에는 있는데 실제 정의 파일이 없는" 또는 "handoff_to가 가리키는 에이전트가 삭제된" 같은 불일치를 조기에 발견할 수 있다.

이 검증 흐름의 자동화는 8장 §1(배포와 SSOT)에서 다루는 CI/CD 파이프라인에 validate-templates.ts 단계로 통합할 수 있다.