Claude Code 플러그인을 위한 에이전트 개발
개요
에이전트는 복잡한 다단계 작업을 독립적으로 처리하는 자율적인 하위 프로세스입니다. 에이전트 구조, 트리거 조건, 시스템 프롬프트 설계를 이해하면 강력한 자율 기능을 만들 수 있습니다.
핵심 개념:
- 에이전트는 자율 작업을 위한 것이고, 명령어는 사용자 주도 작업을 위한 것입니다.
- YAML 프론트매터가 포함된 마크다운 파일 형식
- 설명 필드와 예시를 통한 트리거링
- 시스템 프롬프트가 에이전트 동작을 정의
- 모델 및 색상 사용자 지정
에이전트 파일 구조
전체 형식
---
name: agent-identifier
description: 다음 상황에서 이 에이전트를 사용하세요. [트리거 조건]. 예시:
<example>
Context: [상황 설명]
user: "[사용자 요청]"
assistant: "[어시스턴트가 응답하고 이 에이전트를 사용하는 방법]"
<commentary>
[이 에이전트가 트리거되어야 하는 이유]
</commentary>
</example>
<example>
[추가 예시...]
</example>
model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---
당신은 [에이전트 역할 설명]입니다...
**귀하의 핵심 책임:**
1. [책임 1]
2. [책임 2]
**분석 프로세스:**
[단계별 워크플로우]
**출력 형식:**
[반환할 내용]
프론트매터 필드
name (필수)
에이전트 식별자로, 네임스페이싱 및 호출에 사용됩니다.
형식: 소문자, 숫자, 하이픈만 가능 길이: 3-50자 패턴: 영숫자로 시작하고 끝나야 함
좋은 예시:
code-reviewertest-generatorapi-docs-writersecurity-analyzer
나쁜 예시:
helper(너무 일반적)-agent-(하이픈으로 시작/끝)my_agent(밑줄 허용 안 됨)ag(너무 짧음, 3자 미만)
description (필수)
Claude가 이 에이전트를 트리거해야 하는 시점을 정의합니다. 가장 중요한 필드입니다.
다음을 포함해야 합니다:
- 트리거 조건 ("다음 상황에서 이 에이전트를 사용하세요...")
- 사용법을 보여주는 여러 개의
<example>블록 - 각 예시의 컨텍스트, 사용자 요청, 어시스턴트 응답
- 에이전트가 트리거되는 이유를 설명하는
<commentary>
형식:
다음 상황에서 이 에이전트를 사용하세요. [조건]. 예시:
<example>
Context: [시나리오 설명]
user: "[사용자가 말한 내용]"
assistant: "[Claude가 응답해야 하는 방식]"
<commentary>
[이 에이전트가 적합한 이유]
</commentary>
</example>
[추가 예시...]
모범 사례:
- 2-4개의 구체적인 예시 포함
- 능동적 및 반응적 트리거링 모두 보여주기
- 동일한 의도의 다양한 표현 다루기
- 설명(commentary)에서 추론 설명
- 에이전트를 사용하지 말아야 할 상황을 구체적으로 명시
model (필수)
에이전트가 사용할 모델입니다.
옵션:
inherit- 상위와 동일한 모델 사용 (권장)sonnet- Claude Sonnet (균형)opus- Claude Opus (가장 강력하고, 비용 높음)haiku- Claude Haiku (빠르고, 저렴)
권장: 특정 모델 기능이 필요한 경우가 아니라면 inherit을 사용하세요.
color (필수)
UI에서 에이전트의 시각적 식별자입니다.
옵션: blue, cyan, green, yellow, magenta, red
지침:
- 동일한 플러그인 내 다른 에이전트와 구별되는 색상 선택
- 유사한 에이전트 유형에 일관된 색상 사용
- Blue/cyan: 분석, 검토
- Green: 성공 지향적 작업
- Yellow: 주의, 검증
- Red: 중요, 보안
- Magenta: 창의적, 생성
tools (선택 사항)
에이전트를 특정 도구로 제한합니다.
형식: 도구 이름의 배열
tools: ["Read", "Write", "Grep", "Bash"]
기본값: 생략하면 에이전트가 모든 도구에 접근 가능
모범 사례: 필요한 최소 도구로 제한 (최소 권한 원칙)
일반적인 도구 세트:
- 읽기 전용 분석:
["Read", "Grep", "Glob"] - 코드 생성:
["Read", "Write", "Grep"] - 테스팅:
["Read", "Bash", "Grep"] - 전체 접근: 필드 생략 또는
["*"]사용
시스템 프롬프트 설계
마크다운 본문은 에이전트의 시스템 프롬프트가 됩니다. 에이전트를 직접 지칭하는 2인칭으로 작성하세요.
구조
표준 템플릿:
당신은 [도메인]을 전문으로 하는 [역할]입니다.
**귀하의 핵심 책임:**
1. [주요 책임]
2. [부차적 책임]
3. [추가 책임...]
**분석 프로세스:**
1. [1단계]
2. [2단계]
3. [3단계]
[...]
**품질 기준:**
- [기준 1]
- [기준 2]
**출력 형식:**
다음 형식으로 결과를 제공하세요:
- [포함할 내용]
- [구성 방법]
**엣지 케이스:**
다음 상황을 처리하세요:
- [엣지 케이스 1]: [처리 방법]
- [엣지 케이스 2]: [처리 방법]
모범 사례
✅ 해야 할 것:
- 2인칭으로 작성 ("당신은...", "당신은 할 것입니다...")
- 책임을 구체적으로 명시
- 단계별 프로세스 제공
- 출력 형식 정의
- 품질 기준 포함
- 엣지 케이스 다루기
- 10,000자 미만 유지
❌ 하지 말아야 할 것:
- 1인칭으로 작성 ("나는...", "내가 할 것은...")
- 모호하거나 일반적으로 작성
- 프로세스 단계 생략
- 출력 형식을 정의하지 않음
- 품질 지침 건너뛰기
- 오류 사례 무시
에이전트 생성
방법 1: AI 지원 생성
이 프롬프트 패턴을 사용하세요 (Claude Code에서 추출):
다음 요청을 기반으로 에이전트 구성을 만드세요: "[설명 입력]"
요구 사항:
1. 핵심 의도와 책임 추출
2. 해당 도메인에 대한 전문가 페르소나 설계
3. 다음을 포함한 포괄적인 시스템 프롬프트 생성:
- 명확한 행동 경계
- 특정 방법론
- 엣지 케이스 처리
- 출력 형식
4. 식별자 생성 (소문자, 하이픈, 3-50자)
5. 트리거 조건을 포함한 설명 작성
6. 사용 시기를 보여주는 2-3개의 <example> 블록 포함
JSON 반환:
{
"identifier": "agent-name",
"whenToUse": "다음 상황에서 이 에이전트를 사용하세요... 예시: <example>...</example>",
"systemPrompt": "당신은..."
}
그런 다음 프론트매터가 있는 에이전트 파일 형식으로 변환하세요.
전체 템플릿은 examples/agent-creation-prompt.md를 참조하세요.
방법 2: 수동 생성
- 에이전트 식별자 선택 (3-50자, 소문자, 하이픈)
- 예시가 포함된 설명 작성
- 모델 선택 (보통
inherit) - 시각적 식별을 위한 색상 선택
- 도구 정의 (액세스 제한 시)
- 위 구조로 시스템 프롬프트 작성
agents/agent-name.md로 저장
유효성 검사 규칙
식별자 유효성 검사
✅ 유효함: code-reviewer, test-gen, api-analyzer-v2
❌ 무효함: ag (너무 짧음), -start (하이픈으로 시작), my_agent (밑줄)
규칙:
- 3-50자
- 소문자, 숫자, 하이픈만 가능
- 영숫자로 시작하고 끝나야 함
- 밑줄, 공백, 특수 문자 없음
설명 유효성 검사
길이: 10-5,000자 다음을 포함해야 함: 트리거 조건 및 예시 최적: 200-1,000자, 2-4개의 예시 포함
시스템 프롬프트 유효성 검사
길이: 20-10,000자 최적: 500-3,000자 구조: 명확한 책임, 프로세스, 출력 형식
에이전트 구성
플러그인 에이전트 디렉토리
plugin-name/
└── agents/
├── analyzer.md
├── reviewer.md
└── generator.md
agents/ 디렉토리 내의 모든 .md 파일은 자동으로 검색됩니다.
네임스페이싱
에이전트는 자동으로 네임스페이스가 지정됩니다:
- 단일 플러그인:
agent-name - 하위 디렉토리 포함:
plugin:subdir:agent-name
에이전트 테스트
트리거 테스트
에이전트가 올바르게 트리거되는지 확인하는 테스트 시나리오를 만드세요:
- 특정 트리거 예시가 있는 에이전트 작성
- 테스트에서 예시와 유사한 표현 사용
- Claude가 에이전트를 로드하는지 확인
- 에이전트가 예상 기능을 제공하는지 확인
시스템 프롬프트 테스트
시스템 프롬프트가 완전한지 확인하세요:
- 에이전트에게 일반적인 작업 부여
- 프로세스 단계를 따르는지 확인
- 출력 형식이 올바른지 확인
- 프롬프트에 언급된 엣지 케이스 테스트
- 품질 기준이 충족되는지 확인
빠른 참조
최소 에이전트
---
name: simple-agent
description: 다음 상황에서 이 에이전트를 사용하세요... 예시: <example>...</example>
model: inherit
color: blue
---
당신은 [X]를 수행하는 에이전트입니다.
프로세스:
1. [1단계]
2. [2단계]
출력: [제공할 내용]
프론트매터 필드 요약
| 필드 | 필수 여부 | 형식 | 예시 |
|---|---|---|---|
| name | 예 | 소문자-하이픈 | code-reviewer |
| description | 예 | 텍스트 + 예시 | 다음 상황에서 사용... ... |
| model | 예 | inherit/sonnet/opus/haiku | inherit |
| color | 예 | 색상 이름 | blue |
| tools | 아니요 | 도구 이름 배열 | ["Read", "Grep"] |
모범 사례
해야 할 것:
- ✅ 설명에 2-4개의 구체적인 예시 포함
- ✅ 구체적인 트리거 조건 작성
- ✅ 특별한 필요가 없으면 모델에
inherit사용 - ✅ 적절한 도구 선택 (최소 권한)
- ✅ 명확하고 구조화된 시스템 프롬프트 작성
- ✅ 에이전트 트리거링 철저히 테스트
하지 말아야 할 것:
- ❌ 예시 없는 일반적인 설명 사용
- ❌ 트리거 조건 생략
- ❌ 모든 에이전트에 동일한 색상 부여
- ❌ 불필요한 도구 접근 권한 부여
- ❌ 모호한 시스템 프롬프트 작성
- ❌ 테스트 건너뛰기
추가 리소스
참조 파일
자세한 지침은 다음을 참조하세요:
references/system-prompt-design.md- 완전한 시스템 프롬프트 패턴references/triggering-examples.md- 예시 형식 및 모범 사례references/agent-creation-system-prompt.md- Claude Code의 정확한 프롬프트
예시 파일
examples/ 디렉토리의 작업 예시:
agent-creation-prompt.md- AI 지원 에이전트 생성 템플릿complete-agent-examples.md- 다양한 사용 사례에 대한 전체 에이전트 예시
유틸리티 스크립트
scripts/ 디렉토리의 개발 도구:
validate-agent.sh- 에이전트 파일 구조 유효성 검사test-agent-trigger.sh- 에이전트가 올바르게 트리거되는지 테스트
구현 워크플로우
플러그인용 에이전트를 생성하려면:
- 에이전트 목적 및 트리거 조건 정의
- 생성 방법 선택 (AI 지원 또는 수동)
agents/agent-name.md파일 생성- 필요한 모든 필드로 프론트매터 작성
- 모범 사례에 따라 시스템 프롬프트 작성
- 설명에 2-4개의 트리거 예시 포함
scripts/validate-agent.sh로 유효성 검사- 실제 시나리오로 트리거 테스트
- 플러그인 README에 에이전트 문서화
자율 운영을 위한 명확한 트리거 조건과 포괄적인 시스템 프롬프트에 집중하세요.