Command → Agent → Skill 아키텍처

Command → Agent → Skill 3계층 아키텍처

User input / command trigger
       │
       ▼
┌──────────────┐    Command (entry point) 
│  /command    │    .claude/commands/*.md
└──────┬───────┘
       │ Agent tool
       ▼
┌──────────────┐    Agent (executor) 
│  Agent       │    .claude/agents/*.md
└──────┬───────┘
       │ Preload/invoke Skill
       ▼
┌──────────────┐    Skill (knowledge) 
│  Skill       │    .claude/skills/*/SKILL.md
└──────────────┘

• Command — 사용자 진입점. Agent 호출 순서를 오케스트레이션합니다. 82개 내장 맞춤형

• Agent — 독립적인 컨텍스트 실행자. 병렬로 실행할 수 있습니다. 5개 내장 맞춤형

• Skill — 재사용 가능한 명령어 팩. 로드되거나 호출됩니다. 10개 내장 맞춤형

비교

선택 가이드: 여러 Agent를 연결하는 다단계 흐름을 조율해야 한다면 → Command. 독립적인 컨텍스트, 병렬 실행, 도구 격리가 필요하다면 → Agent. 다양한 시나리오에서 로드되는 재사용 가능한 명령어 팩이 필요하다면 → Skill.

관계 및 사용 사례

Harness가 중요한 이유

출력 품질 공식: quality = f(effective_context, model_capability, iteration_loops) Harness는 “유효 컨텍스트(effective context)“와 “반복 루프(iteration loops)“에 직접적인 영향을 미칩니다.

Harness: 10가지 핵심 기능

“Skills, Commands, Subagents 모두 결국 프롬프트가 되므로, 강력한 프롬프트만으로 충분하지 않을까?” — 기술적으로는 맞지만, 실제로는 그렇지 않습니다. Harness가 프롬프트가 닿을 수 없는 계층에서 수행하는 작업은 다음과 같습니다:

User input: "Write a recursive flatten function"     ← (a) ~6 tokens

