에이전트 작성 컨벤션

04-agents/ 하위 모든 에이전트 정의 파일(*.md)에 적용되는 바인딩 규칙. 재사용 코드 컨벤션(docs/rules/reusable-code.md)과 동일한 체계(포지셔닝 → 규칙 → 체크리스트)로 구성합니다.

Section 0: 포지셔닝

스킬 vs 에이전트 차이

항목	스킬 (03-skills/)	에이전트 (04-agents/)
호출 방식	`/스킬명` 직접 호출 (사용자 트리거)	Agent 도구 (구 Task, v2.1.63 리네임)로 서브에이전트 실행
자율성	사용자 대화 흐름 내 실행	독립 컨텍스트에서 자율 실행 후 결과 반환
컨텍스트	메인 세션 공유 (또는 context:fork)	항상 별도 컨텍스트 (서브프로세스)
정의 위치	`03-skills/{name}/SKILL.md`	`04-agents/{name}.md`
frontmatter	name, description, allowed-tools	name, description, model, color

적용 범위

필수 적용: 04-agents/ 하위 모든 에이전트 정의 파일
참고: 에이전트 정의는 단일 .md 파일 (스킬처럼 디렉토리 구조 불필요)

Section 1: Frontmatter

필수 필드

필드	타입	규칙
`name`	string	kebab-case. `04-agents/` 내 고유
`description`	string	아래 작성 패턴 준수. `<example>` 태그 2개 이상 포함
`model`	string	`opus`, `sonnet`, `haiku` 중 택 1
`color`	string	터미널 표시 색상

선택 필드

필드	타입	규칙
`tools`	string	허용 도구 목록 (쉼표 구분). 미지정 시 전체 상속
`disallowedTools`	string	상속에서 제외할 도구
`memory`	string	`user` \| `project` \| `local` — 세션 간 영속 메모리
`background`	boolean	`true`면 항상 백그라운드 실행
`isolation`	string	`worktree`면 격리된 git worktree에서 실행
`maxTurns`	number	최대 에이전트 턴 수
`skills`	list	사전 로드할 스킬 (전체 내용 주입)
`mcpServers`	string	사용 가능한 MCP 서버
`hooks`	object	에이전트 수명주기 hooks

description 작성 패턴

에이전트의 description은 Claude Code가 Task 도구로 자동 매칭할 때 사용됩니다. 스킬과 달리 영문으로 작성하며, <example> 태그를 포함합니다.

Use this agent when {발동 조건 설명}. This agent {에이전트가 하는 일}. {추가 트리거 조건}.

<example>
Context: {상황 설명}
user: "{사용자 요청 예시}"
assistant: "{어시스턴트 응답 예시}"
</example>

필수 요소:

"Use this agent when..." 패턴으로 시작
<example> 태그 2개 이상
각 example에 Context, user, assistant 포함

model 선택 가이드

모델	용도	예시
`opus`	복잡한 추론, 아키텍처 분석	(현재 해당 에이전트 없음)
`sonnet`	코드 리뷰, 보안 분석, 코드 생성	code-reviewer, security-reviewer, tdd-guide
`haiku`	빠른 분석, 패턴 매칭, 문서 갱신	build-error-resolver, doc-updater

원칙: 가능한 가벼운 모델 선택. 빠른 응답이 중요하면 haiku, 깊은 분석이 필요하면 sonnet.

Section 2: 본문 구조

표준 섹션 순서

#	섹션	필수	설명
1	정체성 선언	O	"You are..." 형태의 역할 정의
2	핵심 역할 / 철학	O	에이전트의 접근 방식 1~2줄
3	프로세스 / 워크플로우	O	단계별 분석/실행 절차
4	출력 형식	O	3-Tier 심각도 기반 출력 구조
5	가이드라인 / 주의사항	권장	행동 원칙
6	아카이브 규칙	권장	`docs/logs/` 기록 조건
7	관련 리소스	선택	참조 파일 테이블
8	호출 경로	O	어떤 스킬/에이전트가 이 에이전트를 호출하는지

정체성 선언 규칙

에이전트 본문 첫 줄은 "You are..." 형태의 정체성 선언입니다:

You are an expert code reviewer with deep expertise across multiple programming languages...

영문으로 작성
전문성 영역을 명시
1~2문장으로 간결하게

출력 3-Tier 심각도

에이전트 출력은 3단계 심각도로 분류합니다:

Tier	기호	의미	행동
Critical	🔴	필수 수정	수정 없이 진행 불가
Important	🟡	권장 수정	수정하지 않으면 위험 증가
Minor	🟢	선택 개선	개선하면 좋지만 필수 아님

추가로 ✨ Positive Observations로 잘된 점을 강조합니다.

아카이브 규칙

에이전트 결과를 docs/logs/YYYY-MM.md에 기록하는 조건:

조건	기록 여부
Critical 1개 이상	필수 기록
Important 3개 이상	필수 기록
Minor만 / 이슈 없음	선택 (사용자 질문)

docs/logs/ 디렉토리가 없으면 아카이브를 건너뜁니다.

호출 경로 테이블

어떤 스킬/에이전트가 이 에이전트를 호출하는지 명시합니다:

## 호출 경로

| 호출자 | 조건 | 방식 |
|--------|------|------|
| `kdyconvention` | HIGH 3+ 위반 시 | 추천 발동 (Task 에이전트) |
| `kdygenesis` | kdyconvention 게이트 경유 | 간접 발동 |

Section 3: 네이밍

에이전트명

kebab-case 사용 (code-reviewer, build-error-resolver)
파일명 = 에이전트명 + .md (code-reviewer.md)
역할을 명확히 드러내는 이름 (동사-명사 또는 명사-명사)

주석 언어

본문(프로세스, 가이드라인 등): 한국어
정체성 선언("You are..."): 영문
출력 형식 예시: 한/영 혼합 허용

Section 4: 품질 체크리스트

생성 시 체크리스트 (6항목)

#	항목	검증 방법
1	frontmatter에 name, description, model, color 4개 필수 필드 존재	패턴 매칭
2	description에 `<example>` 태그 2개 이상 존재	태그 카운트
3	본문에 "You are..." 정체성 선언 존재	패턴 매칭
4	출력 형식에 3-Tier 심각도 (🔴/🟡/🟢) 포함	섹션 확인
5	`## 호출 경로` 테이블 존재	섹션 존재 확인
6	model이 에이전트 복잡도에 적합	수동 판단

리뷰 시 체크리스트 (4항목)

#	항목
1	frontmatter 필수 필드가 Section 1 규칙을 준수하는가?
2	섹션 순서가 Section 2 표준을 따르는가?
3	호출 경로 테이블이 실제 호출 관계와 일치하는가?
4	이 에이전트를 호출하는 스킬/에이전트의 관계 테이블에 기재되어 있는가?

적용 이력

날짜	내용
2026-02-18	초판 작성. 기존 에이전트 6개(code-reviewer, security-reviewer, tdd-guide, build-error-resolver, doc-updater, web-crawler-builder) 패턴 분석 기반