00. 시작하기

클로드 코드는 /init 명령어를 통해 시작할 수 있습니다. /init 명령어의 주된 목적은 프로젝트를 초기화하고 CLAUDE.md 가이드를 생성하는 것입니다. CLAUDE.md 파일은 프로젝트의 규칙, 코딩 표준, 그리고 **"금지 변경 영역(Invariants)"**을 명시하여 클로드 코드가 작업을 수행할 때 항상 참조하도록 하는 팀 공유 메모리 역할을 합니다.

00-1. CLAUDE.md 파일 명시

프로젝트 루트 디렉토리에 CLAUDE.md 파일을 생성하여 클로드 코드가 작업 시 항상 참조해야 하는 핵심적인 문맥과 규칙을 정의합니다. 이 파일은 프로젝트 메모리 역할을 하며 자동으로 컨텍스트에 로드됩니다.

• CLAUDE.md 파일의 주요 내용 예시
  • Repo Goal
    • 리포지토리의 목적 정의 (예: 레거시 JS → TypeScript 전환)
  • Invariants (금지 변경 영역)
    • 보안 모듈이나 infra/terraform과 같이 Claude가 절대 변경해서는 안 되는 영역을 명시하여 안전 가드레일을 설정
  • How Claude Should Help
    • 권장 작업 방식 명시 (예: "설계 → 합의 → 실행" 3단계)
    • 변경 전 반드시 make test의 "계획 모드" 실행하여야 함을 명시
  • Test & CI Rules
    • 단위/통합 테스트 통과 규칙 및 마이그레이션 커밋 경로 등 팀 규범 명시

00-1-1. 산출물(Artifacts) 폴더

산출물(Artifacts) 폴더란 클로드 코드가 프로젝트에 대한 에이전틱(Agentic) 작업을 수행하는 과정에서 생성하는 모든 중간 결과물, 계획, 설계 문서 등을 저장하기 위해 프로젝트 루트 디렉토리에 미리 정해진 폴더를 만들어 사용하는 것을 의미합니다.

산출물 폴더를 지정하는 주된 목적은 클로드 코드가 생성한 변경 계획이나 설계 등을 로깅하고 관리하는 것입니다.

• 중간 결과물 보존: 클로드는 복잡한 작업을 수행할 때 변경 계획(changesets), 상세 설계 문서 (design), 마이그레이션 스크립트(migrations)와 같은 생성물을 만드는데, 이러한 결과물들을 지정된 디렉토리(/changesets, /design, /migrations 등)에 저장하도록 규약합니다.
• 규칙 주입 패턴: 이 폴더 규약을 CLAUDE.md를 통해 명시하면, 클로드는 이러한 생성물을 저장하거나 참조할 때 이 규칙을 따르게 됩니다. 이는 엔터프라이즈 환경에서 작업의 투명성과 감사 추적(Auditability)을 높이는 데 중요합니다.
• 계획/합의/실행 사이클 지원: 특히 **계획 모드(Plan Mode)**를 사용하여 "설계 → 합의 → 실행"의 안전 사이클을 고정할 때, 설계 단계의 결과물(계획, 리스크 분석, 롤백 플랜)을 /design과 같은 폴더에 기록하도록 지시할 수 있습니다.

00-1-2. 환경 스냅샷 표준화

환경 스냅샷 표준화란 프로젝트의 설치, 테스트, 배포 등 개발 환경을 구성하고 검증하는 명령들을 Makefile이나 scripts/ 폴더 내의 스크립트로 통일하고 명시하는 것을 의미합니다.

핵심 목적: 일관성과 에이전트 신뢰도 향상

이것은 클로드 코드가 코드를 "알아서 설치해 주는" 것을 넘어서, **"정의된 표준화된 방법으로 설치하고, 테스트하고, 실행하는 방법"**을 학습하게 하는 데 있습니다.

• 일관된 명령어 사용: 대형 코드베이스에서는 npm test, make test, npm run lint 등 다양한 명령어가 사용될 수 있습니다. 이러한 명령들을 Makefile에 make test, make install, make deploy 등으로 표준화하면, 클로드가 복잡한 환경 설정 파일을 일일이 분석하는 대신 이 표준 명령만 따르면 됩니다.
• 신뢰도 및 검증: 클로드 코드가 대규모 리팩토링이나 버그 수정을 시도할 때, make test와 같은 표준화된 명령어를 사용하여 변경 사항을 검증하도록 할 수 있습니다. 이는 클로드가 터미널 네이티브 에이전트로서 로컬 실행 및 권한 요청 UX를 활용하는 데 필수적입니다.
• 예시: Makefile에 test 타겟을 정의해 두면, CLAUDE.md에서 "변경 전에는 반드시 make test의 계획 모드를 먼저 실행하라"고 지시함으로써, 클로드가 테스트 절차를 명확히 따르도록 강제할 수 있습니다.

1. CLAUDE.md 작성 예시 및 상세 설명

이러한 규약들은 클로드 코드가 프로젝트의 문맥에 포함될 때 자동으로 로드되도록 CLAUDE.md 파일에 명시됩니다. 이 파일은 프로젝트의 규칙, 코딩 표준, 금지 변경 영역과 함께 이러한 산출물 및 환경 표준을 클로드에게 주입하는 역할을 합니다.

다음은 산출물 폴더 및 환경 표준화를 CLAUDE.md에 작성하는 구체적인 예시입니다:

• CLAUDE.md 예시

# CLAUDE.md (starter)

## Repo Goal
- (예) 레거시 JS → TypeScript 전환, Node 20.x 표준화