What the model actually sees:                       ← (b) ~15,000 tokens
  ├── CLAUDE.md (Project specs)
  ├── Matched .claude/rules/*.md (paths trigger)
  ├── Modular system prompt fragments (110+)
  ├── Tool definitions
  ├── Environment context (cwd, git status, platform)
  ├── Previous conversation turns
  ├── Files read via Read/Grep
  └── User's 6-token request

하위 에이전트

5가지 내장 유형

사용자 정의 에이전트 프론트매터 (16개 필드)

명령어 시스템 (82개 내장)

Claude Code에는 11개 카테고리로 구성된 82개의 내장 슬래시 명령어가 있습니다. 사용자 정의 명령어는 .claude/commands/*.md에 추가할 수 있습니다.

사용자 정의 명령어: .claude/commands/*.md에 배치하며, 16개의 프론트매터 필드(name, description, argument-hint, arguments, context 등)를 지원합니다. 동적 컨텍스트 주입을 위해 “!`command```를 사용하세요.

오케스트레이션 패턴

Weather Reporter 전체 오케스트레이션 흐름 애니메이션

User: /weather-orchestrator
       │
       ▼
┌──────────────────────────┐
│  weather-orchestrator    │  ← Command (entry point) 
│  1. Ask temperature unit C/F   │
│  2. Call weather-agent   │
│  3. Call svg-creator     │
└──────┬───────────────────┘
       ▼
┌──────────────────────────┐
│  weather-agent           │  ← Agent
│  preload: weather-fetcher │  ← Skill (preloaded) 
└──────┬───────────────────┘
       ▼
┌──────────────────────────┐
│  weather-svg-creator     │  ← Skill (invoked) 
│  output: weather.svg         │
└──────────────────────────┘

작업 시스템

Claude Code의 내장 작업 추적 시스템은 생성, 조회, 업데이트 및 종속성 관리를 지원합니다. 서브에이전트 및 스킬과 함께 작동합니다.

4가지 핵심 도구

작업 수명 주기

pending → in_progress → completed
                 ↘ deleted

종속성

• addBlocks — “이 작업이 완료될 때까지 지정된 작업을 시작할 수 없음”을 표시합니다
• addBlockedBy — “이 작업은 지정된 작업이 완료될 때까지 대기해야 함”을 표시합니다
• 실행 순서를 보장하는 **DAG(방향성 비순환 그래프)**를 형성합니다

환경 변수: CLAUDE_CODE_TASK_LIST_ID는 현재 작업 목록을 식별하며, 파일은 ~/.claude/tasks/에 저장됩니다.

스킬 시스템

핵심 통찰: 스킬은 폴더입니다 (단순한 마크다운 파일이 아님). 스크립트, 데이터, 리소스, 구성 템플릿 등 에이전트가 검색, 읽기 및 조작할 수 있는 모든 것을 포함할 수 있습니다. SKILL.md는 진입점이지만 전체는 아닙니다. 실제 예제는 오케스트레이션을 참조하세요.

스킬은 자동 검색 및 트리거 기능과 함께 .claude/skills/<name>/SKILL.md에 있습니다. 세션이 시작되면 Claude는 사용 가능한 모든 스킬의 description 필드를 스캔하여 현재 작업과 일치시킵니다.

• 점진적 정보 로딩 — SKILL.md를 통해 폴더에 있는 파일을 Claude에 알려주면, 필요할 때만 세부 정보를 읽습니다. 모든 정보를 한 번에 로딩하여 컨텍스트를 낭비하는 것을 방지합니다.

• 설명은 모델을 위한 것 — description 필드는 요약이 아니라 트리거 조건 설명입니다. “이 스킬을 언제 사용해야 하는지”를 명확하게 작성하면 Claude가 그에 따라 자동 매칭합니다.

9가지 구성 패턴

2가지 로딩 모드

• 사전 로딩 모드 (에이전트 스킬) — 에이전트의 skills: 필드를 통해 로딩됩니다. 에이전트 시작 시 자동으로 주입됩니다.

• 호출 모드 (실행된 스킬) — 스킬 도구 또는 /skill-name을 통해 트리거됩니다. Claude가 자동으로 매칭하여 호출할 수도 있습니다.

9가지 사용 카테고리

수백 개의 내부 Anthropic 스킬에서 추출(Thariq, 2026.03). 좋은 스킬은 하나의 카테고리에 속합니다. 여러 카테고리에 걸친 스킬은 일반적으로 분할해야 합니다.

16가지 프론트매터 필드

10가지 내장 스킬

훅 시스템

라이프사이클 이벤트 기반 자동화 스크립트입니다. .claude/settings.json 또는 에이전트 프론트매터에서 구성합니다.

4가지 훅 유형

에이전트 프론트매터 제한 사항: 에이전트에서는 6개의 훅 이벤트만 사용할 수 있습니다: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Stop, SubagentStop. 나머지 21개 이벤트는 메인 세션에서만 사용할 수 있습니다.

27개 라이프사이클 이벤트

기능별로 그룹화됩니다. 모든 이벤트는 async 및 timeout 옵션을 지원합니다.

구성 예시

훅은 설정에서 구성하거나, 필요에 따라 스킬 프론트매터를 통해 활성화합니다.

{
  "hooks": {
    "Stop": [{
      "type": "command",
      "command": "python3 .claude/hooks/scripts/hooks.py --event Stop"
    }],
    "PostToolUse": [{
      "type": "command",
      "command": "python3 .claude/hooks/scripts/hooks.py --event PostToolUse"
    }]
  }
}

고급 도구 활용

Prompt-to-Code (PTC) — 패러다임 전환

시스템 프롬프트에 지시사항을 쑤셔 넣는 대신, PTC는 이를 샌드박스에서 실행되는 실행 가능한 코드 규칙으로 컴파일합니다. 결과: 더 짧은 프롬프트, 더 정밀한 추론, ~37% 토큰 절약.

{
  "type": "code_execution_20250825",
  "name": "data_processor",
  "allowed_callers": ["code_execution_20250825"],
  "input_schema": {
    "type": "object",
    "properties": {
      "task": { "type": "string" }
    }
  }
}

PTC 고급 패턴

• 배치 처리 — 단일 PTC 호출로 여러 레코드를 순회하여 도구 호출 횟수를 줄입니다. 배치 번역, 분류 등에 이상적입니다.

• 조기 종료 — 코드에 조건 검사를 추가하여 임계값 충족 시 즉시 return합니다. 불필요한 연산을 방지합니다.

• 조건부 분기 — 각각에 대해 별도의 도구를 정의하는 대신 입력 유형에 따라 다른 처리 분기를 동적으로 선택합니다.

PTC 제약사항

동적 도구 필터링

Web Search / Web Fetch 결과가 원본 그대로 주입되는 대신 코드에 의해 사전 처리됩니다. 베타 헤더 anthropic-beta: code-execution-web-tools-2026-02-09가 필요합니다.

도구 검색

자주 사용하지 않는 도구에 defer_loading: true를 표시하면 모델이 필요할 때 검색하여 로드하며, 도구 정의를 ~85% 줄여줍니다.

// Tool definitionsExample
{
  "name": "specialized_analyzer",
  "defer_loading": true,
  "description": "..."
}

// Claude Code environment variable
ENABLE_TOOL_SEARCH=auto:5  // Keep 5 common tools, defer the rest

도구 사용 예시

도구 정의에 실제 데이터 샘플이 포함된 input_examples 배열(1-5개 항목)을 추가하세요. 모델 호출 정확도가 72%에서 90%로 향상됩니다.

{
  "name": "query_database",
  "input_examples": [
    { "sql": "SELECT * FROM users WHERE active = true LIMIT 10" },
    { "sql": "SELECT COUNT(*) FROM orders WHERE date > '2026-01-01'" }
  ]
}

Claude Code에서의 가용성

CLI 사용자 우선사항: CLAUDE.md에서 먼저 도구 사용 예시와 도구 검색을 구성하세요 (ENABLE_TOOL_SEARCH=auto:5). 이 기능들이 CLI 사용자에게 가장 큰 이점을 제공합니다. PTC와 동적 필터링은 주로 SDK/API 심층 연동 시나리오를 위한 것입니다.

설정 5단계 우선순위

관리형 설정 전달 방법

핵심 설정

거부 규칙은 항상 최고 우선순위를 가집니다 — 어느 수준에서든 거부는 모든 허용 규칙을 재정의합니다. 배열 설정은 수준 간에 대체되지 않고 병합 및 중복 제거됩니다.

관리형 레이어 내부 우선순위

관리형 레이어 내에서 소스는 다음 순서로 사용됩니다 (단 하나의 소스만 사용, 교차 레이어 병합 없음):

v2.1.126 변경 사항: /config는 이제 변경 사항을 메모리에만 보관하는 대신 ~/.claude/settings.json에 저장합니다. 대화형 설정 UI를 통한 편집은 재시작 후에도 유지됩니다.

권한 모드

설정의 permissions 키를 통해 구성합니다.

도구 권한 구문

경로 접두사

매칭 규칙

• 복합 명령어: &&, ||, ;, |로 분리되며, 각 하위 명령어는 독립적으로 매칭됩니다. Bash(safe-cmd *)는 safe-cmd && other-cmd를 포함하지 않습니다
• 와일드카드 위치: *는 접두사, 접미사 또는 중간에 올 수 있습니다. Bash(* install)은 npm install과 매칭됩니다; Bash(git * main)은 git push main과 매칭됩니다
• 단어 경계: Bash(ls *)(공백 포함)는 lsof와 매칭되지 않습니다; Bash(ls*)(공백 없음)는 둘 다 매칭됩니다
• 심볼릭 링크: 허용하려면 심볼릭 링크와 대상 모두가 허용된 디렉토리에 있어야 합니다; 거부는 둘 중 하나라도 해당되면 트리거됩니다
• 프로세스 래퍼: timeout, time, nice, nohup은 매칭 전에 제거됩니다. watch, find -exec는 항상 프롬프트를 표시합니다

전역 vs 프로젝트 설정

• 전역 ~/.claude/ — settings.json 전역 설정 CLAUDE.md 모든 프로젝트 지침 적합: 개인 설정, 일반 구성, 셸 별칭

• 프로젝트 .claude/ — settings.json 팀 공유 (커밋됨) settings.local.json 개인 오버라이드 (git-ignored)) CLAUDE.md 프로젝트 지침 agents/ SubAgent 정의 skills/ 스킬 정의 commands/ 커스텀 명령어

6가지 설정 차원

디렉토리 구조

~/.claude/                          .claude/
├── settings.json      ← Global settings    ├── settings.json      ← Team shared
├── settings.local.json               ├── settings.local.json ← Personal override
├── CLAUDE.md          ← Global instructions    ├── CLAUDE.md          ← Project instructions
├── mcp.json           ← Global MCP    ├── agents/            ← Subagent definitions
├── agents/            ← Global agents    │   ├── reviewer.md
│   ├── explorer.md                   │   └── coder.md
│   └── researcher.md                 ├── skills/            ← Skill definitions
├── skills/            ← Global skills    │   ├── lint-check/
│   └── deploy-check/                 │   │   └── SKILL.md
├── commands/          ← Global commands    │   └── test-runner/
│   └── review.md                     │       └── SKILL.md
├── plans/             ← Plan files    ├── commands/          ← Custom commands
├── tasks/             ← Task persistence  │   └── commit.md
├── memory/            ← Auto memory    ├── rules/             ← Conditional rules
└── plugins/           ← Plugin installs    │   ├── tests.md
                                      │   └── security.md
                                      └── mcp.json           ← Project MCP

6가지 설계 원칙

전역 전용 기능

• allowedPlugins / deniedPlugins — 플러그인 허용/차단 목록
• managedSettings — IT 배포 조직 수준 설정
• autoUpdatesChannel — 업데이트 채널 제어
• cleanupPeriodDays — 세션 자동 정리
• pluginRegistry — 커스텀 플러그인 소스
• plansDirectory — 전역 계획 파일 디렉토리
• autoMemoryEnabled — 메모리 시스템 토글

CLAUDE.md 사양

CLAUDE.md는 Claude Code에서 가장 영향력 있는 구성입니다. 잘 구조화된 CLAUDE.md는 어떠한 설정 튜닝보다도 출력 품질을 더 크게 향상시킵니다.

4가지 저장 위치

.claude/rules/ 조건부 로딩

• paths: 프론트매터 포함 — **지연 로드(Lazy-loaded)**됩니다. 일치하는 경로에서 작업할 때만 로드됩니다. 프레임워크별 규칙에 이상적입니다. 예: paths: ["src/**/*.test.ts"]는 테스트 파일을 편집할 때만 로드됩니다.

