Claude Code 완벽 가이드: Skills, Hooks, Subagents로 AI 코딩 에이전트 200% 활용하기

티스토리 뷰

AI 지식

Claude Code 완벽 가이드: Skills, Hooks, Subagents로 AI 코딩 에이전트 200% 활용하기

pak2251 2026. 2. 27. 12:07

작성일: 2026년 2월 27일
카테고리: AI Engineering, Developer Productivity, Claude Code
키워드: Claude Code, Skills, Hooks, Subagents, MCP, Rules, Commands, 토큰 최적화, 컨텍스트 엔지니어링

요약

Claude Code는 설치만 하면 쓸 수 있지만, 제대로 설정하면 완전히 다른 도구가 된다. Anthropic 해커톤 우승자 affaanmustafa는 10개월간 매일 Claude Code를 사용하며 6대 확장 시스템(Rules, Skills, Commands, Hooks, Subagents, MCP)을 체계화했고, 이를 통해 토큰 사용량 50% 절감과 컨텍스트 윈도우 2배 확보를 달성했다. 이 글에서는 각 시스템의 역할과 관계, 토큰 최적화 전략, 메모리 지속성 패턴, 그리고 실전 워크플로우를 정리한다.

왜 Claude Code를 "설정"해야 하는가

Claude Code를 처음 설치하고 터미널에서 claude를 입력하면, 꽤 잘 동작한다. 파일을 읽고, 코드를 작성하고, 테스트를 돌린다. 그런데 2주 정도 쓰다 보면 반복되는 불편함이 쌓인다.

같은 지시를 매번 다시 타이핑한다. "TypeScript strict mode로 작성해", "테스트 먼저 짜", "console.log 남기지 마"
MCP를 10개 넘게 켜 놓았더니 응답이 느려지고, 실제 작업에 쓸 수 있는 컨텍스트가 줄어든다
어제 세션에서 발견한 디버깅 패턴을 오늘 또 처음부터 설명한다
간단한 탐색 작업에 Opus를 쓰면서 비용이 불필요하게 올라간다

이것은 마치 프로 운동선수가 운동화 하나만 신고 모든 종목에 출전하는 것과 같다. 기본 체력으로도 경기는 할 수 있지만, 종목별 전문 장비와 훈련 프로그램이 있으면 성과가 완전히 달라진다.

affaanmustafa(@affaanmustafa)는 10개월간 매일 Claude Code를 사용하며 이 문제를 체계적으로 해결했다. 그 결과물인 everything-claude-code는 공개 1주일 만에 GitHub 50,000 star를 넘겼고, Anthropic x Forum Ventures 해커톤에서 우승했다. 13개 에이전트, 48개 스킬, 32개 커맨드가 포함된 이 설정은 "어떻게 하면 Claude Code를 프로덕션 수준으로 쓸 수 있는가"에 대한 하나의 답이다.

이 글은 그의 Shortform Guide와 Longform Guide를 기반으로, 핵심 개념을 비유와 함께 정리한 한국어 종합 가이드다.

Claude Code 확장 시스템 전체 지도

Claude Code의 확장 시스템은 6개의 구성 요소로 이루어져 있다. 각각의 역할이 다르고, 서로 조합되어 작동한다.

graph TB
    User["개발자"]
    Claude["Claude Code (Orchestrator)"]

    Rules["Rules<br/>항상 적용되는 원칙"]
    Skills["Skills<br/>워크플로우 정의"]
    Commands["Commands<br/>슬래시 커맨드"]
    Hooks["Hooks<br/>이벤트 자동화"]
    Subagents["Subagents<br/>위임 에이전트"]
    MCP["MCP<br/>외부 서비스 연결"]

    User --> Claude
    Claude --> Subagents

    Rules -.->|"모든 동작에 적용"| Claude
    Skills -.->|"필요 시 로드"| Claude
    Commands -->|"사용자가 호출"| Skills
    Hooks -.->|"이벤트 발생 시 실행"| Claude
    MCP -.->|"외부 데이터 제공"| Claude
    Skills -.->|"스킬 위임"| Subagents

    style User stroke:#2563eb,stroke-width:3px
    style Claude stroke:#dc2626,stroke-width:3px
    style Rules stroke:#4b5563,stroke-width:2px
    style Skills stroke:#16a34a,stroke-width:2px
    style Commands stroke:#16a34a,stroke-width:2px
    style Hooks stroke:#ea580c,stroke-width:2px
    style Subagents stroke:#2563eb,stroke-width:2px
    style MCP stroke:#4b5563,stroke-width:2px

이 6가지를 회사 조직에 비유하면 이해가 쉽다:

시스템	비유	역할
Rules	회사 사규	모든 직원이 항상 따르는 규칙. "보안 정책을 준수하라"
Skills	업무 매뉴얼	특정 업무를 수행할 때 참고하는 절차서. "신규 기능 개발 매뉴얼"
Commands	내선 번호	매뉴얼을 빠르게 호출하는 단축키. `/tdd`를 누르면 TDD 매뉴얼이 열린다
Hooks	사내 알림 시스템	"퇴근 전에 자동으로 일일 보고서 생성". 조건이 충족되면 자동 실행
Subagents	부서별 전문가	CEO가 모든 일을 직접 하지 않고, 법무팀/보안팀/QA팀에 위임
MCP	외부 협력사 전화번호	GitHub, Supabase 등 외부 서비스를 직접 호출하는 연결선

6대 핵심 시스템 심층 해설

1. Rules: 항상 따라야 할 원칙

Rules는 Claude Code가 모든 대화에서 자동으로 참조하는 규칙이다. 프로젝트마다 다른 코딩 스타일, 보안 정책, Git 워크플로우를 Rules로 정의하면 매번 반복 지시할 필요가 없다.

두 가지 방식으로 관리할 수 있다:

방식 1: 단일 CLAUDE.md 파일

프로젝트 루트에 CLAUDE.md 하나로 모든 규칙을 관리한다. 소규모 프로젝트에 적합하다.

방식 2: Rules 폴더 (권장)

규칙을 주제별로 분리한다. 프로젝트가 커질수록 이 방식이 관리하기 쉽다.

~/.claude/rules/
├── coding-style.md      # 코딩 스타일 규칙
├── security.md          # 보안 규칙
├── testing.md           # 테스트 규칙 (80% 커버리지 필수)
├── git-workflow.md      # 커밋 포맷, PR 프로세스
└── performance.md       # 모델 선택, 컨텍스트 관리

실전에서 자주 쓰이는 규칙의 예:

# coding-style.md
- TypeScript strict mode 사용
- 함수는 단일 책임 원칙 준수
- 파일당 200줄 이내 유지
- console.log 커밋 금지
- 하드코딩된 시크릿 금지

