에이전트 작성 컨벤션

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

Section 0: 포지셔닝

스킬 vs 에이전트 차이

적용 범위

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

Section 1: Frontmatter

필수 필드

선택 필드

description 작성 패턴

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

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

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

필수 요소:

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

model 선택 가이드

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

Section 2: 본문 구조

표준 섹션 순서

정체성 선언 규칙

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

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

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

출력 3-Tier 심각도

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

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

아카이브 규칙

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

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항목)

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

적용 이력