• 프론트매터 없음 — 모든 세션에서 로드되며 CLAUDE.md와 동일합니다. 프로젝트 전체 규칙에 가장 적합합니다.

작성 가이드라인

• 200줄 이하로 유지 — 이를 넘어가면 준수율이 떨어집니다
• **이유(WHY)**를 작성하고 내용(WHAT)은 쓰지 마세요 — 코드가 이미 내용을 설명하고 있습니다; 숨겨진 제약 조건, 미묘한 불변량, 특정 버그에 대한 해결 방법을 문서화하세요
• 부정 지침이 더 효과적입니다 — “패턴 X를 사용하지 마세요”가 “패턴 Y를 사용하세요”보다 더 명확합니다
• 코드가 이미 표현하고 있는 내용은 적지 마세요 — CLAUDE.md의 가치는 Claude를 기본 사고방식에서 벗어나게 하는 데 있습니다
• 코드 패턴, 아키텍처 스냅샷 또는 git 기록을 저장하지 마세요 — 이러한 것들은 코드에서 파생될 수 있습니다
• 프로젝트별 제약 조건을 포함하세요: 빌드 순서 종속성, 알려진 호환되지 않는 라이브러리 버전, 특수 배포 프로세스

claudeMdExcludes

claudeMdExcludes 설정을 사용하여 원하지 않는 CLAUDE.md 파일을 건너뛰세요:

{
  "claudeMdExcludes": [
    "**/vendor/**/CLAUDE.md",
    "**/node_modules/**/CLAUDE.md"
  ]
}

제외는 사용자, 프로젝트 및 로컬 메모리에만 적용됩니다. 관리형 정책 파일은 제외할 수 없습니다.

