Agent SDK에서 Claude Code 기능 사용

공식 기준: https://code.claude.com/docs/en/agent-sdk/claude-code-features

기준일: 2026-07-26 · CLI 기준 2.1.220

개요

Agent SDK는 Claude Code와 같은 기반 위에 있어, SDK 에이전트도 프로젝트 지침(CLAUDE.md, rules), skills, hooks 등 파일시스템 기반 기능을 사용할 수 있습니다.

settingSources를 생략하면 query()가 CLI와 같이 user/project/local 설정, CLAUDE.md, .claude/ skills·agents·commands를 읽습니다. 프로그램 설정만 쓰려면 settingSources: []를 전달합니다. Managed policy와 전역 ~/.claude.json은 이 옵션과 무관하게 읽힙니다.

핵심 개념

소스	로드 내용	위치
"project"	프로젝트 CLAUDE.md, rules, skills, hooks, settings.json	<cwd>/.claude/ 및 상위 CLAUDE.md/rules/skills
"user"	사용자 CLAUDE.md, rules, skills, settings	~/.claude/
"local"	CLAUDE.local.md, settings.local.json	<cwd> 및 상위

생략 시 ["user", "project", "local"]과 동일합니다. cwd 옵션이 프로젝트 입력 탐색 기준입니다.

상세

settingSources로 파일시스템 설정 제어

Python: setting_sources, TypeScript: settingSources.

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
import asyncio

async def main():
    async for message in query(
        prompt="Help me refactor the auth module",
        options=ClaudeAgentOptions(
            setting_sources=["user", "project"],
            allowed_tools=["Read", "Edit", "Bash"],
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(f"\nResult: {message.result}")

asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Help me refactor the auth module",
  options: {
    settingSources: ["user", "project"],
    allowedTools: ["Read", "Edit", "Bash"]
  }
})) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "text") console.log(block.text);
    }
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log(`\nResult: ${message.result}`);
  }
}

• CLAUDE.md·rules: <cwd>와 모든 상위 디렉터리
• Skills: <cwd>부터 저장소 루트까지 상위
• Project settings.json·hooks: <cwd>/.claude/만 (상위 fallback 없음)

settingSources가 제어하지 않는 입력

입력	동작	비활성 방법
Managed policy settings	MDM/plist/registry/managed file, 조건부 server-managed	호스트에서 제거; server-managed는 org admin 영역
~/.claude.json	항상 읽음	CLAUDE_CONFIG_DIR로 재배치
Auto memory (~/.claude/projects/<project>/memory/)	세션 시작 시 시스템 프롬프트 로드; Write/Edit로 저장	autoMemoryEnabled: false 또는 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
claude.ai MCP connectors	claude.ai 로그인 세션에서 로드 (setup-token만으로는 미로드)	strictMcpConfig: true, disableClaudeAiConnectors: true, 또는 ENABLE_CLAUDEAI_MCP_SERVERS=false

멀티테넌트 격리 경고: 기본 query() 옵션에 의존하지 마세요. 테넌트별 파일시스템 분리 + settingSources: [] + CLAUDE_CODE_DISABLE_AUTO_MEMORY=1을 권장합니다. Server-managed settings는 조직 자격증명 인증 시 여전히 fetch됩니다.

프로젝트 지침 (CLAUDE.md와 rules)

settingSources에 "project"가 있으면 세션 시작 시 로드되어 프롬프트 반복 없이 컨벤션을 따릅니다.

레벨	위치	로드 조건
Project root	<cwd>/CLAUDE.md 또는 <cwd>/.claude/CLAUDE.md	"project"
Project rules	<cwd> 및 상위 .claude/rules/*.md	"project"
Parent CLAUDE.md	cwd 상위	"project", 시작 시
Child CLAUDE.md	cwd 하위	"project", 해당 subtree 파일 읽기 시 on-demand
Local	CLAUDE.local.md	"local"
User	~/.claude/CLAUDE.md, rules	"user"

레벨은 가산적입니다. 충돌 시 Claude 해석에 따르므로 비충돌 규칙을 쓰거나 더 구체적 파일에 우선순위를 명시하세요. CLAUDE.md 없이 systemPrompt로도 컨텍스트 주입 가능합니다.

Skills

Skills는 관련 시점에 on-demand 로드됩니다. 설명은 시작 시 제공됩니다.

skills 옵션 생략 시 발견된 user/project skills가 활성화되고 Skill 도구가 사용 가능합니다(CLI와 동일). "all", 이름 목록, 또는 [](전부 비활성)를 전달할 수 있습니다. skills를 설정하면 SDK가 allowedTools에 Skill을 자동 추가합니다. 명시 tools 목록을 쓰면 "Skill"을 포함하세요.

Skills는 파일시스템 아티팩트(.claude/skills/<name>/SKILL.md)로만 생성합니다. 프로그램 등록 API는 없습니다.

Hooks

두 경로가 병행합니다.

1. Filesystem hooks: settings.json의 shell 등, settingSources로 로드
2. Programmatic hooks: query()에 넘기는 콜백, 프로세스 내 structured decision

둘 다 동일 lifecycle에서 실행됩니다. PreToolUse에서 차단하려면 hookSpecificOutput에 permissionDecision: "deny"와 permissionDecisionReason을 반환합니다. 빈 {}는 허용입니다. 최상위 decision/reason은 PreToolUse에서 deprecated입니다.

타입	적합한 경우
Filesystem	CLI·SDK 공유. command/http/mcp_tool/prompt/agent 지원. 메인·서브에이전트에서 fire
Programmatic	앱 전용 로직·구조화 결정. 서브에이전트에서도 fire. agent_id/agent_type 필드

TypeScript는 Python 대비 SessionStart, SessionEnd, TeammateIdle, TaskCompleted 등 추가 이벤트를 지원합니다.

기능 선택 가이드

목표	사용	SDK 표면
항상 따르는 프로젝트 컨벤션	CLAUDE.md	settingSources: ["project"]
관련 시 참고 자료	Skills	settingSources + skills
재사용 워크플로 (deploy/review)	User-invocable skills	동일
격리 서브태스크	Subagents	agents + allowedTools: ["Agent"]
다중 인스턴스 조율	Agent teams	CLI 기능 (SDK 옵션 직접 설정 아님)
도구 호출 시 결정적 로직	Hooks	hooks 또는 settings scripts
외부 서비스 구조화 도구	MCP	mcpServers

Subagents는 ephemeral·격리(새 대화, 한 작업, 요약 반환). Agent teams는 독립 인스턴스가 task list를 공유하고 직접 메시징합니다. 기능을 켤수록 context window 비용이 늘어납니다.

체크리스트

• 필요한 settingSources를 명시했다 (멀티테넌트면 [])
• managed policy·auto memory·claude.ai connectors 우회 경로를 이해했다
• CLAUDE.md/rules와 skills 경로가 cwd 기준으로 올바른지 확인했다
• hooks는 filesystem vs programmatic 역할을 분리했다
• skills/tools 목록에 Skill 도구 포함 여부를 점검했다

다음 단계

• Agent SDK Skills
• Agent SDK Hooks
• Agent SDK Subagents
• Agent SDK MCP
• 시스템 프롬프트 수정
• 기능 개요