Rules는 모든 세션에 자동 적용된다는 점이 핵심이다. "TypeScript strict mode로 작성해"라고 매번 타이핑하는 시간을 줄여준다.

2. Skills: 워크플로우의 레시피

Skills는 특정 작업을 수행하는 절차를 정의한 문서다. Rules가 "항상 따르는 규칙"이라면, Skills는 "필요할 때 꺼내 보는 레시피"다.

요리 레시피를 생각하면 된다. 냉장고(코드베이스)를 열 때마다 모든 레시피를 외울 필요는 없다. "된장찌개를 끓이겠다"고 결정한 순간에만 해당 레시피를 꺼내면 된다.

~/.claude/skills/
├── tdd-workflow/
│   └── README.md        # TDD 절차 정의
├── security-review/
│   └── README.md        # 보안 리뷰 체크리스트
├── coding-standards.md  # 코딩 표준
└── refactor-clean.md    # 리팩토링 절차

Skills의 강력한 점은 코드맵(codemap)을 포함할 수 있다는 것이다. 코드맵은 코드베이스의 구조를 요약한 정보로, Claude가 탐색에 토큰을 낭비하지 않고 바로 핵심 파일을 찾도록 돕는다.

3. Commands: 빠른 실행 단축키

Commands는 Skills를 호출하는 슬래시 커맨드다. 키보드 단축키처럼, 자주 쓰는 워크플로우를 짧은 명령어로 실행한다.

~/.claude/commands/
├── plan.md             # /plan "기능 설명"
├── tdd.md              # /tdd
├── e2e.md              # /e2e
├── code-review.md      # /code-review
├── build-fix.md        # /build-fix
└── refactor-clean.md   # /refactor-clean

Skills와 Commands의 관계:

/tdd (Command) → tdd-workflow/ (Skill) → 실행

Command는 진입점이고, Skill은 실제 절차다. TV 리모컨의 버튼(Command)을 누르면 해당 채널의 프로그램(Skill)이 실행되는 것과 같다.

4. Hooks: 이벤트 기반 자동화

Hooks는 특정 이벤트가 발생할 때 자동으로 실행되는 스크립트다. "~하면 ~해라"라는 IFTTT 스타일의 자동화 규칙이다.

6가지 Hook 유형이 있다:

Hook 유형	발동 시점	용도
PreToolUse	도구 실행 직전	위험한 명령 차단, 리마인더 표시
PostToolUse	도구 실행 직후	코드 포맷팅, 타입 체크
UserPromptSubmit	사용자 메시지 전송 시	입력 전처리
Stop	Claude 응답 완료 시	학습 내용 저장, 상태 정리
PreCompact	컨텍스트 압축 직전	중요 상태 백업
Notification	권한 요청 시	알림 처리

graph LR
    A["사용자 입력"] --> B["UserPromptSubmit"]
    B --> C["Claude 처리"]
    C --> D{"도구 호출?"}
    D -->|예| E["PreToolUse"]
    E --> F["도구 실행"]
    F --> G["PostToolUse"]
    G --> C
    D -->|아니오| H["응답 완료"]
    H --> I["Stop Hook"]

    style A stroke:#2563eb,stroke-width:2px
    style B stroke:#ea580c,stroke-width:2px
    style E stroke:#ea580c,stroke-width:2px
    style G stroke:#ea580c,stroke-width:2px
    style I stroke:#ea580c,stroke-width:2px
    style F stroke:#16a34a,stroke-width:2px

실전에서 가장 유용한 Hook 조합:

{
  "PostToolUse": [
    {
      "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\.(ts|tsx)$\"",
      "hooks": [
        {
          "type": "command",
          "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\""
        }
      ]
    }
  ],
  "Stop": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "grep -r 'console.log' --include='*.ts' src/ && echo '[Hook] console.log 발견됨' >&2 || true"
        }
      ]
    }
  ]
}

이 설정은 두 가지를 자동화한다:

TypeScript 파일을 편집할 때마다 자동으로 prettier를 실행한다
Claude가 응답을 마칠 때마다 코드에 console.log가 남아 있는지 검사한다

Hook을 직접 JSON으로 작성하기 번거롭다면, hookify 플러그인을 사용할 수 있다. "TypeScript 파일 수정 후 prettier 실행해줘"라고 말하면 Hook 설정을 자동 생성한다.

5. Subagents: 위임 전문가

Subagents는 메인 Claude(Orchestrator)가 특정 작업을 위임하는 전문 에이전트다.

CEO가 모든 업무를 직접 처리하지 않는 것과 같다. 법률 검토는 법무팀에, 보안 감사는 보안팀에, QA는 QA팀에 위임한다. 각 팀은 자기 전문 분야에 집중하고, CEO는 전체 방향을 조율한다.

~/.claude/agents/
├── planner.md              # 기능 구현 계획 수립
├── architect.md            # 시스템 설계 결정
├── tdd-guide.md            # 테스트 주도 개발 가이드
├── code-reviewer.md        # 코드 품질/보안 리뷰
├── security-reviewer.md    # 취약점 분석
├── build-error-resolver.md # 빌드 에러 해결
├── e2e-runner.md           # E2E 테스트 실행
├── refactor-cleaner.md     # 데드코드 제거
└── doc-updater.md          # 문서 업데이트

Subagent의 핵심 이점은 두 가지다:

첫째, 컨텍스트 분리. 메인 에이전트의 컨텍스트 윈도우를 소비하지 않는다. 코드 리뷰를 Subagent에 위임하면, 리뷰에 필요한 파일 읽기와 분석이 별도 컨텍스트에서 이루어진다.

둘째, 모델 선택. 작업 난이도에 따라 다른 모델을 쓸 수 있다. 간단한 탐색은 Haiku, 일반 코딩은 Sonnet, 아키텍처 결정은 Opus. 이것이 비용을 크게 줄인다.

6. MCP: 외부 세계와의 연결

MCP(Model Context Protocol)는 Claude Code를 외부 서비스에 연결하는 프로토콜이다. GitHub, Supabase, Vercel 같은 서비스를 프롬프트로 직접 호출할 수 있게 한다.

USB 허브를 생각하면 된다. 노트북에 USB 포트가 있지만, 동시에 꽂을 수 있는 장치 수는 제한되어 있다. MCP도 마찬가지다. 연결할 수 있는 서비스는 많지만, 동시에 활성화하면 성능이 떨어진다.

여기서 핵심 경고가 있다. Claude Code의 컨텍스트 윈도우는 200k 토큰이지만, MCP 도구 설명만으로도 상당한 양이 소비된다. MCP를 10개 이상 활성화하면 실제 사용 가능한 컨텍스트가 70k 수준으로 줄어들 수 있다.

200k (전체 컨텍스트) - 130k (MCP 도구 설명) = 70k (실제 작업 공간)