모노레포 로딩 메커니즘

모노레포에서의 CLAUDE.md 로딩 메커니즘 (Boris Cherny 원작)

• 상위 디렉토리 로딩 — 시작 시 상향으로 탐색하며 모든 CLAUDE.md 파일을 즉시 로드합니다. 즉시 로드

• 하위 디렉토리 로딩 — 하위 디렉토리의 CLAUDE.md 파일은 해당 디렉토리에서 작업할 때만 로드됩니다. 지연 로드

시나리오 비교

모노레포 구조: frontend/CLAUDE.md, backend/CLAUDE.md, api/CLAUDE.md, 루트 CLAUDE.md라고 가정합니다.

시나리오 1: 루트에서 시작 cd /mymonorepo && claude

시나리오 2: 컴포넌트 디렉토리에서 시작 cd /mymonorepo/frontend && claude

모범 사례: 공유 규칙은 루트 CLAUDE.md에, 컴포넌트별 지침은 해당 컴포넌트의 CLAUDE.md에 작성하세요. 개인 기본 설정은 CLAUDE.local.md(git-ignored)에 작성하세요.

자동 메모리

Claude Code의 자동 메모리 시스템은 세션 간에 정보를 유지합니다. 메모리 파일은 프로젝트 .claude/ 디렉토리 또는 전역 ~/.claude/에 저장되며, YAML frontmatter + Markdown 형식으로 구성됩니다.

4가지 메모리 유형

메모리 파일 구조

각 메모리는 YAML frontmatter를 사용하는 독립적인 Markdown 파일입니다:

---
name: feedback-testing
description: Testing preferences and corrections
metadata:
  type: feedback
---

Integration tests must use a real database, not mocks.
**Why:** Last quarter a migration failed due to mock/production environment divergence. 

[[testing-patterns]]  ← link to related memory

MEMORY.md 인덱스

모든 메모리는 200줄 이하로 유지되는 MEMORY.md 인덱스 파일을 통해 관리됩니다. 줄당 인덱스 형식:

- [Title](filename.md) — one-line summary

저장하지 않아야 할 항목

• 코드 패턴, 아키텍처, 파일 경로 — 코드에서 도출 가능
• Git 기록, 최근 변경 사항 — git log가 권위 있는 소스
• 디버깅 솔루션 — 수정 사항은 코드에, 맥락은 커밋 메시지에 있음
• CLAUDE.md에 이미 포함된 내용
• 일시적인 작업 세부 정보 — 대신 Task 또는 Plan 사용

설정

에이전트 메모리 3가지 범위

서브에이전트를 통해 메모리는 에이전트 간에 지식을 유지할 수 있습니다.

MEMORY.md 인덱스 파일은 200줄 이하로 유지하세요.

MCP 서비스

일반 MCP 서비스

MCP 설정 키

설정 예시

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-context7"]
    },
    "always-on-server": {
      "type": "http",
      "url": "https://mcp.example.com",
      "alwaysLoad": true
    }
  }
}

주요 기능

• alwaysLoad (v2.1.121) — 서버 설정에 "alwaysLoad": true를 설정하면 지연 로딩(lazy discovery) 대신 모든 도구를 즉시 로드합니다. 매 턴마다 필요한 소규모 도구 세트에만 사용하세요.

• 핫 리로드 (v2.1.139) — /mcp 재연결은 세션을 재시작하지 않고 .mcp.json을 다시 읽습니다. 또한 stdio 서버 환경에 CLAUDE_PROJECT_DIR을 주입합니다.

환경 변수 확장

.mcp.json에서 ${ENV_VAR} 구문을 사용하여 환경 변수를 참조하면 하드코딩된 시크릿을 피할 수 있습니다:

{
  "mcpServers": {
    "my-api": {
      "url": "https://mcp.example.com/mcp?token=${MCP_API_TOKEN}"
    }
  }
}

workspace는 예약된 MCP 서버 이름입니다 (v2.1.128). 이 이름으로 사용자 정의 서버를 정의하면 경고와 함께 건너뜁니다.

OAuth 호환 서버는 인증을 자동으로 완료합니다(RFC 9728 준수). 수동으로 apiKeyHelper를 설정할 필요가 없습니다.

RPI 워크플로우

Research(조사) → Plan(계획) → Implement(구현), 각 단계에는 검증 게이트가 있습니다. 서브에이전트를 통해 여러 에이전트 역할을 조정합니다.

Step 1: RESEARCH   → RESEARCH.md (GO / NO-GO) 
Step 2: PLAN       → PLAN.md + pm.md + ux.md + eng.md
Step 3: IMPLEMENT  → IMPLEMENT.md (phased, each phase has test gates) 

8가지 에이전트 역할

3가지 명령어

rpi/{feature-slug}/
├── REQUEST.md              # Feature description
├── research/RESEARCH.md    # GO/NO-GO analysis
├── plan/
│   ├── PLAN.md             # Implementation roadmap (3-5 phases) 
│   ├── pm.md               # Product requirements document
│   ├── ux.md               # UX design draft
│   └── eng.md              # Technical specification
└── implement/IMPLEMENT.md  # Implementation log (per-phase verification) 

CRISPY 방법론

C — Clarify      Define requirements
R — Research     Technical research
I — Ideate       Brainstorm solutions
S — Structure    Architecture design
P — Plan         Create plan
Y — Yield        Produce implementation
  + Iterate      Iterate & refine

