Scaffold 구축 - Claude Code 완전 가이드

처음부터 자신만의 Claude Code 프로젝트 환경을 구축하는 단계별 가이드입니다. 이것이 이 가이드의 최종 목표입니다.

권장 디렉토리 구조

project-root/
  CLAUDE.md                     # 핵심 규칙 (200줄 이내!)
  .claude/
    settings.json               # 팀 공유 설정 (permissions, hooks, env)
    settings.local.json         # 개인 설정 (git-ignored)
    rules/
      code-style.md             # 항상 로드되는 코드 스타일
      testing.md                # 테스트 규칙
      security.md               # 보안 요구사항
      frontend/
        react-patterns.md       # 경로 스코프 (Glob: src/components/**)
    skills/
      fix-issue/
        SKILL.md                # /fix-issue 1234 워크플로우
      deploy/
        SKILL.md                # 수동 전용 (disable-model-invocation: true)
      api-conventions/
        SKILL.md                # 참조 문서 (user-invocable: false)
    agents/
      code-reviewer.md          # 읽기 전용 (tools: Read, Grep, Glob)
      debugger.md               # 전체 도구 (버그 수정용)
      security-reviewer.md      # 보안 전문 에이전트
    commands/
      *.md                      # 레거시 (skills/ 권장)
    hooks/
      scripts/                  # Hook 스크립트
      config/                   # Hook 설정 파일
  .mcp.json                     # 팀 공유 MCP 서버

8단계 구축 방법론

/init 실행 — 코드베이스 분석 기반 CLAUDE.md 자동 생성
공격적 프루닝 — Claude가 코드에서 추론할 수 있는 것은 모두 삭제
반복 교정 추가 — Claude가 실수할 때마다 규칙 추가 (Compounding)
반복 작업 스킬화 — 매일 여러 번 하는 작업을 Skill로 만들기
권한 설정 — /permissions로 안전한 명령 화이트리스트
Hooks 추가 — 자동 포매팅, 린팅, 보안 게이트 등 결정론적 자동화
전문 에이전트 추가 — 코드 리뷰어, 디버거 등 기능별 에이전트
테스트 & 반복 — Claude 행동 관찰. 규칙 무시시 = CLAUDE.md 너무 김

Progressive Disclosure (점진적 노출)

        ┌─────────────────────────────────┐
        │          CLAUDE.md              │
        │  매 세션 항상 로드 — 최소한의    │
        │        핵심 규칙만              │
        └─────────────────────────────────┘
       ┌─────────────────────────────────────┐
       │          .claude/rules/             │
       │  파일 접근 시 조건부 로드 —          │
       │         경로별 규칙                 │
       └─────────────────────────────────────┘
      ┌─────────────────────────────────────────┐
      │              Skills                     │
      │  호출 시에만 로드 — 재사용 가능한        │
      │    워크플로우, 컨텍스트 비용 0           │
      └─────────────────────────────────────────┘
     ┌─────────────────────────────────────────────┐
     │            Sub-Agents                       │
     │  생성 시에만 격리 실행 — 무거운 작업,        │
     │          별도 컨텍스트                       │
     └─────────────────────────────────────────────┘

WARNING: Claude가 규칙을 무시하면 CLAUDE.md가 너무 긴 것입니다. 줄이고, 분할하고, Rules로 이동하세요. "Claude는 자기 자신을 위한 규칙을 기이할 정도로 잘 작성합니다." — Boris Cherny