이것은 3m x 3m 책상을 가지고 있는데, 서류함을 올려 놓고 나면 실제 작업 공간은 1m x 1m밖에 안 남는 것과 같다.

권장 규칙: 설정에 20~30개 MCP를 등록하되, 동시에 활성화하는 것은 10개 이하, 활성 도구는 80개 이하로 유지한다.

토큰 최적화 & 비용 절감 전략

Claude Code를 매일 사용하면 토큰 비용이 빠르게 누적된다. affaanmustafa의 가이드에서 가장 실용적인 부분이 바로 이 토큰 최적화 전략이다.

전략 1: MCP 대신 CLI + Skills 조합

많은 MCP는 CLI 도구를 래핑한 것에 불과하다. GitHub MCP는 내부적으로 gh CLI를 호출하고, Vercel MCP는 vercel CLI를 호출한다.

MCP를 활성화하면 도구 설명이 컨텍스트에 상주하면서 토큰과 컨텍스트 공간을 동시에 소비한다. 반면 같은 기능을 CLI + Skills로 구현하면 필요할 때만 로드되므로 둘 다 절약된다.

MCP 방식:    [도구 설명 항상 상주] → 토큰 소비 + 컨텍스트 감소
CLI + Skill: [필요할 때만 로드]   → 토큰 절약 + 컨텍스트 확보

예를 들어, GitHub MCP 대신 /gh-pr 커맨드를 만들어 gh pr create를 감싸면 된다.

전략 2: Subagent 모델 선택

모든 작업에 Opus를 쓸 필요가 없다. 작업 성격에 따라 모델을 선택하면 비용이 크게 줄어든다.

작업	권장 모델	이유
파일 탐색, 검색	Haiku	빠르고 저렴. 정확한 위치를 찾는 단순 작업
단순 편집, 포맷팅	Haiku	지시가 명확한 기계적 작업
일반 코딩, 구현	Sonnet	비용 대비 성능 최적. 90%의 작업이 여기 해당
PR 리뷰	Sonnet	맥락 이해는 필요하나 깊은 추론은 불필요
문서 작성	Haiku	구조가 정해진 단순 작성
복잡한 아키텍처 결정	Opus	여러 파일의 관계를 파악하는 깊은 추론 필요
보안 분석	Opus	실수가 허용되지 않는 영역
복잡한 버그 디버깅	Opus	전체 시스템의 상호작용 이해 필요

핵심 규칙: 기본값은 Sonnet이다. Opus로 업그레이드하는 기준은 명확하다:

첫 시도에서 실패했을 때
5개 이상의 파일에 걸친 변경일 때
아키텍처 수준의 결정이 필요할 때
보안이 관련된 코드일 때

전략 3: 컨텍스트 윈도우 관리

Claude Code는 대화가 길어지면 자동으로 컨텍스트를 압축(compact)한다. 이 과정에서 초기 지시사항이나 중요한 컨텍스트가 손실될 수 있다.

효과적인 컨텍스트 관리 전략:

1) 계획 수립 후 컨텍스트 클리어

탐색과 계획에 사용한 컨텍스트는 구현 단계에서는 불필요하다. Plan mode에서 계획을 수립한 후, 구현 시작 전에 /compact로 탐색 컨텍스트를 정리하면 구현에 집중할 수 있는 공간이 확보된다.

2) 모듈식 코드베이스 유지

수천 줄짜리 파일 하나보다 수백 줄짜리 파일 여러 개가 낫다. Claude가 읽어야 하는 토큰이 줄어들고, 첫 시도에서 성공할 확률이 높아진다.

3) mgrep 활용

기본 grep 대비 약 50% 토큰을 절감할 수 있다. 50개 작업 벤치마크에서 약 2배 더 적은 토큰으로 유사하거나 더 나은 검색 품질을 보였다.

전략 4: pass@k로 검증 비용 판단

작업의 일관성 요구 수준에 따라 검증 전략이 달라진다.

pass@k: k번 시도 중 최소 1회 성공 확률
  k=1: 70%  |  k=3: 91%  |  k=5: 97%

pass^k: 모든 k번 시도가 성공할 확률
  k=1: 70%  |  k=3: 34%  |  k=5: 17%

"한 번이라도 되면 된다"(pass@k)와 "매번 되어야 한다"(pass^k)는 완전히 다른 기준이다. 프로토타이핑은 pass@k로 충분하지만, CI/CD 파이프라인은 pass^k가 필요하다.

메모리 & 지속적 학습

Claude Code의 가장 큰 한계 중 하나는 세션 간 기억이 끊긴다는 것이다. 어제 3시간 동안 디버깅하며 발견한 패턴을 오늘은 다시 처음부터 발견해야 한다.

affaanmustafa의 메모리 시스템은 이 문제를 3가지 레이어로 해결한다.

레이어 1: 세션 파일

각 세션의 상태를 마크다운 파일로 저장한다.

.claude/
├── sessions/
│   ├── session-2026-02-25.md
│   └── session-2026-02-26.md

각 세션 파일에는 세 가지를 기록한다:

작동한 접근법: 증거(로그, 출력 결과)와 함께
실패한 접근법: 왜 실패했는지와 함께
남은 할 일: 다음 세션에서 이어갈 작업

새 세션을 시작할 때 --system-prompt "$(cat memory.md)"로 이전 컨텍스트를 주입하면, 어제의 작업을 이어갈 수 있다.

# 모드별 컨텍스트 분리
alias claude-dev='claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"'
alias claude-review='claude --system-prompt "$(cat ~/.claude/contexts/review.md)"'

레이어 2: PreCompact & Stop Hook

두 개의 Hook이 메모리 자동 저장을 담당한다.

PreCompact Hook: 컨텍스트 압축이 일어나기 직전에 실행된다. 현재 작업 상태, 발견된 패턴, 미해결 이슈를 파일로 저장한다. 에어컨의 자동 온도 기록 기능과 비슷하다. 전원이 꺼지기 직전에 현재 설정을 저장해 두면, 다시 켤 때 같은 상태에서 시작할 수 있다.

Stop Hook: 세션이 끝날 때 실행된다. 이번 세션에서 발견한 디버깅 기법, 프로젝트 특정 패턴, 해결된 문제의 워크플로우를 추출하여 저장한다.

왜 UserPromptSubmit이 아닌 Stop Hook인가? UserPromptSubmit은 모든 메시지마다 실행되므로 매번 지연이 발생한다. Stop Hook은 세션 종료 시 1회만 실행되므로 가볍다.

레이어 3: Continuous Learning (지속적 학습)

가장 고급 패턴이다. Claude가 작업 중 비자명한(non-trivial) 발견을 하면, 그것을 자동으로 Skill로 변환하여 저장한다. 다음에 비슷한 문제가 발생하면 해당 Skill이 자동 로드된다.