CRISPY는 RPI의 진화형으로, Ideate(구상) 및 Structure(구조화) 단계를 추가하여 구현보다 솔루션 설계가 더 중요하다는 점을 강조합니다.

크로스 모델 협업 (Claude + Codex)

Claude Code (Opus) + Codex CLI (GPT) 크로스 모델 4단계 협업 워크플로우

STEP 1: PLAN          Claude Code Opus · Plan Mode
STEP 2: QA REVIEW     Codex CLI GPT · Review plan, insert findings
STEP 3: IMPLEMENT     Claude Code Opus · Phase-by-phase implementation
STEP 4: VERIFY        Codex CLI GPT · Verify against plan

**핵심 아이디어:**서로 다른 모델이 상호 검토를 수행합니다. Codex는 원본 계획을 다시 작성하지 않고 “Codex Finding” 주석을 추가합니다.

에이전트 팀

에이전트 팀 멀티 에이전트 협업 워크플로우

공유 작업 목록(TaskCreate/TaskUpdate)을 통해 여러 에이전트를 조정합니다. 독립적인 하위 작업으로 분해 가능한 대규모 리팩토링에 이상적입니다.

팀 조정 패턴

시간 오케스트레이션을 예로 들면 — 세 가지 역할이 데이터 계약 {time, timezone, formatted}을 공유하며 병렬로 빌드합니다:

에이전트 팀 구성 요소 목록

---
name: time-agent
description: Get current Dubai time (Asia/Dubai, UTC+4) 
tools: Bash
model: haiku
color: blue
maxTurns: 3
skills: time-fetcher
---
Use Bash to execute `TZ='Asia/Dubai' date`, return time/timezone/formatted fields. 

---
description: Get Dubai time and generate SVG time card
model: haiku
---
1. Agent(time-agent) → fetch {time, timezone, formatted}
2. Skill(time-svg-creator) → generate SVG card
Note: Must execute sequentially, cannot parallelize. 

---
name: time-fetcher
description: Fetch current Dubai time via bash
user-invocable: false
---
Command: TZ='Asia/Dubai' date '+%Y-%m-%d %H:%M:%S %Z'
Return format: { time: "HH:MM:SS", timezone: "GST (UTC+4)", formatted: "full output" }

---
name: time-svg-creator
description: Create Dubai time SVG card
allowed-tools: Write, Read
---
Receive time/timezone/formatted, generate self-contained SVG card. 
Output: agent-teams/output/dubai-time.svg + output.md

예약 작업

# CronCreate Parameters
cron: "*/5 * * * *"     # Standard 5-field cron (local timezone) 
prompt: "Check CI status"   # Prompt executed on trigger
recurring: true          # true=recurring, false=one-shot
durable: true            # true=persist to file

목표 기반

작업 시스템을 통해 자동으로 분해하고 진행 상황을 추적합니다.

1. 사용자가 목표를 설정합니다
2. Claude가 하위 작업으로 분해하고 작업 목록을 생성합니다
3. 단계별로 구현하며, 각 단계에서 상태를 업데이트합니다
4. 차단 시 사용자 입력을 요청합니다

커뮤니티 목표 팁

세션 관리

컨텍스트 부패는 약 300-400k에서 나타나기 시작합니다. 수정하는 것보다 되돌리는 것이 낫습니다.

LLM 성능 저하 분석

LLM 출력 품질의 일일 변동

9계층 추론 스택 (고정된 가중치 ≠ 고정된 동작)

┌──────────────────────────────────────────────┐
│  User session context              ← In-session degradation    │
│  System Prompt                    ← Periodically updated      │
│  Post-Training (RLHF/fine-tuning)  ← Can update silently    │
│  Sampling params (temperature/top-p) ← Server-adjustable    │
│  Speculative Decoding (draft model) ← Quality fluctuation      │
│  MoE routing / batch composition   ← ±8-14% variance   │
│  Hardware routing (TPU/GPU/Trainium)← Different failure modes  │
│  Quantization level (FP16/INT8/INT4)← May change under load │
│  Compiler & runtime (XLA:TPU/CUDA) ← Confirmed bugs  │
├──────────────────────────────────────────────┤
│  Model weights (frozen) ← This layer does not change                    │
└──────────────────────────────────────────────┘

핵심 발견 사항

Anthropic 2025.9 사후 분석: 3가지 인프라 버그

버그 #1 — 컨텍스트 윈도우 라우팅 오류

버그 #2 — TPU 출력 손상

버그 #3 — XLA:TPU 컴파일러 오류 컴파일레이션 (가장 까다로운 버그)

Claude는 세 가지 다른 하드웨어 플랫폼(AWS Trainium, NVIDIA GPU, Google TPU)에서 실행되며, 각각 다른 장애 모드, 컴파일러 및 정밀도 동작을 가집니다. 요청은 날짜에 따라 다른 하드웨어에 도달할 수 있습니다.

MoE 라우팅 분산 (Scale AI 연구)

MoE(Mixture of Experts) 아키텍처에서, 배치 내 다른 사용자의 쿼리 구성에 따라 요청이 라우팅되는 전문가가 결정되며 — 이 구성은 비결정론적입니다.

구체적인 예: 동일한 모델이 어느 날은 탈옥 저항성에서 77%를 기록했고 다음 날은 63%를 기록함 — 버그도, 변경 사항도 없이 14포인트가 변동했습니다.

시스템 프롬프트 및 사후 학습 업데이트

스탠퍼드 연구 (2023) — 그리고 그 논란