## Invariants (금지 변경)
- packages/auth/* 내부 API 시그니처 변경 금지
- infra/terraform/* 는 read-only (별도 워크플로)

## 2. 산출물(Artifacts) 폴더 규약

모든 생성된 설계 문서 및 변경 계획은 아래 지정된 폴더에 저장해야 한다. 
실행 결과물은 여기에만 저장하고 다른 폴더에 저장해서는 안 된다.

- `/changesets`: 최종 변경 사항을 반영하기 위한 계획 목록
- `/design`: 아키텍처 변경이나 리팩토링 시 작성된 상세 설계 문서, 옵션 비교표, 리스크 분석 문서
- `/migrations`: 데이터베이스 또는 시스템 마이그레이션 스크립트

## 3. 환경 스냅샷 및 표준화

코드를 실행, 테스트, 검증할 때 반드시 아래 정의된 표준 명령을 사용해야 한다.

- 설치: 새로운 종속성 추가 시 `npm install` 대신 **`make setup`** 명령을 사용하라.
- 테스트: 모든 코드 수정 후 검증 시 **`make test:unit`** 명령을 실행하라.
- 런북: 운영 환경 배포 런북은 **`scripts/runbook.sh`** 파일을 참조하라.

## How Claude Should Help

- "설계 → 합의 → 실행" 3단계. 각 단계 결과물을 **`/design`에 기록.**
- 변경 전엔 반드시 **`make test:unit`**의 "계획 모드"를 먼저 실행.

## Test & CI Rules
- 단위/통합 테스트 모두 통과해야 PR 생성.
- 마이그레이션은 `scripts/migrate/*`에만 커밋.

00-2. 계획 모드(Plan Mode)로 시작

Anthropic의 공식 베스트 프랙티스는 계획 모드를 활용하여 "설계 → 합의 → 실행" 사이클을 고정하는 것입니다.

• 새 세션 시작 시: claude --permission-mode plan 명령어를 사용합니다.

계획 모드에서는 옵션 트리, 근거, 리스크, 복구 플랜 등을 사람이 승인(합의)하기 전에 Claude가 분석하도록 요청합니다.

00-2-1. 코드베이스 이해하기 (Common Workflows)

새로운 프로젝트를 시작했을 때, 클로드 코드를 사용하여 코드베이스를 빠르게 이해할 수 있습니다.

1. 개요 요청: 프로젝트 루트 디렉토리에서 Claude를 시작한 후, "> give me an overview of this codebase" 명령어로 고수준의 개요를 요청합니다.
2. 구체적인 질문: "main architecture patterns," "key data models," "how is authentication handled?" 등 구체적인 아키텍처 패턴에 대해 질문합니다.
3. 파일 참조: @ 멘션을 사용하여 특정 파일이나 디렉토리의 내용을 컨텍스트에 빠르게 포함시켜 분석을 요청할 수 있습니다 (예: Explain the logic in @src/utils/auth.js). 이때 해당 파일이 포함된 디렉토리의 CLAUDE.md 파일도 함께 로드됩니다.

00-2-2. 모델 선택 전략

작업의 복잡도에 따라 초기 세션에 사용할 모델을 선택하여 비용과 속도를 최적화합니다.

• 복잡한 작업 (추론/설계): 최신 Opus/Sonnet 4.5 라인업을 사용합니다.
• 경량/고속 작업 (리서치/요약): Haiku 4.5를 사용하여 빠른 리서치, 문서 합성, 병렬 서브에이전트 역할에 배치합니다. Haiku 4.5는 Sonnet 4급 성능을 1/3 비용, 2배 이상의 속도로 제공합니다.

01. Tool Use & MCP

Claude Code에서 "Tool"은 모델이 코딩 작업을 수행하는 데 필요한 모든 능력 단위를 의미하며, 이는 **내장 도구(Built-in Tools)**와 **외부 도구(MCP Tools)**로 나뉩니다. 이 도구들은 안전성을 최우선으로 하는 권한 시스템(Permission System) 하에 작동합니다.

01-1. Tool Use

내장 도구 (Built-in Tools):

Claude Code 설치 시 기본적으로 제공되며, 로컬 파일 시스템과 셸 환경에 접근합니다.

• 주요 예시:
  • Edit / Write: 파일 내용을 수정하거나 새로 작성합니다.
  • Read / Grep / LS: 파일 내용을 읽거나, 코드를 검색하거나, 디렉토리 구조를 확인합니다.
  • Bash: 터미널 셸 명령(예: git, npm, make test)을 실행할 수 있습니다. Bash 도구는 Bash(git:*), Bash(npm:*)와 같이 범위가 지정될 수 있습니다

01-2. MCP

MCP(Model Context Protocol)는 Claude Code가 조직 내부의 데이터 소스, 외부 도구, 시스템과 안전하게 연결되도록 지원하는 **오픈 표준(open-source standard)**입니다. 이는 엔터프라이즈 환경에서 Claude의 컨텍스트 범위를 대폭 확장하는 역할을 합니다.

MCP의 목적 및 기능

1. 외부 도구 연결: Claude Code가 수백 개의 외부 도구, API, 데이터베이스에 접근할 수 있게 합니다.
2. 조직 컨텍스트 통합: 엔터프라이즈 검색, 지식 데이터베이스, 이슈 트래커(JIRA)와 같은 사내 리소스를 연결하여 Claude가 조직 문맥을 이해하고 작업을 수행하도록 돕습니다.
3. 워크플로 자동화 지원: MCP 서버를 통해 특정 작업을 자동화할 수 있습니다. 예를 들어, JIRA 이슈를 기반으로 기능 구현을 요청하거나, Sentry나 Statsig 같은 모니터링 데이터를 분석하고, PostgreSQL 데이터베이스를 쿼리할 수 있습니다.

MCP 자원 참조 및 활용

• 자원 참조: MCP 서버가 노출하는 자원(Resources)은 @멘션 구문을 사용하여 참조할 수 있습니다. 형식은 @server:resource/path를 따릅니다. 예를 들어, @github:issue://123과 같이 특정 이슈를 참조하여 분석을 요청할 수 있습니다.
• 슬래시 커맨드: MCP 서버는 특정 프롬프트를 노출할 수 있으며, 이는 Claude Code 내에서 /mcp__servername__promptname 형식의 사용자 지정 슬래시 커맨드로 실행 가능합니다.
• Smithery 를 통해 다양한 MCP Tool을 찾아볼 수 있습니다.

MCP 서버 설치 및 범위 (Scope)

MCP 서버는 필요에 따라 세 가지 방식으로 구성 및 설치될 수 있습니다:

MCP 구성은 액세스 범위에 따라 세 가지 레벨로 나뉩니다:

1. Local Scope (로컬 범위): 현재 프로젝트에만 유효하며 사용자에게 비공개입니다. 개인적인 개발 서버나 민감한 구성에 적합합니다.
2. Project Scope (프로젝트 범위): 프로젝트 루트 디렉터리의 .mcp.json 파일에 저장되며, 버전 관리에 포함하여 팀원들과 공유하는 데 사용됩니다.
3. User Scope (사용자 범위): 사용자 계정에 비공개로 유지되며, 사용자의 모든 프로젝트에서 사용 가능합니다.

MCP 설정 및 관리

• MCP 서버는 claude mcp add 명령을 통해 추가하거나 claude mcp list를 통해 목록을 확인할 수 있습니다.
• Claude Code 내부에서는 /mcp 명령을 사용하여 서버 연결 상태를 확인하고 OAuth 2.0 인증이 필요한 원격 서버에 인증할 수 있습니다.
• MCP 도구의 출력 토큰이 과도해지는 것을 방지하기 위해 최대 허용 토큰 수(MAX_MCP_OUTPUT_TOKENS)가 기본 25,000으로 설정되어 있습니다

02. 컨텍스트(프롬프트) 엔지니어링

컨텍스트 엔지니어링(Context Engineering)과 프롬프트 엔지니어링(Prompt Engineering)은 대규모 언어 모델(LLM)의 성능을 극대화하고 원하는 결과를 안정적으로 얻기 위한 핵심 전략입니다. 특히 에이전틱 코딩 환경(예: Claude Code)에서는 이 두 가지 개념이 밀접하게 연결되어 사용됩니다.

02-1. 컨텍스트 엔지니어링 (Context Engineering)

컨텍스트 엔지니어링은 LLM 에이전트에게 관련성 높고 일관된 배경 지식과 제약 조건을 제공 및 관리하는 프로세스입니다. 이는 에이전트가 복잡한 작업을 수행하는 데 필요한 "영구적인 두뇌"와 작업 공간의 맥락을 구축하는 데 중점을 둡니다.

A. 컨텍스트 엔지니어링의 주요 목표 및 구성 요소

B. 핵심 컨텍스트 엔지니어링 기법 및 도구

1. 에이전틱 코딩 매니페스트 (ACMs) - CLAUDE.md

CLAUDE.md는 Claude Code가 자동으로 컨텍스트로 불러오는 특수 문서이며, 프로젝트의 영구적인 지침서 역할을 합니다.

• 내용 구성: 일반적인 Bash 명령어 (npm run test), 코드 스타일 가이드라인 (예: CommonJS 대신 ES 모듈 사용), 핵심 파일 목록, 아키텍처 패턴, 테스트 지침 등을 명시합니다.
• 구조적 특징: 경험적 연구에 따르면, ACM은 보통 단일 기본 제목(H1)과 적당한 수의 H2 및 H3 하위 섹션을 사용하여 얕은 계층 구조를 선호하며, 내용은 빌드 및 실행(Build and Run), 구현 세부 정보(Implementation Details), 아키텍처(Architecture) 설명에 중점을 둡니다.
• 계층적 적용: 리포지토리 루트 외에도 하위 폴더 (/frontend, /backend)에 특정 CLAUDE.md 파일을 배치하거나, 사용자의 홈 폴더(~/.claude/CLAUDE.md)에 개인 설정을 저장하여 컨텍스트를 계층적으로 적용할 수 있습니다.

2. 모델 컨텍스트 프로토콜 (MCP)

MCP는 LLM이 외부 도구와 상호작용하는 방식을 표준화하는 오픈 프로토콜입니다. 이를 통해 Claude Code는 코드베이스 외부의 광범위한 리소스에 접근하여 컨텍스트를 풍부하게 만듭니다.

• 주요 기능: MCP 서버를 통해 Jira 이슈 트래커의 기능 구현 요청을 받거나, Sentry 모니터링 데이터를 분석하거나, PostgreSQL 데이터베이스에 쿼리를 실행하거나, Figma 디자인을 통합하는 등의 작업을 수행할 수 있습니다.
• 컨텍스트 확장: MCP는 엔터프라이즈 검색, Windows 통합, Microsoft 365 (Outlook, Teams, OneDrive, SharePoint) 콘텐츠 분석 등 조직의 문맥을 연결하는 데 사용됩니다.
• 리소스 참조: MCP 서버가 노출하는 리소스는 파일처럼 @server:protocol://resource/path 형식으로 직접 참조하여 프롬프트에 포함할 수 있습니다.

3. 세션 위생 및 관리

긴 작업 흐름에서 문맥을 효율적으로 유지하고 오염을 방지하는 기술입니다.

• 컨텍스트 재설정: /clear 명령을 사용하여 대화 기록을 지우고 깨끗한 상태에서 새 작업을 시작하여 컨텍스트 창이 불필요한 정보로 가득 차는 것을 방지해야 합니다.
• 요약 스냅샷: 긴 세션에서는 스코프를 축소하고, 요약 스냅샷(이전 대화 핵심 요약 10줄 등)을 만들어 새로운 세션에 주입함으로써 컨텍스트를 효율적으로 유지할 수 있습니다.
• 체크포인트: 긴 작업이 분할 및 재개될 수 있도록 체크포인트를 생성하여 롤백 지점이나 작업 진행 상황을 저장합니다.

4. Skills (스킬)

Skills는 지침, 스크립트, 리소스를 폴더 단위로 묶어 Claude Code, Claude Console, API 등 Anthropic 제품군 전역에서 재사용할 수 있도록 만든 **"무코드 명령형 확장 모듈"**입니다.

• 기능: 팀의 집단 지식을 에이전트 레벨에서 재사용하고, 코드 품질 및 보안 규범을 자동 주입하며, 정책 일관성을 유지할 수 있습니다.
• 구조: 스킬 폴더는 SKILL.md (설명 및 메타데이터), prompts/, templates/, scripts/ 등의 구조를 가집니다.
• 동작 원리: Claude Code는 사용자의 명령을 분석할 때 등록된 스킬의 Trigger 조건을 스캔하고, 해당 스킬이 발견되면 자동으로 해당 프롬프트나 스크립트를 컨텍스트로 삽입합니다.

5. 명시적 컨텍스트 제공

프롬프트에 직접 관련 파일을 참조하거나 시각적 정보를 제공하여 컨텍스트를 보강합니다.

• 파일 참조: @ 기호와 파일 경로를 사용하여 파일의 전체 내용을 대화에 포함할 수 있습니다 (예: @src/utils/auth.js).
• 시각적 컨텍스트: 디자인 모형의 스크린샷, 오류 메시지, 아키텍처 다이어그램 등 이미지를 드래그 앤 드롭하거나 붙여넣어 시각적 컨텍스트를 제공할 수 있으며, Claude는 이를 분석하여 코드를 생성하거나 오류를 디버깅합니다.
• URL 참조: GitHub 이슈, 문서 또는 Stack Overflow 답변 등의 URL을 프롬프트에 붙여 넣어 Claude가 이를 읽고 컨텍스트로 활용하게 합니다.

02-2. 프롬프트 엔지니어링 (Prompt Engineering)

프롬프트 엔지니어링은 AI 모델에게 주는 입력(프롬프트)을 최적화하여 원하는 출력을 이끌어내는 과정이며, 특히 LLM이 목표를 달성할 수 있도록 명확하고 구조화된 지시를 제공하는 데 초점을 맞춥니다.

A. 효과적인 프롬프트 작성 원칙

B. 고급 프롬프트 엔지니어링 기법

1. 계획 후 실행 (Plan, then Execute)

단순 명령형 요구 대신 결과-형 목표를 제시하고, 코딩 전에 모델이 먼저 상세한 구현 계획을 세우도록 강제하는 것이 가장 효과적인 워크플로우 중 하나입니다.

• 프로세스: (1) 계획 모드로 옵션 비교표, 근거, 리스크, 복구 플랜 등을 요청합니다. (2) 합의 단계에서 계획을 검토하고 수정합니다. (3) 실행 단계에서 체크포인트를 생성하고 스몰 배치로 진행합니다.
• 활용: 복잡한 코딩 작업이나 대규모 리팩토링 시, 사전에 계획을 명문화함으로써 재작업 시간을 줄이고 성능을 향상시킬 수 있습니다.

2. 확장된 사고 (Extended Thinking) 활용

복잡한 아키텍처 결정, 어려운 버그 디버깅, 다단계 구현 계획 등 깊은 추론이 필요할 때 모델에게 추가적인 계산 시간을 할당하도록 요청합니다.

• 트리거: 프롬프트에 "think", "think hard", "think harder", "ultrathink"와 같은 키워드를 사용하여 모델의 사고 예산 수준을 높일 수 있습니다. 이는 단계적으로 더 많은 토큰 예산을 할당합니다.
• CoT (Chain of Thought): 단계별로 추론하도록 요청하여 중간 사고 과정을 보이게 하면 더 정확하고 체계적인 결과를 얻을 수 있습니다.

3. 출력 형식 제어

응답을 스크립트나 자동화 도구에서 사용하기 위해 특정 형식으로 출력하도록 요청합니다.

• 구조화된 데이터: JSON, CSV, 표 형식 등 구조화된 데이터로 응답을 요청합니다.
• 출력 포맷 플래그: Claude Code CLI에서 --output-format json 플래그를 사용하여 출력을 프로그래밍 방식으로 쉽게 구문 분석할 수 있도록 JSON 형식으로 받거나, stream-json을 통해 실시간 스트리밍 JSON으로 받을 수 있습니다.

4. 맞춤형 슬래시 명령어 (Custom Slash Commands)

반복적인 워크플로우나 긴 프롬프트 템플릿을 .claude/commands 폴더에 Markdown 파일로 저장하여 /command 형태로 재사용할 수 있습니다.

• 인수 활용: 슬래시 명령어 템플릿 내에 $ARGUMENTS를 사용하여 명령 실행 시 전달되는 인수를 프롬프트에 포함할 수 있습니다 (예: /fix-issue 123에서 123이 인수로 전달됨).
• 개인/팀 공유: 개인적인 명령어는 ~/.claude/commands에, 팀 공유 명령어는 프로젝트 내 .claude/commands에 저장합니다.

5. Few-shot 및 XML 태그 활용

• Few-shot 프롬프팅: 모델에게 몇 가지 예시를 제공하여 원하는 응답 패턴이나 형식을 학습시키고 유도합니다.
• XML 태그: <instruction>, <customer_feedback>, <output_format>과 같은 XML 태그를 사용하여 프롬프트의 다양한 구성 요소를 명확히 구분하고 구조를 인식하도록 돕습니다.

03. SubAgent & 병렬 실행

컨텍스트 엔지니어링 및 프롬프트 엔지니어링의 고급 전략으로, **서브 에이전트(SubAgent)**와 **병렬 실행(Parallel Execution)**은 대규모 작업의 효율성과 정확도를 극대화하기 위한 핵심 기술입니다. 이들은 복잡한 문제를 분해하고, 문맥을 격리하며, 작업 처리 속도를 높이는 데 사용됩니다.

03-1. 서브 에이전트 (SubAgents) 및 작업 위임 (Delegation)

서브 에이전트는 특정 역할을 수행하도록 특별히 구축된 보조 AI 도우미이며, 고유한 프롬프트, 도구, 그리고 격리된 컨텍스트 창을 가집니다. 이는 LLM의 작업을 '전문가 혼합(mixture-of-experts)' 방식으로 구성하여, 작업별로 필요한 전문 지식을 모델에 주입하는 역할을 합니다.

A. 서브 에이전트의 역할 및 이점

• 컨텍스트 효율성 극대화: 서브 에이전트를 사용하는 가장 중요한 이유 중 하나는 컨텍스트 사용을 극대화하는 것입니다. 주 에이전트가 복잡한 작업(busy work)을 서브 에이전트의 격리된 컨텍스트 창 내에서 처리하도록 위임함으로써, 주 대화 세션의 컨텍스트 창이 불필요한 정보로 가득 차는 것(오염)을 방지합니다.
• 전문화된 기능 수행: Claude Code는 적절한 작업을 전문 서브 에이전트에게 자동으로 위임합니다. 예를 들어, "최근 코드 변경 사항에 대해 보안 문제 검토를 해달라"고 요청하면 코드-리뷰어(code-reviewer) 서브 에이전트를 사용하도록 할 수 있습니다.
• 고품질 응답: 서브 에이전트는 특정 작업(계획, 리뷰, 디프)에 대한 **높은 신호 응답(high signal responses)**을 제공하며, 불필요한 부가 작업(side quests) 없이 핵심에 집중합니다.
• 역할 부여: 서브 에이전트 유형에는 api-designer, performance-optimizer, debugger subagent 등이 있으며, 복잡한 문제에 대해 아이디어를 브레인스토밍하는 데도 사용됩니다.

B. 서브 에이전트 설계 및 관리

서브 에이전트는 팀원들에게 작업 설명서를 제공하는 것처럼 관리되어야 합니다.

• 생성 및 관리:
  • /agents 명령을 사용하여 사용자 지정 AI 서브 에이전트를 관리할 수 있음.
  • 새 서브 에이전트를 생성할 때, 유형, 사용 시점, 접근 가능한 도구, 전문화된 시스템 프롬프트 등을 정의.
• 책임 분리 원칙:
  • 각 에이전트에게 하나의 명확한 책임을 정의.
  • 해당 역할에 필요한 최소한의 도구 세트만 유지해야 함.
• 읽기/쓰기 권한:
  • 분석 및 리뷰 작업에는 읽기 전용(read-only) 에이전트를 선호.
  • 쓰기 권한은 최소한의 에이전트에게만 부여.
  • 쓰기 권한을 특정 경로(src/ 나 tests/ )로 제한 가능.
• 버전 관리:
  • 에이전트 구성을 프로젝트 폴더(agents/) 내에 유지.
  • Git을 통해 버전 관리하고 PR(Pull Request)을 통해 팀과 공유 및 발전.
• 워크플로우 활용:
  • 코딩 작업의 대다수(bulk of the coding/review/testing)를 서브 에이전트에게 위임.
  • 주 Claude Code 인스턴스는 조직자(organiser) 역할만 수행하도록 하는 것이 모범 사례.

03-2. 병렬 실행 및 멀티-클로드 워크플로우 (Parallel Execution & Multi-Claude Workflows)

병렬 실행은 여러 개의 Claude Code 인스턴스를 동시에 실행하여 각 인스턴스가 격리된 환경에서 독립적인 작업을 처리하게 함으로써 전체 개발 속도를 높이는 전략입니다.

A. Git Worktrees를 통한 격리 및 병렬 처리

Claude Code에서 병렬 작업을 실행하는 가장 권장되는 방법은 Git worktrees를 사용하는 것입니다.

• Worktree 개념: Git worktrees는 동일한 리포지토리의 여러 브랜치를 분리된 디렉토리로 체크아웃할 수 있게 해주는 기능입니다. 각 작업 트리는 Git 히스토리를 공유하지만 독립적인 파일 상태를 가집니다.
• 병렬 세션: 각 작업 트리는 자체적인 작업 디렉토리를 가지므로, 각 worktree에서 독립적인 Claude Code 세션을 실행할 수 있습니다.
• 격리: 한 worktree에서의 변경 사항은 다른 worktree에 영향을 미치지 않으므로, Claude 인스턴스들이 서로 간섭하지 않고 동시에 다른 작업을 처리할 수 있습니다 (예: 하나는 인증 시스템 리팩토링, 다른 하나는 데이터 시각화 컴포넌트 구축).
• 설치 및 실행: git worktree add ../project-feature-a -b feature-a 명령으로 새 worktree를 생성하고, 해당 디렉토리에서 claude를 실행하여 독립된 환경에서 작업을 시작합니다.

B. 멀티-클로드 협업 전략

하나의 Claude 인스턴스가 계획, 코딩, 테스트를 모두 수행하게 하는 대신, 여러 인스턴스를 활용하여 협업함으로써 더 나은 결과를 얻을 수 있습니다.

1. 제작과 검증의 분리:
   • 코드 작성: 한 Claude 인스턴스에게 코드를 작성하도록 요청합니다.
   • 검토/테스트: /clear 명령으로 새 세션을 시작하거나, 두 번째 Claude 인스턴스를 다른 터미널에서 실행하여 첫 번째 Claude가 작성한 코드를 검토하거나 테스트하도록 합니다.
   • 피드백 적용: 세 번째 Claude 인스턴스(또는 새로운 클리어 세션)가 코드와 검토 피드백을 모두 읽고, 피드백에 따라 코드를 수정하도록 합니다. 이러한 분리는 단일 Claude가 모든 것을 처리하는 것보다 종종 더 나은 결과를 낳습니다.
2. 테스트 주도 개발(TDD) 병렬화:
   • 한 Claude가 테스트 케이스를 작성하고 커밋한 후, 다른 Claude가 해당 테스트를 통과시키는 코드를 작성하도록 지시할 수 있습니다.

C. 모델 선택을 통한 효율적인 병렬 처리

Anthropic의 모델 라인업은 병렬 처리에 최적화된 하이브리드 전략을 지원합니다.

• Haiku 4.5의 역할: Haiku 4.5는 경량 모델로, Sonnet 4급의 코딩 성능을 1/3 비용, 2배 이상의 속도로 제공합니다. 따라서 대규모 병렬 리서치, 문서 요약, 로그 분석, 검색 및 랭킹 후보 생성 등 서브 에이전트가 처리하는 백그라운드 작업에 배치하는 데 유용합니다.
• Sonnet 4.5의 역할: Sonnet 4.5는 복잡한 설계, 리팩토링, 긴 문맥 유지가 필요한 메인 태스크를 담당하는 데 적합합니다.
• 데이터 파이프라인 예시: 실제로 데이터 파이프라인 리팩토링 시, Haiku 4.5는 수천 줄의 로그를 요약하거나 패턴을 추출하는 병렬 작업에 사용되었고, Sonnet 4.5는 테스트 케이스 골격 자동 생성 및 복잡한 엔터프라이즈 검색을 위해 사용되어 비용-속도 최적화를 위한 모델 이원화 전략을 보여주었습니다.

D. 멀티 레포지토리 동시 변경 (Multi-Repository Orchestration)

병렬 실행 전략은 하나의 리포지토리를 넘어 여러 리포지토리에 걸친 대량 변경에도 적용됩니다.

• 구조: 루트 메타 레포(Root Meta-Repo)를 통해 전체 오케스트레이션을 담당하고, 이 레포에는 변경 제안서와 영향을 받는 레포 목록이 정리됩니다.
• 격리된 배치 적용: 각 서비스 레포지토리(service-A repo, service-B repo 등)에서 독립된 체크포인트를 생성한 후, 변경 사항을 병렬 배치로 적용합니다.
• 안전 게이트: 중앙 CI/CD 파이프라인에서 Rulelint, 보안 스캔 등의 게이트를 통과하는 과정을 거쳐 안전성을 확보합니다. 이 과정에서 **"읽기 전용 드라이런 → 승인 → 적용"**의 안전 원칙이 강제됩니다.

04. SuperClaude

SuperClaude에 대한 상세 정보는 주로 Anthropic이 아닌 SuperClaude-Org 커뮤니티에서 개발한 **메타 프로그래밍 구성 프레임워크 (meta-programming configuration framework)**를 기반으로 합니다. 이 프레임워크는 Claude Code의 에이전틱 코딩 역량을 체계화하고 확장하기 위해 설계되었습니다.

04-1. SuperClaude Framework (버전 4 기준)

SuperClaude는 Claude Code (Anthropic의 터미널 기반 에이전틱 코딩 도구)를 체계적인 개발 플랫폼으로 변환하는 것을 목표로 하는 구성 프레임워크입니다. 이는 행동 지침 주입(behavioral instruction injection)과 구성 요소 오케스트레이션을 통해 이루어지며, 강력한 도구와 지능형 에이전트를 활용하여 체계적인 워크플로우 자동화를 제공합니다.

참고: 이 프로젝트는 Anthropic의 공식 서비스가 아닌 오픈소스 프로젝트입니다.

1. 프레임워크의 주요 구성 요소 (Statistics)

SuperClaude Framework는 네 가지 핵심 구성 요소를 통해 Claude Code의 기능을 확장합니다:

프레임워크의 모든 명령은 다른 사용자 지정 명령과의 충돌을 피하기 위해 /sc: 접두사를 사용합니다.

2. 주요 기능 및 V4 업데이트 상세

SuperClaude V4 업데이트는 커뮤니티 피드백을 기반으로 하며, 에이전트 시스템과 통합 기능을 크게 개선했습니다.

A. 전문 에이전트 시스템 (16 Specialized Agents)

SuperClaude는 도메인 전문성을 갖춘 16개의 전문 에이전트를 제공하며, 문맥에 기반한 자동 조정을 통해 필요한 전문 지식을 즉시 제공합니다.

• PM Agent (프로젝트 매니저 에이전트): 체계적인 문서화를 통해 지속적인 학습을 보장합니다.
• Deep Research Agent (심층 연구 에이전트): 자율적인 웹 연구를 수행합니다.
• Security Engineer (보안 엔지니어): 실제 취약점을 포착합니다.
• Frontend Architect (프론트엔드 설계자): UI 패턴을 이해하고 적용합니다.

B. 행동 모드 (7 Adaptive Modes)

다양한 개발 단계와 작업 환경에 맞춰 Claude의 사고방식을 조정하는 7가지 적응형 모드를 제공합니다.

• Brainstorming (브레인스토밍): 올바른 질문을 던지도록 유도합니다.
• Business Panel (비즈니스 패널): 다중 전문가 전략 분석을 수행합니다.
• Deep Research (심층 연구): 자율적인 웹 리서치를 수행합니다.
• Orchestration (오케스트레이션): 도구의 효율적인 조정을 담당합니다.
• Token-Efficiency (토큰 효율): 컨텍스트 사용량을 30-50% 절약합니다.
• Task Management (작업 관리): 체계적인 작업을 조직화합니다.
• Introspection (자기 성찰): 메타인지적 분석을 가능하게 합니다.

C. Model Context Protocol (MCP) 서버 통합

SuperClaude는 8개의 강력한 MCP 서버를 통합하여, Claude Code의 외부 도구 연결 및 컨텍스트 확보 능력을 확장합니다.

3. 심층 연구 역량 (Deep Research Capabilities)

SuperClaude V4.2에서 도입된 심층 연구(Deep Research) 시스템은 자율적이고 지능적인 웹 리서치를 가능하게 합니다. 이 시스템은 DR Agent Architecture와 연동되어 작동합니다.

A. 적응형 계획 및 추론 (Adaptive Planning & Reasoning)

• 적응형 계획 (Adaptive Planning): 세 가지 지능형 전략을 사용합니다.
  • Planning-Only: 명확한 쿼리에 대한 직접 실행.
  • Intent-Planning: 모호한 요청에 대한 의도 명확화.
  • Unified (기본값): 협업적인 계획 개선.
• 다중 홉 추론 (Multi-Hop Reasoning): 최대 5회 반복 검색을 지원하며, 엔티티 확장(예: 논문 → 저자 → 작품), 개념 심화, 시간적 진행, 인과 관계 추적 등을 수행합니다.

B. 품질 관리 및 학습

• 품질 점수화 (Quality Scoring): 신뢰도 기반 검증을 사용하여 소스 신뢰도 평가(0.0~1.0), 커버리지 완전성 추적, 합성 일관성 평가를 포함합니다. 목표 신뢰도는 0.8이며 최소 임계값은 0.6입니다.
• 사례 기반 학습 (Case-Based Learning): 성공적인 쿼리 공식 저장, 패턴 인식 및 재사용, 전략 최적화 등을 통해 교차 세션 지능을 확보합니다.

C. 연구 명령 사용 예시

사용자는 /sc:research 명령을 사용하여 연구 깊이(--depth)나 전략(--strategy)을 제어할 수 있습니다.

4. 설치 및 지원

SuperClaude Framework는 pipx, pip, npm 등 다양한 패키지 관리자를 통해 설치할 수 있습니다.

• 설치 중요 사항: SuperClaude V3에서 업그레이드할 경우, V4 설치 전에 V3를 완전히 제거하고 관련된 .md 및 .json 파일(특히 commands/sc/ 경로 밖의 사용자 지정 파일 제외)을 삭제해야 충돌을 방지할 수 있습니다.
• 커뮤니티 지원: SuperClaude 프로젝트는 유지 관리 비용(예: Claude Max 구독료)이 발생하므로 코드 기여, 피드백, 재정적 지원 등을 통해 커뮤니티의 지원을 받는다고 명시하고 있습니다.

04-2. 컨텍스트 엔지니어링 및 프롬프트 엔지니어링과의 연관성

SuperClaude Framework는 기본적으로 이전 답변에서 다룬 컨텍스트 엔지니어링과 프롬프트 엔지니어링 기법을 구조화하고 자동화하는 데 중점을 둡니다.

1. 컨텍스트 엔지니어링의 구조화:
   • CLAUDE.md 관리: Claude Code는 CLAUDE.md 파일을 자동으로 컨텍스트로 불러와 프로젝트 규칙을 명시하는데, SuperClaude의 PM Agent는 이러한 문서화를 체계적으로 수행하도록 돕습니다.
   • MCP 확장: Claude Code의 핵심 기능인 MCP(Model Context Protocol) 서버 연결을 SuperClaude는 8가지 전문 서버를 통합하여 조직 문맥 연결 전략을 미리 패키징해 제공합니다.
2. 프롬프트 엔지니어링의 자동화:
   • 계획 후 실행(Plan-then-Execute): Claude Code의 공식 권장 루틴인 '계획 모드'를 사용한 설계→합의→실행 사이클은 SuperClaude의 26개 Slash Command와 7개 행동 모드를 통해 체계적으로 강제됩니다.
   • 역할 부여 및 분리: 프롬프트에서 특정 역할을 부여하는 기법을 SuperClaude는 16개의 전문화된 에이전트를 통해 구현함으로써, 특정 작업(예: 보안, 프론트엔드)을 위해 Claude의 사고방식(페르소나)을 자동 주입합니다.
   • 심층 추론 활용: 일반 Claude Code의 think, ultrathink 키워드를 사용한 확장된 사고 (Extended Thinking) 요청은 SuperClaude의 Deep Research 모드나 특정 에이전트 시스템에서 더욱 체계적인 다단계 추론(Multi-Hop Reasoning)으로 구현됩니다.

05. Agent Skills (Claude Skills)

Agent Skills는 지침(Instructions)·스크립트(Scripts)·리소스(Resources) 를 폴더로 묶어, Claude가 “관련 있을 때만” 자동으로 로드해 특정 업무를 더 잘 수행하게 만드는 무코드 명령형 확장 모듈입니다. Claude Code/콘솔/클라이언트 앱/메시지 API/Agent SDK 전반에서 재사용되며, 조직 문맥(브랜드 가이드, 보안 규정, 데이터 처리 방식 등)을 반복 가능한 능력으로 패키징합니다. 2025-10에 공식 도입되었습니다.

05-1. 핵심 개념과 목표

05-2. 왜 쓰는가 — 장점과 특징

• 일관성 & 품질 주입: 매 요청마다 프롬프트를 새로 짜지 않아도, 스킬에 박아둔 정책·형식·검사 규칙을 Claude가 자동 적용합니다(예: 브랜드/법무 규정, 린트·테스트 절차).
• 자동 활성화: 사용자 지시/맥락과 관련될 때만 로드되어 비용·속도를 아낍니다(불필요한 파일/지시를 덜 불러옴).
• 휴대성(Portable): 한 번 만든 스킬을 앱·Code·API 어디서든 같은 형식으로 재사용.
• 조합성(Composable): 여러 스킬을 함께 사용(예: “브랜드+법무+문서화”). Claude가 필요 스킬을 식별하고 조율합니다.
• 강한 실행력: 단순 생성이 아니라 실행 가능한 스크립트로 신뢰성 있는 처리를 붙일 수 있습니다(예: 대량 포맷 변환, 엑셀 수식 적용).

05-3. 스킬 폴더 구조(권장 스켈레톤)

my-skill/
├─ SKILL.md               # 목적/트리거/지침/출력
├─ prompts/
│  ├─ plan.md             # 계획(옵션 비교·리스크·롤백안)
│  ├─ apply.md            # 적용(체크포인트·배치·검증)
│  └─ rollback.md         # 롤백 절차
├─ scripts/
│  ├─ run_tests.sh
│  └─ lint_rules.sh
├─ templates/
│  ├─ PR_template.md
│  └─ changelog.md
└─ policy/
   ├─ rulelint.yaml
   └─ license_rules.json

• SKILL.md: Purpose/Triggers/Instructions/Outputs 등 메타·지침의 단일 진실원. 예: “refactor, migration 키워드 감지 시 체크포인트 강제·배치 50파일 제한·테스트 자동 실행”.
• 저장 위치: 프로젝트의 .claude/skills 또는 사용자의 ~/.claude/skills(엔터프라이즈는 중앙 배포 가능).

05-4. 동작 원리(자동 호출 파이프라인)

1. 트리거 감지: Claude가 사용자 요청을 해석하며 등록된 스킬의 트리거를 스캔.
2. 컨텍스트 삽입: 관련 스킬이면 해당 폴더의 지침·프롬프트·스크립트를 세션 문맥에 주입.
3. 절차 실행: 계획→합의→적용→검증 같은 정형 절차를 자동화(예: 체크포인트 강제, 테스트·린트 실행).
4. 안전 원칙: 멀티 레포 등 고위험 작업엔 **“드라이런→승인→적용”**을 템플릿으로 강제.

05-5. 제품군별 제작·배포·사용

A) Claude Code / 콘솔(웹 앱)

• 사전 탑재 스킬: 엑셀/파워포인트/워드/PDF 관련 문서 스킬은 자동 활성(유효 작업 시 백그라운드 적용).
• 스킬 생성기: 설정에서 skill-creator 스킬을 켜면 대화형으로 첫 스킬을 생성(폴더 구조·SKILL.md 자동 생성).

B) API / Agent SDK

• 스킬 첨부 전송: Messages API에 스킬을 명시 첨부 가능.
• 버전·배포: /v1/skills 엔드포인트로 업로드/버전 관리(조직 단위 공유 구성), 코드 실행 도구(보안 샌드박스) 활성 필요.
• 공개 예제 저장소: anthropics/skills에서 예시·가이드 확인 및 설치.

Tip: 엔터프라이즈는 스킬을 조직 표준 카탈로그로 운영하고, 변경은 PR로 심사→태깅→배포하세요.

05-6. 운영·보안·거버넌스 체크리스트

• 신뢰 가능한 소스만 활성화: 스킬은 스크립트를 실행할 수 있으므로 서명·소스 검증을 거친 후 배포. 엔터프라이즈 콘솔에서 조직 단위 허용 목록 운영.
• 실행 경계: Code Execution Tool 샌드박스에서만 실행(권한 요청·로그 남김).
• 감사 추적: 실행 로그·체크포인트·리포트를 CI 아티팩트로 보존.
• 규정 고정: 각 레포의 CLAUDE.md 에 “금지 변경·테스트·릴리즈 규정”을 명시하고, 스킬은 이를 준수하도록 설계(정책=CLAUDE.md, 실행=Skills).

05-7. CLAUDE.md vs Skills(겹치지 않음)

둘은 상호보완 구조입니다. 스킬 실행 중에도 Claude는 CLAUDE.md 정책을 참조·준수합니다.