세션 1: TypeScript에서 순환 참조 해결법 발견
    ↓ Stop Hook이 패턴 추출
    ↓ Skills로 변환하여 저장
세션 5: 비슷한 순환 참조 문제 발생
    ↓ 해당 Skill 자동 로드
    ↓ 이전 해결법을 즉시 적용

반복 프롬프트를 제거하는 것은 비용 절감이기도 하지만, 더 중요한 것은 시간 절감이다. 같은 설명을 반복 타이핑하는 시간이 0이 된다.

내 프로젝트에 적용하기: 실전 가이드

지금까지 6대 확장 시스템의 개념, 토큰 최적화 전략, 메모리 관리 패턴을 다뤘다. 이론은 충분하다. 이제 이 모든 것을 내 프로젝트에 실제로 적용하는 방법을 단계별로 정리한다.

everything-claude-code의 48개 스킬과 32개 커맨드를 한꺼번에 도입할 필요는 없다. 중요한 것은 내 프로젝트에서 반복되는 불편함을 먼저 진단하고, 그에 맞는 시스템을 하나씩 도입하는 것이다.

1단계: 반복 패턴 진단 (10분)

지난 1주일의 Claude Code 사용을 돌아보면서 아래 3가지를 적어본다.

질문 1: 매번 반복하는 지시가 있는가?

"TypeScript strict mode로 작성해", "테스트 먼저 짜", "커밋 메시지는 conventional commits로" 같은 지시를 매 세션 타이핑하고 있다면, 그것이 Rules의 후보다.

질문 2: 같은 실수가 반복되는가?

console.log가 커밋에 포함되거나, 포맷팅이 안 맞거나, 테스트 없이 코드가 작성된다면, 그것이 Hooks의 후보다.

질문 3: 컨텍스트가 부족하다고 느끼는가?

대화가 길어지면 초반 지시를 잊어버리거나, 파일을 많이 읽다 보면 응답 품질이 떨어진다면, 그것이 Subagents 분리의 신호다.

이 3가지 질문만으로 어떤 시스템을 먼저 도입해야 하는지 결정할 수 있다.

2단계: CLAUDE.md 작성 (15분)

프로젝트 루트에 CLAUDE.md를 만들고, 1단계에서 찾은 "반복 지시"를 정리한다. 처음부터 완벽할 필요 없다. 3~~5개 규칙으로 시작하고, 2주 동안 사용하면서 추가하면 자연스럽게 10~~15개로 늘어난다.

프론트엔드 프로젝트 (React + TypeScript):

# Project Rules

## 기술 스택
- React 18 + TypeScript 5.x + Vite
- 상태 관리: Zustand
- 스타일: Tailwind CSS
- 테스트: Vitest + Testing Library

## 코딩 규칙
- 컴포넌트는 함수형으로만 작성
- Props는 interface로 정의 (type 아님)
- 파일당 1개 컴포넌트 (index.ts 재수출 금지)
- console.log 커밋 금지

## 디렉토리 구조
- src/components/ - 재사용 가능한 UI 컴포넌트
- src/features/ - 기능별 모듈
- src/hooks/ - 커스텀 훅

## 테스트
- 새 컴포넌트 작성 시 반드시 테스트 파일 동반
- 테스트 파일명: *.test.tsx

백엔드 프로젝트 (Node.js + Express):

# Project Rules

## 기술 스택
- Node.js 20 + TypeScript
- Express + Zod (입력 검증)
- PostgreSQL + Drizzle ORM

## API 규칙
- RESTful 네이밍: /api/v1/{resource}
- 에러 응답은 { error: string, code: string } 형식
- 모든 입력은 Zod 스키마로 검증
- 환경변수는 반드시 env.ts에서 검증 후 사용

## 보안
- SQL 쿼리는 반드시 파라미터화
- 사용자 입력 직접 문자열 결합 금지
- 시크릿은 환경변수에서만 로드

Python 프로젝트 (FastAPI):

# Project Rules

## 기술 스택
- Python 3.12 + FastAPI
- SQLAlchemy 2.0 + Alembic
- 테스트: pytest + httpx

## 코딩 규칙
- 타입 힌트 필수 (Any 사용 금지)
- Pydantic 모델로 입출력 정의
- 비즈니스 로직은 service 레이어에 분리
- f-string 사용 (format() 금지)

핵심은 기술 스택, 코딩 규칙, 디렉토리 구조를 명시하는 것이다. Claude는 이 정보를 기반으로 프로젝트 컨벤션에 맞는 코드를 생성한다.

3단계: 첫 번째 Hook 추가 (10분)

가장 자주 겪는 실수를 방지하는 Hook을 .claude/settings.json에 추가한다. 앞서 Hooks 섹션에서 prettier 자동 실행과 console.log 감지 예시를 다뤘다. 여기서는 프로젝트 유형별로 바로 복사해서 쓸 수 있는 실전 설정을 정리한다.

TypeScript 프로젝트 — 파일 수정 후 타입 체크:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "tool == 'Write' || tool == 'Edit'",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\" 2>/dev/null; npx tsc --noEmit --pretty 2>&1 | head -20 || true"
          }
        ]
      }
    ]
  }
}

이 설정은 파일 수정 시마다 자동으로 포맷팅을 적용하고, 타입 에러가 있으면 즉시 보여준다. Claude가 타입 에러를 확인하고 스스로 수정하기 때문에, 코드 리뷰에서 "타입이 안 맞는다"는 지적이 사라진다.

Python 프로젝트 — 포맷팅 + 린트:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "tool == 'Write' || tool == 'Edit'",
        "hooks": [
          {
            "type": "command",
            "command": "black \"$TOOL_INPUT_FILE_PATH\" 2>/dev/null; ruff check \"$TOOL_INPUT_FILE_PATH\" 2>&1 | head -10 || true"
          }
        ]
      }
    ]
  }
}

위험 명령 차단 (모든 프로젝트):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "tool == 'Bash'",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$TOOL_INPUT\" | grep -qE 'rm -rf|git push --force|drop table' && echo 'BLOCK: 위험한 명령이 감지되었습니다' >&2 && exit 2 || true"
          }
        ]
      }
    ]
  }
}

이처럼 Hook은 "실수 방지"뿐 아니라 "코드 품질 자동 검증"과 "위험 행동 차단"까지 확장할 수 있다.

4단계: 자주 쓰는 커맨드 만들기 (10분)

.claude/commands/ 폴더에 반복되는 워크플로우를 커맨드로 정의한다. 매번 장문의 프롬프트를 타이핑하는 대신, 슬래시 커맨드 하나로 실행한다.

코드 리뷰 커맨드 (review.md):