Chen/Zaharia/Zou의 획기적인 연구는 “소수 판별”에서 GPT-4의 정확도가 97.6%에서 2.4%로 떨어진 것(2023년 3월→6월)을 발견했지만, 방법론적 문제가 있었습니다:

• 3월 버전은 temperature 0.0을 사용했고, 6월 버전은 temperature 1.0을 사용함 — 근본적인 교란 변수
• 작업당 500개의 쿼리만 사용 — 표본 크기가 너무 작음
• “수학 문제”는 실제로 예/아니요 질문이었으며, 수학 능력이 저하된 것이 아니라 모델의 추측 패턴이 변경된 것임
• 변경 사항은 의도하지 않은 저하가 아니라 의도적인 사후 학습 안전 업데이트일 수 있음

심리적 요인

Codex 5.3 비교 분석

Claude에 단기적인 성능 저하가 있을 때 Codex 5.3이 훨씬 더 좋아 보일 수 있는 이유는 다음과 같습니다:

1. 제품-목표 적합성 — Codex는 코드 생성에 최적화되어 있어 동일한 모델 강도에서도 더 나은 코딩 결과를 생성함
2. 추론 전략 차이 — 각 제공업체는 지연 시간/추론 깊이/디코딩 기본값을 독립적으로 조정함
3. 서비스 경로 격리 — 다른 라우팅 계층/컴파일러/릴리스 파이프라인을 사용하므로 한쪽의 장애가 다른 쪽에 영향을 주지 않음
4. 릴리스 시기 — 한 제공업체가 릴리스 중이고 다른 제공업체가 안정적인 경우 일시적으로 큰 품질 차이가 발생할 수 있음

성능 저하 가설 순위

실용적인 권장 사항

1. 가능한 경우 (유동적 별칭 대신) 모델 스냅샷을 잠금 설정
2. 요청 메타데이터(모델 ID, 매개변수, 지연 시간, 오류율)를 저장
3. 고정된 일일 카나리아 테스트를 실행하고, 회귀 시 경고
4. 여러 번 실패한 후 긴 세션을 재설정하거나 압축
5. 백업 제공업체/모델 경로를 유지
6. 내부 대시보드에서 “모델 품질”과 “서비스 안정성”을 분리

가장 중요한 단일 조치: 품질이 저하된 것 같으면 /compact를 사용하거나 새 세션을 시작하세요. 이것이 가장 효과적인 단일 조치입니다 — 대부분의 “Claude가 멍청해졌다”는 것은 모델 저하가 아니라 컨텍스트 오염입니다.

하니스의 중요성

일반적인 오해: 스킬/커맨드/서브에이전트/훅은 모두 결국 프롬프트가 되므로, 좋은 프롬프트를 작성하는 것만으로 충분하다는 것입니다. **이것은 틀렸습니다.**엔지니어링 관점에서 하니스는 프롬프트 구성 시스템 + 결정론적 실행 시스템 + 컨텍스트 아키텍처 시스템입니다.

하니스의 10가지 기능 (프롬프트로는 복제 불가)

출력 품질 = f(유효 컨텍스트, 모델 기능, 반복 루프). 사용자는 유효 컨텍스트의 극히 일부만 제어합니다. 하니스가 나머지와 전체 반복 루프를 제어합니다. 강력한 프롬프트는 필요하지만 충분하지 않습니다.

브라우저 MCP 비교

권장 워크플로우

# Install command
npx playwright install
claude mcp add playwright -s user -- npx @playwright/mcp@latest
claude mcp add chrome-devtools -s user -- npx chrome-devtools-mcp@latest

Playwright가 가장 높은 토큰 효율성(186.3k 남음)을 가지며, Chrome DevTools가 가장 낮습니다(181k 남음). 약 5.3k 토큰의 차이가 있습니다.

모노레포 스킬 탐색

스킬 탐색/로딩 메커니즘은 CLAUDE.md와 다릅니다: CLAUDE.md는 상위로 탐색(조상 로딩)하는 반면, 스킬은 중첩된 디렉토리 자동 탐색(자손 탐색)을 사용하며, 해당 디렉토리에서 파일을 편집할 때만 필요에 따라 로드됩니다. 모노레포 로딩 메커니즘을 참조하세요.

표준 스킬 위치

CLAUDE.md와 스킬 로딩 비교

문자 예산은 기본적으로 15,000자이며, SLASH_COMMAND_TOOL_CHAR_BUDGET 환경 변수를 통해 조정할 수 있습니다. /context를 사용하여 예산 제한으로 인해 제외된 스킬이 있는지 확인하세요.

• 일반적인 워크플로는 루트 .claude/skills/에 배치합니다
• 패키지별 스킬은 해당 패키지의 .claude/skills/에 배치합니다
• 위험한 작업 스킬은 disable-model-invocation: true를 설정해야 합니다
• 혼란을 피하기 위해 패키지 이름 접두사를 사용하세요 (예: frontend-review, backend-deploy)

사용량 및 제한

모니터링 명령어

비용 최적화

• 간단한 작업에는 model: haiku를 사용하세요
• effort: low는 추론을 줄여줍니다
• 백그라운드 에이전트는 블로킹을 방지합니다
• API 키 사용자는 --max-budget-usd를 사용하여 비용을 제어할 수 있습니다
• 예상치 못한 요금을 피하기 위해 extra-usage 월간 상한선을 설정하세요

빠른 모드(/fast)는 첫 번째 토큰부터 추가 사용량으로 계산되며, 구독 플랜에 포함된 할당량을 소비하지 않습니다. 사용하려면 extra-usage를 활성화하고 자금을 충전해야 합니다.

