템플릿 선택

용도	템플릿
최소 시작	`templates/basic-agent.py`
커스텀 도구	`templates/tool-agent.py`
훅 (검증/로깅)	`templates/hook-agent.py`
서브에이전트	`templates/multi-agent.py`
프로덕션	`templates/production-agent.py`

프로젝트 구조 생성

{project}/
├── pyproject.toml
├── agent.py          # 메인 에이전트
├── tools.py          # 커스텀 도구 (선택)
└── hooks.py          # 훅 정의 (선택)

코드 생성: 템플릿 기반으로 사용자 요구에 맞게 수정

워크플로우 2: 기능 추가

기존 에이전트에 기능 추가 시:

키워드 → 리소스 매칭

키워드	리소스
설치, pyproject	`resources/01-setup.md`
query, 기본, 옵션	`resources/02-query-options.md`
도구, @tool	`resources/03-custom-tools.md`
훅, hook, 검증	`resources/04-hooks.md`
서브에이전트, 위임	`resources/05-subagents.md`
세션, resume	`resources/06-sessions.md`
MCP, playwright	`resources/07-mcp.md`

리소스 로드 → 패턴 적용

워크플로우 3: 코드 리뷰/개선

기존 에이전트 코드 분석 요청 시:

구조 확인: 현재 사용 중인 기능 파악
개선점 제안:
- 에러 핸들링 추가
- 훅으로 검증/로깅
- 서브에이전트로 분리
- 세션 관리 추가

핵심 패턴

기본 query()

from claude_agent_sdk import query, ClaudeAgentOptions

async for msg in query(
    prompt="작업 지시",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash"],
        cwd="/path/to/project",
        permission_mode="acceptEdits"
    )
):
    if hasattr(msg, "result"):
        print(msg.result)

커스텀 도구

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("search", "검색 수행", {"query": str})
async def search(args):
    return {"content": [{"type": "text", "text": f"결과: {args['query']}"}]}

server = create_sdk_mcp_server("my-tools", "1.0.0", tools=[search])

훅

async def validate_bash(input_data, tool_use_id, context):
    cmd = input_data.get("tool_input", {}).get("command", "")
    if "rm -rf" in cmd:
        return {"decision": "block", "reason": "위험한 명령어"}
    return {}

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[validate_bash])]}
)

중요 원칙

allowed_tools 최소화: 필요한 도구만 허가
permission_mode 신중히: bypassPermissions는 프로덕션 전용
에러 핸들링: try/except로 graceful 처리
세션 활용: 장기 작업은 session_id 저장 후 resume

Technical Details

REFERENCE.md: SDK API 전체 개요
resources/: 기능별 상세 패턴
templates/: 완전한 에이전트 코드

항목	agent-creator	claude-agent-sdk
결과물	`.claude/agents/*.md`	`*.py` 파일
실행 환경	Claude Code 내부	독립 Python 앱
용도	작업 위임	프로덕션 자동화

claude-agent-sdk

Claude Agent SDK

Instructions

워크플로우 1: 새 에이전트 프로젝트