현재 브랜치의 변경사항을 리뷰한다.

1. `git diff main...HEAD`로 변경사항 확인
2. 각 파일에 대해:
   - 버그 가능성 체크
   - 보안 취약점 체크 (입력 검증, SQL 인젝션, XSS)
   - 테스트 누락 여부 확인
3. 발견된 이슈를 심각도(높/중/낮)로 분류하여 보고

기능 계획 커맨드 (plan.md):

$ARGUMENTS 기능의 구현 계획을 수립한다.

1. 관련 코드 탐색 (기존 패턴 파악)
2. 변경이 필요한 파일 목록 작성
3. 단계별 구현 계획 작성
4. 엣지 케이스와 리스크 식별
5. 계획을 plan.md 파일로 저장

구현은 하지 않는다. 계획만 수립한다.

이제 /review로 코드 리뷰를, /plan 사용자 인증 기능으로 구현 계획을 즉시 실행할 수 있다.

5단계: Subagent 분리 (프로젝트가 커졌을 때)

컨텍스트 부족이 체감될 때 도입한다. 가장 효과가 큰 것부터 시작:

코드 리뷰 에이전트 (~/.claude/agents/code-reviewer.md):

# Code Reviewer

## 역할
코드 변경사항의 품질과 보안을 리뷰한다.

## 사용 도구
- Read, Grep, Glob (읽기 전용)

## 모델
- Sonnet (기본)

## 체크리스트
- [ ] 입력 검증 누락 여부
- [ ] 에러 핸들링 적절성
- [ ] 테스트 커버리지
- [ ] 보안 취약점 (OWASP Top 10)
- [ ] 네이밍 컨벤션 준수

Subagent로 분리하면 메인 대화의 컨텍스트를 소비하지 않으면서도 전문적인 리뷰가 가능하다.

6단계: MCP 정리 (월 1회)

등록된 MCP 목록을 확인하고, 실제로 사용하는 것만 활성화한다.

활성 유지: Context7 (문서 검색), Chrome DevTools (디버깅)
비활성화: 한 달간 사용하지 않은 MCP
CLI로 전환: GitHub MCP → gh CLI, Vercel MCP → vercel CLI

활성 MCP를 10개 이하로 유지하는 것만으로도 체감할 수 있는 성능 차이가 난다.

적용 효과 확인

설정 전후의 차이를 체감하는 지표:

지표	설정 전	설정 후
세션 시작 시 반복 지시	3~5회 타이핑	0회 (Rules가 처리)
포맷팅 관련 PR 코멘트	자주 발생	자동 포맷팅으로 해소
컨텍스트 부족으로 /compact	빈번	Subagent 분리로 감소
console.log 커밋 실수	가끔 발생	Hook이 자동 감지
코드 리뷰 프롬프트 작성	매번 장문 타이핑	`/review` 한 번

모든 것을 한꺼번에 도입하면 설정 자체가 프로젝트가 된다. CLAUDE.md 하나 → Hook 하나 → 커맨드 2~3개 순서로, 불편함이 발견될 때마다 하나씩 추가하는 것이 가장 현실적이다.

실전 사례: 글로벌 플러그인과 프로젝트 하네스의 공존

앞선 적용 가이드대로 프로젝트에 설정을 추가하다 보면, 자연스럽게 이런 질문이 생긴다.

"everything-claude-code를 글로벌(~/.claude/)에 설치했는데, 프로젝트별 .claude/ 설정과 어떻게 공존하는가? 둘 다 쓰면 충돌하지 않는가?"

이 질문은 Claude Code를 실무 프로젝트에 적용할 때 반드시 만나는 문제다.

설정 레이어링: 어떤 규칙이 우선하는가

Claude Code는 설정을 레이어(layer) 구조로 로드한다. 아파트 주소 체계를 생각하면 된다.

~/.claude/          ← 글로벌 설정 (시 조례: 모든 프로젝트에 적용)
프로젝트/.claude/   ← 프로젝트 설정 (아파트 규약: 이 프로젝트에만 적용)
CLAUDE.md           ← 프로젝트 루트 규칙 (세대 규칙: 가장 구체적)

글로벌에 everything-claude-code(ECC)의 48개 스킬, 32개 커맨드, 13개 에이전트가 설치되어 있고, 프로젝트에도 도메인 전용 설정이 있다면, 두 레이어가 동시에 로드된다.