스피너 동사

Claude Code의 로딩 애니메이션은 179개의 무작위 동사를 사용합니다. 일반적인 동사는 다음과 같습니다:

학습 경로

Weather Reporter를 처음부터 구축하는 완전한 학습 여정으로, 5개 주요 단계 · 37개 슬라이드로 구성됩니다:

단계 순서 (인지적 종속성에 따라 재정렬)

LEVELS 매핑 (6개 레벨)

const LEVELS = {
  context:     '🔴 Context Window',   // context-window.jpeg, context.jpg
  claude_md:   '🟠 CLAUDE.md',   // Project instruction system
  agents:      '🟡 Agent System',     // Built-in + custom agents
  skills:      '🟢 Skills System',     // Skills framework
  commands:    '🔵 Commands System',     // Commands orchestration
  workflow:    '🟣 Full Workflow'    // End-to-end integration
}

37개 슬라이드 개요

리소스 재사용

재설정 내역

• goToSlide() 대상: 모든 37개 호출 지점의 인덱스 번호 업데이트 필요
• data-level 속성: 각 슬라이드의 레벨 마커를 LEVELS에 매핑 필요
• 탐색 컴포넌트: 이전/다음 버튼을 새 슬라이드 순서에 바인딩 필요
• 진행률 표시줄: 5구간 진행 표시기가 5개 단계에 매핑

단순하게 시작 → 점진적으로 조합 → 전체 오케스트레이션. 처음부터 복잡한 아키텍처를 구축하지 마세요. 단계 순서는 인지적 종속성에 따라 재배열되었습니다: 먼저 “누가”(Agents)를 이해하고, 그 다음 “무엇을 할 수 있는가”(Skills), “환경”(Context), “규칙”(CLAUDE.md), 마지막으로 “오케스트레이션”(Commands)의 순서입니다.

SDK vs CLI 시스템 프롬프트

Claude Code CLI와 Agent SDK는 서로 다른 시스템 프롬프트 전략을 사용합니다:

핵심 차이점

SDK는 modular 프롬프트 타입을 제공하여, 도구 설명을 개별적으로 추가할 수 있어 CLI의 전체 로드 방식보다 많은 토큰을 절약할 수 있습니다.

10억 달러짜리 질문들

커뮤니티에서 나온 13개의 미해결 심층 질문 — 답을 알고 있다면, 그것은 10억 달러짜리 통찰입니다.

메모리 및 지침 (4개 질문)

1. CLAUDE.md에는 무엇이 들어가야 할까? — 포함할 것과 제외할 것은?
2. CLAUDE.md가 있다면, 여전히 constitution.md나 rules.md가 필요한가?
3. CLAUDE.md는 얼마나 자주 업데이트해야 할까? 구식이 되었는지 어떻게 알 수 있을까?
4. 왜 Claude는 MUST를 모두 대문자로 써도 CLAUDE.md의 지침을 여전히 무시할까?

에이전트, 스킬 및 워크플로우 (6개 질문)

1. Command, Agent, Skill을 각각 언제 사용해야 할까 — 네이티브 Claude Code가 더 나은 경우는 언제인가?
2. 모델이 업그레이드됨에 따라 에이전트/명령어/워크플로우는 얼마나 자주 업데이트해야 할까?
3. 범용 vs 역할/기능 특화 서브에이전트 — 상세한 페르소나가 실제로 품질을 향상시킬까?
4. Claude Code의 내장 plan 모드를 사용할까, 아니면 팀 워크플로우를 강제하기 위해 커스텀 기획 명령/에이전트를 구축할까?
5. 개인 스킬과 커뮤니티 스킬은 어떻게 공존할까? 충돌 시 누가 우선인가?
6. **궁극의 질문:**기존 코드베이스를 스펙으로 변환하고, 코드를 삭제한 후, 스펙만으로 AI가 다시 생성하게 할 수 있을까?

스펙 및 문서화 (3개 질문)

1. 저장소의 모든 기능에 스펙 파일이 필요할까?
2. 스펙은 최신 상태를 유지하기 위해 얼마나 자주 업데이트해야 할까?
3. 새로운 기능을 구현할 때, 다른 기능의 스펙에 미치는 연쇄적 영향을 어떻게 처리할까?

이 질문들에 대한 답은 에이전틱 엔지니어링 모범 사례의 방향을 결정할 것입니다. 통찰력이 있다면, 이곳이 최전선입니다.

Boris Cherny — 13가지 규칙

Boris Cherny — Claude Code 핵심 엔지니어

Boris Cherny는 Anthropic의 Claude Code 핵심 엔지니어로, 수십만 개발자가 사용하는 에이전트 기반 코딩 도구의 개발을 이끌고 있습니다. O’Reilly 《Programming TypeScript》의 저자이며, AI 지원 개발 워크플로우에 대한 공개 강연을 자주 진행합니다. 아래 13가지 규칙은 그의 강연, 데모, PR 코멘트에서 반복적으로 강조된 핵심 조언 —— Claude Code를 처음 시작하는 팀원에게 늘 강조하는 몇 마디 —— 를 압축한 것입니다.

15가지 숨겨진 기능

Boris Cherny(Meta)가 공유하는 Claude Code의 15가지 덜 알려진 기능으로, 각각 사용 방식을 크게 변화시킵니다.

12가지 맞춤 설정 팁

10가지 고급 팁

코드 리뷰 팁

