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% 이상 유지

CLAUDE.md의 동적 적용

Claude Code는 현재 작업 디렉터리를 기준으로 CLAUDE.md를 찾습니다. 서브에이전트가 다른 디렉터리에서 작업하면 해당 디렉터리의 CLAUDE.md가 적용됩니다. 이를 통해 모노레포에서 패키지별로 다른 규칙을 적용할 수 있습니다.

Hooks 시스템

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

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-command.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format-file.py"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "audit-console-logs.sh"
          }
        ]
      }
    ]
  }
}

위 스크립트에는 jq가 필요합니다. PreToolUse command 훅은 종료 코드 2로 실행을 차단하고 stderr를 Claude에 전달합니다. 0은 성공이며, 다른 비영 종료 코드는 기본적으로 차단하지 않는 오류입니다. 이벤트별 의미는 공식 훅 명세를 확인합니다.

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

# stdin으로 JSON 입력 수신
INPUT=$(cat)
COMMAND=$(printf '%s' "$INPUT" | jq -er '.tool_input.command | strings') || {
  echo "Invalid hook input" >&2
  exit 2
}

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

exit 0  # 허용

PostToolUse의 파일 경로도 환경 변수 대신 stdin JSON의 tool_input.file_path에서 읽습니다. 다음은 위 설정이 호출하는 포맷 스크립트입니다.

.claude/hooks/format-file.py

import json
import subprocess
import sys

file_path = json.load(sys.stdin).get("tool_input", {}).get("file_path")
if file_path:
    subprocess.run(["npx", "prettier", "--write", file_path], check=True)

도구별 입력 스키마가 다르므로 matcher와 JSON 경로를 함께 확인합니다. 위 위험 명령 정규식은 설명용 필터이며, 우회 가능한 문자열 검사만으로 셸을 격리할 수는 없습니다.

Tool Use — Claude API 레벨

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

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

const client = new Anthropic();
const model = process.env.ANTHROPIC_MODEL;
if (!model) throw new Error('Set ANTHROPIC_MODEL to an available model ID');

const tools: Anthropic.Tool[] = [{
  name: 'read_file',
  description: 'Read an authorized workspace file',
  input_schema: {
    type: 'object',
    properties: { path: { type: 'string' } },
    required: ['path'],
  },
}];
const messages: Anthropic.MessageParam[] = [
  { role: 'user', content: 'src/index.ts 파일을 읽어주세요' },
];

for (let turn = 0; turn < 10; turn++) {
  const response = await client.messages.create({ model, max_tokens: 4096, tools, messages });
  messages.push({ role: 'assistant', content: response.content });
  if (response.stop_reason !== 'tool_use') break;

  const results: Anthropic.ToolResultBlockParam[] = [];
  for (const block of response.content) {
    if (block.type !== 'tool_use') continue;
    // executeTool은 별도로 구현하며 입력 검증·경로 제한·승인을 담당합니다.
    const result = await executeTool(block.name, block.input);
    results.push({ type: 'tool_result', tool_use_id: block.id, content: result });
  }
  messages.push({ role: 'user', content: results });
}

병렬 tool_use가 있으면 해당 응답의 모든 결과를 같은 후속 사용자 메시지에 반환합니다. 위 코드는 Messages API 루프를 설명하는 단편이며, Agent SDK와 달리 도구 실행기를 직접 구현합니다.

Claude Agent SDK — 멀티에이전트

Claude Agent SDK는 Claude Code의 실행 루프, 내장 도구, 컨텍스트 관리를 Python·TypeScript 애플리케이션에서 사용하게 합니다. 일반 anthropic Messages SDK 호출과 다른 패키지입니다.

pip install claude-agent-sdk

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Agent", "Read", "Glob", "Grep"],
        agents={
            "reviewer": AgentDefinition(
                description="코드 검토가 필요할 때 사용합니다",
                prompt="파일을 읽고 검토 의견을 보고하세요. 파일은 수정하지 마세요.",
                tools=["Read", "Glob", "Grep"],
            ),
        },
        max_turns=10,
    )
    async for message in query(
        prompt="reviewer에게 코드베이스 분석을 맡기고 개선 계획을 정리하세요.",
        options=options,
    ):
        print(message)

asyncio.run(main())

SDK 인증을 구성한 실습 프로젝트에서 실행합니다. agents의 설명은 모델이 서브에이전트를 선택할 때 사용하며, Agent 도구로 위임합니다. 도구 노출·자동 승인 목록은 OS 샌드박스를 대신하지 않습니다.

MCP — 외부 도구 통합

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

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    }
  }
}

MCP의 장점

MCP를 사용하면 도구 구현 없이 기존 서버를 에이전트에 연결할 수 있습니다. 파일 시스템, GitHub, 데이터베이스, Slack 등 수백 개의 기존 MCP 서버가 오픈소스로 공개되어 있습니다.

요약

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