Anthropic Claude Agent SDK & Claude Code

Claude Code — 레퍼런스 하네스

Claude Code는 단순한 AI 코딩 도구가 아닙니다. Anthropic이 에이전트 하네스 설계 원칙을 실제로 구현한 레퍼런스 구현체(reference implementation) 입니다. Claude Code를 분석하면 Anthropic이 생각하는 이상적인 에이전트 하네스 구조를 볼 수 있습니다.

Claude Code의 핵심 구성 요소:

구성 요소	역할	해당 챕터
CLAUDE.md	컨텍스트 엔지니어링	03장 참고
Hooks 시스템	라이프사이클 제어	이 챕터
Tool use	에이전트 도구 인터페이스	04장 참고
MCP 통합	외부 도구 연결	04장 참고
Permission 시스템	안전성 레이어	05장 참고

CLAUDE.md — 컨텍스트 주입

CLAUDE.md는 에이전트가 작업 시작 시 자동으로 읽는 컨텍스트 파일입니다. 프로젝트별, 디렉터리별, 전역별로 계층적으로 적용됩니다.

~/.claude/CLAUDE.md          ← 전역 설정 (모든 프로젝트)
~/project/CLAUDE.md          ← 프로젝트 루트
~/project/src/CLAUDE.md      ← 서브 디렉터리 (작업 범위 한정)

# 프로젝트 CLAUDE.md 예시

## 코드 스타일
- TypeScript strict mode 필수
- 함수형 패턴, 불변성 유지
- 파일당 최대 400줄

## 금지 사항
- console.log 사용 금지 (logger 사용)
- any 타입 사용 금지
- 직접 DOM 조작 금지

## 테스트 정책
- 모든 함수에 unit test 필수
- 커버리지 80% 이상 유지

Hooks 시스템

훅은 도구 실행의 전후에 사용자 정의 로직을 삽입하는 메커니즘입니다. ~/.claude/settings.json에서 설정합니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '실행 예정: ' && cat"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "audit-console-logs.sh"
          }
        ]
      }
    ]
  }
}

훅 스크립트가 exit code 1을 반환하면 도구 실행이 차단됩니다.

#!/bin/bash
# dangerous-command-check.sh (PreToolUse Bash 훅)

# stdin으로 JSON 입력 수신
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.command')

# 위험 패턴 검사
if echo "$COMMAND" | grep -qE 'rm\s+-rf|chmod\s+777|curl.*\|\s*sh'; then
  echo "위험한 명령어 감지: $COMMAND" >&2
  exit 1  # 차단
fi

exit 0  # 허용

Tool Use — Claude API 레벨

Claude API에서 도구는 content block 형태로 주고받습니다.

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const tools: Anthropic.Tool[] = [
  {
    name: "read_file",
    description: "파일 내용을 읽습니다",
    input_schema: {
      type: "object",
      properties: {
        path: { type: "string", description: "읽을 파일 경로" }
      },
      required: ["path"]
    }
  }
];

const response = await client.messages.create({
  model: "claude-opus-4-5",
  max_tokens: 4096,
  tools,
  messages: [{ role: "user", content: "src/index.ts 파일을 읽어주세요" }]
});

// tool_use 블록 처리
for (const block of response.content) {
  if (block.type === "tool_use") {
    const toolResult = await executeTool(block.name, block.input);

    // 결과를 tool_result로 반환
    await client.messages.create({
      model: "claude-opus-4-5",
      max_tokens: 4096,
      tools,
      messages: [
        { role: "user", content: "src/index.ts 파일을 읽어주세요" },
        { role: "assistant", content: response.content },
        {
          role: "user",
          content: [{ type: "tool_result", tool_use_id: block.id, content: toolResult }]
        }
      ]
    });
  }
}

Claude Agent SDK — 멀티에이전트

Claude Agent SDK는 여러 에이전트를 오케스트레이션하는 상위 레벨 인터페이스입니다.

import anthropic

client = anthropic.Anthropic()

def create_subagent(role: str, tools: list) -> dict:
    """서브에이전트 설정 생성"""
    return {
        "model": "claude-opus-4-5",
        "system": f"당신은 {role}입니다. 맡은 작업만 수행하세요.",
        "tools": tools,
        "max_tokens": 8192,
    }

# 오케스트레이터가 서브에이전트에게 작업 위임
orchestrator_response = client.messages.create(
    model="claude-opus-4-5",
    system="당신은 오케스트레이터입니다. 서브에이전트에게 작업을 분배하세요.",
    tools=[
        {
            "name": "delegate_to_agent",
            "description": "서브에이전트에게 작업 위임",
            "input_schema": {
                "type": "object",
                "properties": {
                    "agent_role": {"type": "string"},
                    "task": {"type": "string"}
                },
                "required": ["agent_role", "task"]
            }
        }
    ],
    messages=[{"role": "user", "content": "코드베이스를 분석하고 리팩터링 계획을 세워주세요"}],
    max_tokens=4096,
)

MCP — 외부 도구 통합

Model Context Protocol (MCP) 는 에이전트와 외부 도구/서비스를 표준화된 방식으로 연결하는 프로토콜입니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    }
  }
}

요약

Claude Code는 CLAUDE.md(컨텍스트), 훅 시스템(라이프사이클 제어), Tool use(도구 인터페이스), MCP(외부 연동)가 통합된 레퍼런스 하네스입니다. Anthropic Agent SDK는 이를 기반으로 멀티에이전트 오케스트레이션까지 지원합니다. 에이전트 하네스를 직접 구축할 때 Claude Code의 설계 결정은 최고의 참고 자료입니다.