실제 로드 순서:
~/.claude/rules/*.md        (ECC 범용 규칙)
~/.claude/agents/*.md       (ECC 범용 에이전트: code-reviewer, tdd-guide 등)
프로젝트/.claude/rules/*.md  (프로젝트 도메인 규칙)
프로젝트/.claude/agents/*.md (프로젝트 전문 에이전트)
프로젝트/CLAUDE.md           (프로젝트 최우선 규칙)

프로젝트 설정이 글로벌 설정보다 우선한다. 같은 이름의 커맨드가 양쪽에 있으면 프로젝트 버전이 실행된다.

두 가지 공존 전략

실무에서는 두 가지 접근이 있다.

전략 A: 독립 운영 — 프로젝트 설정만 사용

프로젝트/.claude/
├── rules/              ← 프로젝트 규칙만
├── agents/             ← 프로젝트 전문 에이전트만
├── commands/           ← 프로젝트 커맨드만
└── skills/             ← 프로젝트 스킬만

~/.claude/ (ECC)        ← 무시 또는 비활성화

장점	단점
컨텍스트 깔끔 (70k 이하 사용)	ECC 범용 기능 사용 불가
설정 충돌 없음	ECC 업데이트 혜택 못 받음
팀원 온보딩 간단	범용 리뷰/보안 기능 직접 구현 필요

전략 B: 선택적 통합 — 프로젝트 우선, 글로벌 보조

프로젝트/.claude/
├── rules/              ← 프로젝트 규칙 (최우선)
├── agents/             ← 프로젝트 전문 에이전트
├── commands/           ← /plan, /review는 프로젝트 버전으로 재정의
└── skills/             ← 프로젝트 스킬

~/.claude/ (ECC)
├── agents/code-reviewer.md      ← 상속하여 활용
├── agents/security-reviewer.md  ← 상속하여 활용
└── agents/tdd-guide.md          ← 상속하여 활용

장점	단점
범용 기능 + 도메인 특수성 모두 활용	컨텍스트 혼재 가능 (~130k 소비)
ECC 업데이트 자동 적용	설정 복잡도 증가
보안 리뷰, 코드 리뷰 등 즉시 사용 가능	규칙 충돌 모니터링 필요

권장: 독립 → 통합의 단계적 접근

둘 중 하나를 처음부터 정할 필요는 없다. 단계적으로 접근하면 된다.

graph LR
    P1["Phase 1<br/>프로젝트 하네스<br/>독립 구축"]
    P2["Phase 2<br/>ECC 상속 정의<br/>필요한 에이전트만"]
    P3["Phase 3<br/>통합 settings.json<br/>우선순위 명확화"]

    P1 --> P2
    P2 --> P3

    style P1 stroke:#2563eb,stroke-width:2px
    style P2 stroke:#ea580c,stroke-width:2px
    style P3 stroke:#16a34a,stroke-width:2px

Phase 1: 프로젝트 하네스를 독립적으로 완성한다.

프로젝트의 도메인 규칙, 전문 에이전트, 커맨드를 먼저 구축한다. 이 단계에서 ECC는 무시한다. 프로젝트 설정만으로 충분한지 확인하는 것이 목적이다.

프로젝트/.claude/
├── rules/
│   ├── api-conventions.md     # API 네이밍, 에러 포맷
│   ├── security-policy.md     # 프로젝트 보안 규칙
│   └── infra-constraints.md   # 인프라 제약사항
├── agents/
│   ├── domain-reviewer.md     # 도메인 로직 전문 리뷰어
│   └── deploy-coordinator.md  # 배포 조율 에이전트
└── commands/
    ├── deploy.md              # /deploy
    └── verify.md              # /verify

Phase 2: ECC에서 필요한 기능만 선별하여 상속한다.

프로젝트 하네스가 안정된 후, ECC의 범용 에이전트 중 프로젝트에 유용한 것만 활성화한다. 보통 code-reviewer, security-reviewer, tdd-guide 3개가 가장 투자 대비 효과가 크다.

Phase 3: 통합 설정으로 우선순위를 명확히 한다.

프로젝트 CLAUDE.md에 레이어링 정책을 명시한다.

# 설정 우선순위
1. 이 프로젝트의 .claude/rules/ (최우선)
2. 이 프로젝트의 CLAUDE.md
3. ~/.claude/rules/ (글로벌, 보조)

# ECC에서 상속하는 에이전트
- code-reviewer: 프로젝트 규칙 적용하여 리뷰
- security-reviewer: OWASP Top 10 기반 보안 분석

# ECC에서 상속하지 않는 에이전트
- doc-updater: 프로젝트 문서 구조가 다름
- e2e-runner: 프로젝트 전용 E2E 파이프라인 사용

의사결정 기준

어떤 전략을 선택할지는 프로젝트 상황에 따라 달라진다.

상황	권장 전략
소규모 사이드 프로젝트	ECC 글로벌만 사용 (프로젝트 설정 불필요)
1인 프로젝트, 도메인 규칙 있음	전략 A (독립 운영)
팀 프로젝트, 온보딩 중요	전략 A (독립 운영) + CLAUDE.md 문서화
기존 ECC 스킬을 적극 활용 중	전략 B (선택적 통합)
프로젝트가 성숙하고 규칙이 많음	Phase 1→2→3 단계적 접근

핵심은 "프로젝트 설정이 항상 우선한다"는 원칙이다. ECC는 프로젝트에 해당 기능이 없을 때 보조하는 역할이지, 프로젝트 규칙을 덮어쓰지 않는다.

실전 적용 사례: SaaS 프로젝트의 Claude Code 하네스

지금까지 다룬 개념을 실제 프로덕션 프로젝트에 적용한 사례를 살펴본다. imprun-harness는 API 과금 SaaS 프로젝트의 .claude/ 설정을 오픈소스로 공개한 것이다. NestJS 백엔드, Next.js 프론트엔드, Python/Fission 서버리스 함수, Kubernetes 인프라를 포함하는 멀티 레포 프로젝트에서 Claude Code의 6대 확장 시스템을 어떻게 조합했는지 보여준다.

패턴 1: Rules를 범용과 도메인으로 분리

프로젝트가 커지면 Rules 파일이 수십 개로 늘어난다. imprun은 이를 2계층 구조로 정리했다.

.claude/rules/
├── _core/                         ← 범용 규칙 (어떤 프로젝트에서든 재사용 가능)
│   ├── coding-standards.md        # TypeScript, Python, YAML 코딩 표준
│   ├── security-invariants.md     # 5대 보안 불변 원칙
│   ├── testing-standards.md       # 테스트 커버리지 기준
│   └── git-workflow.md            # 커밋 포맷, PR 프로세스
│
└── _imprun-specific/              ← 도메인 규칙 (이 프로젝트에서만 유효)
    ├── billing-pipeline.md        # 과금 파이프라인 상태 머신, DLQ 패턴
    └── cross-repo-dependencies.md # 3개 레포 간 의존성 매트릭스

_core/의 규칙은 "TypeScript strict mode 사용", "console.log 커밋 금지", "파일당 1개 컴포넌트" 같은 언어 수준 표준이다. 다른 프로젝트에 그대로 복사해도 동작한다.

_imprun-specific/의 규칙은 "5xx 응답은 과금에서 제외", "크레딧 차감 시 lockedAt으로 동시성 제어", "배포 순서는 infra → console → functions" 같은 비즈니스 로직 제약이다. 이 프로젝트의 맥락을 모르면 의미가 없다.

이 분리의 실용적 효과: 새 프로젝트를 시작할 때 _core/ 폴더를 통째로 복사하면 기본 코딩 표준이 즉시 적용된다. 도메인 규칙은 처음부터 새로 작성한다.

패턴 2: 도메인 전문가 에이전트 7인 체제

이 프로젝트는 7개의 Subagent를 정의했다. 각 에이전트는 프로젝트의 특정 영역만 담당한다.

.claude/agents/
├── architecture-reviewer.md   ← Opus  (설계 결정, 성능 분석)
├── billing-pipeline.md        ← Sonnet (과금 파이프라인 8단계 진단)
├── backend.md                 ← Sonnet (NestJS 인증, 과금 로직)
├── frontend.md                ← Sonnet (Next.js 대시보드, 결제 UI)
├── functions-dev.md           ← Sonnet (Python/Fission 서버리스 함수)
├── infra-ops.md               ← Sonnet (K8s, Helm, Envoy Gateway)
└── deploy-coordinator.md      ← Sonnet (크로스 레포 배포 조율)

주목할 점은 모델 선택 전략이다. 7개 중 6개는 Sonnet이고, Opus는 architecture-reviewer 1개에만 할당했다. 아키텍처 리뷰는 여러 레포에 걸친 변경의 파급 효과를 추론해야 하므로 깊은 분석이 필요하다. 나머지 작업은 도메인 규칙과 체크리스트가 명확하게 정의되어 있어 Sonnet으로 충분하다.

또 하나의 설계 결정: billing-pipeline 에이전트는 진단 전용(읽기 전용)이다. 코드를 수정하지 않고, PromQL/LogQL/SQL 쿼리로 파이프라인 상태만 분석한다. 수정이 필요하면 backend 또는 infra-ops 에이전트에 위임한다. "진단하는 사람"과 "수정하는 사람"을 분리하면 실수로 인한 장애를 방지할 수 있다.

패턴 3: 에이전트 협업 파이프라인

새 기능을 추가할 때 에이전트들이 순서대로 작업하는 패턴이 정의되어 있다.

graph LR
    A["architecture-reviewer<br/>(Opus)"] --> B["functions-dev<br/>(Sonnet)"]
    B --> C["deploy-coordinator<br/>(Sonnet)"]
    C --> D["billing-pipeline<br/>(Sonnet)"]

    A1["설계 평가<br/>과금 영향 분석"] -.-> A
    B1["함수 구현<br/>Vault 연동"] -.-> B
    C1["HTTPRoute 생성<br/>레포 동기화"] -.-> C
    D1["파이프라인<br/>통과 검증"] -.-> D

    style A stroke:#dc2626,stroke-width:2px
    style B stroke:#2563eb,stroke-width:2px
    style C stroke:#2563eb,stroke-width:2px
    style D stroke:#2563eb,stroke-width:2px
    style A1 stroke:#4b5563,stroke-width:1px
    style B1 stroke:#4b5563,stroke-width:1px
    style C1 stroke:#4b5563,stroke-width:1px
    style D1 stroke:#4b5563,stroke-width:1px

예를 들어, 새 스크래핑 함수를 추가하는 작업:

architecture-reviewer가 함수 설계를 평가한다. Stateless 제약을 만족하는지, 과금 대상 API인지 확인한다.
functions-dev가 FastAPI 함수를 구현하고 Vault에서 자격증명을 연동한다.
deploy-coordinator가 infra 레포에 HTTPRoute와 SecurityPolicy를 생성하고, console 레포의 환경변수를 동기화한다.
billing-pipeline이 Envoy Access Log → Alloy → VictoriaMetrics → NestJS → DB 전 구간을 검증한다.

각 에이전트는 자기 영역의 규칙(Rules)을 참조하므로, "인프라에서 SecurityPolicy를 빠뜨렸다"거나 "과금에서 5xx를 제외하지 않았다" 같은 실수가 자동으로 걸러진다.

패턴 4: Permission으로 위험 명령 차단

settings.json에서 Claude가 실행할 수 있는 명령의 범위를 명시적으로 통제한다.

{
  "permissions": {
    "allow": [
      "Bash(gh issue:*)",
      "Bash(gh pr:*)",
      "Bash(kubectl get:*)",
      "Bash(kubectl logs:*)",
      "Bash(kubectl describe:*)"
    ],
    "deny": [
      "Bash(kubectl delete:*)",
      "Bash(kubectl apply:*)",
      "Bash(helm uninstall:*)",
      "Bash(npm install:*)",
    ]
  }
}

허용 목록은 "읽기 전용" 명령뿐이다. kubectl get, kubectl logs, kubectl describe는 클러스터 상태를 조회만 하므로 안전하다. GitHub CLI도 이슈와 PR 조회만 허용했다.

거부 목록에는 클러스터를 변경하는 명령이 들어간다. kubectl delete나 kubectl apply는 프로덕션 서비스를 중단시킬 수 있고, helm uninstall은 전체 배포를 삭제할 수 있다. 이런 명령은 Claude가 실행할 수 없고, 반드시 사람이 직접 실행한다.

이 패턴은 앞서 다룬 "위험 명령 차단 Hook"의 상위 버전이다. Hook은 패턴 매칭으로 차단하지만, settings.json의 Permission은 도구 수준에서 원천 차단하므로 더 확실하다.

패턴 5: 크로스 레포 의존성을 Rules로 문서화

멀티 레포 프로젝트의 가장 큰 위험은 "레포 A에서 변경했는데 레포 B를 동기화하지 않는 것"이다. imprun은 이 의존성을 Rules 파일에 변경 영향도 매트릭스로 문서화했다.

변경 대상	영향받는 레포	필수 작업
console ext_authz 추가	infra	reference-grant.yaml 수정
console 환경변수 추가	infra	deployment.yaml 수정
functions 새 함수 추가	infra	HTTPRoute + SecurityPolicy 추가
infra Alloy 라벨 변경	console	PromQL 쿼리 수정

이 매트릭스가 Rules로 로드되면, Claude는 "console에 새 환경변수를 추가하겠습니다"라고 할 때 자동으로 "infra의 deployment.yaml도 수정해야 합니다"라고 안내한다. 사람이 기억에 의존하지 않아도 된다.

패턴 6: 메모리로 프로젝트 지식 축적

memory/MEMORY.md 파일에 프로젝트의 핵심 아키텍처, 에이전트 협업 패턴, 자주 사용하는 쿼리(PromQL, LogQL, SQL), 문제 해결 가이드를 누적한다. 새 세션을 시작할 때 이 파일이 자동으로 로드되므로, "이 프로젝트의 API 흐름이 어떻게 되는지" 매번 설명할 필요가 없다.

특히 효과적인 것은 문제 해결 가이드 섹션이다. "과금이 0으로 기록됨" 문제의 일반적 원인 3가지, "pending 청구서 적체" 문제의 디버깅 순서가 기록되어 있다. 이전에 해결한 문제가 재발하면 메모리에서 즉시 해결법을 찾을 수 있다.

이 사례에서 가져갈 것

imprun 하네스의 핵심은 "많이 설정하는 것"이 아니라 "설정 간의 연결"에 있다.

Rules가 에이전트의 행동 범위를 제한한다 (billing-pipeline 에이전트는 "5xx 무과금" 규칙을 항상 참조)
에이전트 간 협업 순서가 정의되어 있다 (설계 → 구현 → 배포 → 검증)
Permission이 에이전트가 할 수 있는 시스템 명령을 통제한다 (조회만 허용, 변경은 차단)
크로스 레포 의존성이 Rules로 명문화되어 동기화 누락을 방지한다
메모리가 프로젝트 지식을 세션 간에 이어준다

전체 구조는 github.com/imprun/imprun-harness에서 확인할 수 있다. 도메인 로직은 다르더라도, Rules 레이어링, 에이전트 분리 기준, Permission 설정 패턴은 다른 프로젝트에도 그대로 적용할 수 있다.

하네스 유지보수 시 주의할 점

.claude/ 설정이 10개 파일을 넘어가면, 설정 자체가 하나의 코드베이스가 된다. 코드와 동일한 유지보수 문제가 발생한다.

settings.local.json 위생 관리

Claude Code를 사용하면서 "이번만 허용"한 명령이 settings.local.json에 누적된다. 마이그레이션 스크립트, 일회성 git submodule 명령, 머지 충돌 잔해까지 섞이면 의도된 허용과 찌꺼기를 구분하기 어렵다. settings.json(팀 공유)과 settings.local.json(개인 로컬)의 역할을 명확히 구분하고, 로컬 파일은 월 1회 정리한다.

유사 스킬 통합

같은 도메인의 스킬이 여러 파일로 분산되면, 하나를 수정할 때 나머지도 동기화해야 하는 부담이 생긴다. 예를 들어 과금 진단, 과금 디버그, 과금 검증이 3개 스킬로 나뉘어 있다면, 하나의 스킬로 통합하고 커맨드(/billing-debug, /billing-verify)가 같은 스킬의 다른 섹션을 호출하도록 설정하는 것이 낫다.

에이전트 파일 적정 길이: 100~300줄

에이전트 파일이 500줄을 넘으면 로드될 때마다 컨텍스트를 과도하게 소비한다. 반대로 100줄 미만이면 에이전트에게 충분한 맥락을 제공하지 못한다. 상세한 코드 예시나 참조 정보는 references/ 폴더로 분리하고, 에이전트 본문에는 역할, 체크리스트, 판단 기준만 남긴다.

체크포인트 규칙은 검증 방법까지 포함

"cross-validation 확인"이라고만 적으면 에이전트가 실행 가능한 행동으로 전환하기 어렵다. "cross-validation 확인 — SELECT COUNT(*) FROM usage_billing WHERE state='pending' 실행 후 0건이어야 한다"처럼 검증 명령까지 포함해야 규칙이 실제로 동작한다.

설정은 코드와 같다. 작성보다 유지보수가 더 어렵다. 월 1회 설정 리뷰 루틴을 권장한다.

고급 워크플로우: 병렬 작업과 에이전트 파이프라인

기본 설정이 자리잡힌 후에는 Claude Code 인스턴스를 여러 개 활용하는 고급 패턴으로 넘어갈 수 있다. 이 패턴들은 프로젝트 규모가 커지거나, 여러 기능을 동시에 개발해야 할 때 효과적이다.

병렬 작업: Git Worktree

독립적인 기능을 동시에 개발할 때는 Git Worktree로 여러 Claude 인스턴스를 병렬 실행한다.

# 병렬 작업용 워크트리 생성
git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b

# 각 워크트리에서 별도 Claude 인스턴스 실행
cd ../project-feature-a && claude
cd ../project-feature-b && claude

Anthropic의 Boris는 5개 로컬 + 5개 업스트림 인스턴스를 제안했지만, 실전에서는 3~4개가 적정선이다. 그 이상은 머지 충돌과 조율 비용이 생산성 이득을 초과한다.

핵심 원칙:

각 인스턴스의 작업 범위를 명확히 정의한다
중첩되는 코드 변경을 최소화한다
/rename으로 모든 채팅에 이름을 붙인다

Two-Instance Kickoff

새 프로젝트를 시작할 때는 2개 인스턴스로 역할을 분리한다.

graph LR
    subgraph Instance1["Instance 1: 스캐폴딩"]
        S1["프로젝트 구조 설정"]
        S2["CLAUDE.md 작성"]
        S3["Rules, Agents 구성"]
    end

    subgraph Instance2["Instance 2: 연구"]
        R1["서비스 연결 조사"]
        R2["상세 PRD 작성"]
        R3["아키텍처 다이어그램"]
    end

    Instance1 --> Merge["합류"]
    Instance2 --> Merge
    Merge --> Dev["본격 개발 시작"]

    style S1 stroke:#2563eb,stroke-width:2px
    style S2 stroke:#2563eb,stroke-width:2px
    style S3 stroke:#2563eb,stroke-width:2px
    style R1 stroke:#16a34a,stroke-width:2px
    style R2 stroke:#16a34a,stroke-width:2px
    style R3 stroke:#16a34a,stroke-width:2px
    style Merge stroke:#dc2626,stroke-width:2px
    style Dev stroke:#dc2626,stroke-width:2px

Instance 1이 뼈대를 세우는 동안 Instance 2가 깊은 조사를 진행하면, 두 결과물이 합쳐져서 훨씬 빠르게 개발을 시작할 수 있다.

순차 단계 Orchestrator

대규모 기능 구현에는 단계별 에이전트 파이프라인이 효과적이다.

Phase 1: RESEARCH   → 탐색 에이전트    → research-summary.md
Phase 2: PLAN       → 계획 에이전트    → plan.md
Phase 3: IMPLEMENT  → TDD 가이드      → 코드 변경
Phase 4: REVIEW     → 코드 리뷰어     → review-comments.md
Phase 5: VERIFY     → 빌드 에러 해결자 → 완료 또는 루프백

핵심 규칙:

각 에이전트는 1개의 명확한 입력과 1개의 명확한 출력을 가진다
이전 단계의 출력이 다음 단계의 입력이 된다
단계를 건너뛰지 않는다
에이전트 간에 /clear를 사용하여 컨텍스트를 분리한다
중간 산출물은 반드시 파일로 저장한다

보안 참고사항

확장 시스템은 강력하지만, 보안 위험도 함께 커진다.

모든 MCP 서버는 잠재적 공격 표면이다
커뮤니티에서 공유되는 Skill은 실행 전에 코드를 검토해야 한다
CLAUDE.md가 포함된 외부 레포지토리를 클론할 때는 내용을 먼저 확인해야 한다

affaanmustafa는 이 문제를 해결하기 위해 AgentShield를 개발했다. 1,282개 테스트, 102개 정적 분석 규칙으로 보안을 자동 검사하며, --opus 플래그로 Red Team/Blue Team/Auditor 3중 파이프라인을 실행할 수 있다.

정리

Claude Code의 6대 확장 시스템을 한 문장으로 요약하면 이렇다:

Rules로 기본 원칙을 세우고, Skills로 워크플로우를 정의하고, Commands로 빠르게 호출하고, Hooks로 자동화하고, Subagents로 위임하고, MCP로 외부와 연결한다.

이 글에서 다룬 내용이 많지만, 핵심은 하나다. Claude Code는 "설치 후 바로 쓰는 도구"가 아니라 "프로젝트에 맞게 설정하는 플랫폼"이다. 같은 모델, 같은 비용을 쓰더라도 설정에 따라 결과물의 품질과 효율이 크게 달라진다.

@omarsar0의 조언이 이 전체를 관통한다: "초기에 재사용 가능한 워크플로우에 시간을 투자하라. 지루하지만, 모델과 에이전트 능력이 개선될수록 복합 효과가 발생한다."

« 2026/03 »
일	월	화	수	목	금	토
1	2	3	4	5	6	7
8	9	10	11	12	13	14
15	16	17	18	19	20	21
22	23	24	25	26	27	28
29	30	31

티스토리 뷰