테스트 시간 연산: 코드 리뷰는 모델이 독립적인 컨텍스트에서 “다시 생각”하게 만들어 출력을 200% 증가시킵니다. 멀티 에이전트 병렬 리뷰(보안 + 성능 + 아키텍처)는 단일 리뷰보다 더 높은 품질을 제공합니다.

PR 통계 (Boris Cherny의 실제 데이터)

Boris는 새로 작성된 코드의 약 100%를 AI가 작성하며, 인간은 리뷰하고 방향성을 안내합니다. 핵심은 더 명확한 기록을 위해 파일별 독립적인 커밋을 하는 것입니다.

2가지 머지 팁

Opus 4.7의 6가지 효율성 팁

Opus 4.7 출시 후 Boris Cherny가 정리한 6가지 핵심 효율성 개선 방법.

자동 모드 모범 사례: effort: high 및 /focus와 함께 사용하여 에이전트가 높은 추론 깊이로 자율적으로 작업하며 핵심 결정 지점만 보고하도록 합니다.

Thariq — 스킬 설계

Thariq Koya는 Anthropic의 Claude Code 팀 엔지니어로, 스킬 설계, 세션 관리, 실용적인 에이전트 워크플로우에 중점을 두고 있습니다. 아래 섹션들은 그가 가장 많이 인용되는 조언 —— 2026년 3월 Anthropic 내부 스킬 리뷰와 실제 환경에서의 Claude Code 사용에 관한 실전 노트 —— 를 압축한 것이며, 프로덕션 팀을 위한 스킬을 설계할 때 그 자신이 따르는 동일한 패턴입니다.

Thariq — 실용 팁

세션 관리 — 심층 가이드

Thariq의 심층 세션 관리 프레임워크: 컨텍스트 저하 이해, 브랜칭 전략, 하위 에이전트 가비지 컬렉션.

컨텍스트 부패(Context Rot): 대략 300k-400k 토큰에서 모델은 이전 대화를 “잊어버리기” 시작하며, 출력 품질이 현저히 떨어집니다. 이는 버그가 아니라 어텐션의 수학적 특성입니다.

5가지 브랜칭 전략

• 전략시나리오설명 continue마지막에서 이어서전체 컨텍스트를 복원하여 대화를 이어감 rewind특정 지점으로 돌아가기지정된 단계로 되돌리고 다시 시작 clear새로 시작컨텍스트를 지우고 처음부터 시작 compact압축 및 유지핵심 정보는 유지하면서 지능적으로 압축 subagent격리된 실행하위 에이전트를 파견, 메인 컨텍스트 오염 없음

핵심 의사결정 표

• 시나리오권장 작업 컨텍스트 > 50%/compact 또는 하위 에이전트 파견 잘못된 방향rewind로 갈라진 지점으로 돌아가기, 제자리에서 수정하지 않기 compact 후 품질 저하요약 지침과 함께 /compact [brief] 사용, 또는 clear + CLAUDE.md로 바로 시작 히스토리 보존 필요하위 에이전트가 새 작업을 처리, 메인 대화는 가볍게 유지 하위 에이전트 컨텍스트 팽창하위 에이전트는 내장 GC를 가짐 — 완료 후 자동 수집됨, 메인 세션에 영향 없음

Compact vs Fresh: 대화 기록이 매우 관련성이 높은 경우(예: 디버깅 체인), compact + brief를 사용하세요; 주제가 완전히 바뀐 경우, clear하고 CLAUDE.md에서 컨텍스트를 재구축하는 것이 더 효율적입니다. 잘못된 compact의 일반적인 원인: 모호한 압축 지침으로 인해 핵심 제약 조건이 누락됨.

83개의 카테고리별 팁

커뮤니티 실천 사례와 공식 권장 사항을 16개 도구 카테고리로 정리했습니다. 핵심 참고 자료: CLAUDE.md 컨벤션, Subagents 병렬 처리, RPI 워크플로우.

비디오 하이라이트

Boris Cherny × Ryan Peterman — Claude Code 크리에이터의 커리어 스토리 입문자

Boris Cherny × Lenny's Podcast — Claude Code의 탄생과 제품 철학 제품

Karpathy × AI Engineer — 바이브 코딩에서 에이전트 엔지니어링까지 고급

Matt Pocock 워크샵 — 2시간 Claude Code 실전 워크샵 튜토리얼

공통 명령어 (82개 내장)

CLI 플래그 (16개 카테고리)

기능별로 정리된 전체 CLI 시작 플래그 참고 자료입니다.

환경 변수

설정 템플릿

# Project Name

## Tech Stack
- Frontend: React + TypeScript
- Backend: Node.js + Express

## Coding Conventions
- File naming: kebab-case
- Components: functional + hooks
- Testing: Vitest

## Constraints
- Do not use any type
- Do not skip tests
- API must have error handling

{
  "permissions": {
    "allow": ["Bash(npm run *)","Bash(git status)","Read","Grep","Glob"],
    "deny": ["Bash(rm -rf *)","Bash(git push --force)"]
  }
}

---
name: my-agent
description: Perform specific task
tools: "Bash,Read,Write,Edit,Grep"
model: sonnet
maxTurns: 20
memory: project
---

# My Agent
1. Read relevant files
2. Analyze code
3. Implement changes
4. Verify results

---
name: my-skill
description: What to do
arguments: filename
allowed-tools: "Read,Write,Edit"
paths: "src/**/*.ts"
---

Process $filename: 
1. Read → 2. Transform → 3. Write back

워크플로 치트시트