콘텐츠로 이동

.claude/ Scaffold

/bonie:init이 생성하는 .claude/ 디렉토리 구조와 초기화 흐름을 정의한다.

Why this structure

프로젝트별 .claude/는 git 자산이다. 팀이 동일한 컨텍스트로 동작하도록 프로젝트 저장소에 커밋한다. 스캐폴딩을 자동화하여 일관된 초기 구조를 보장하면서도, 기존 설정을 보존하는 병합 전략으로 안전성을 확보한다.

System view

graph TD
    Init["/bonie:init"] --> Detect["환경 감지"]
    Detect --> Interactive["인터랙티브 설정"]
    Interactive --> Scaffold["디렉토리 생성"]
    Scaffold --> Claude["CLAUDE.md 생성"]
    Claude --> Gitignore[".gitignore 업데이트"]
    Gitignore --> Done["완료 보고"]

스캐폴딩 결과물

.claude/
├── CLAUDE.md                         # 프로젝트 컨텍스트 (@MEMORY.md import)
├── MEMORY.md                         # 영구 기억 (세션 시작 시 100% 로드)
├── TODO.md                           # 페이즈 기반 실행 계획
├── settings.json                     # 프로젝트 레벨 설정 (git commit)
├── settings.local.json               # 개인 설정 (gitignore)
├── .templates/                       # 컴포넌트 작성용 문서 템플릿
│   ├── agent.md, command.md, hook.md, rule.md, skill.md
├── agents/                           # 프로젝트 레벨 subagent
├── skills/                           # 프로젝트 레벨 skill
├── hooks/                            # 프로젝트 레벨 hook
├── rules/
│   ├── guides/                       # 코딩 가이드라인
│   └── project/                      # 프로젝트별 규칙
├── logs/
│   ├── decisions.md                  # 의사결정 기록 (observer)
│   ├── tech-debt.md                  # 기술 부채 추적 (observer)
│   ├── patterns.md                   # 패턴 감지 (observer)
│   └── timeline.md                   # 주요 이벤트 타임라인 (observer)
└── config/
    ├── session.json                  # 세션 컨텍스트
    └── snapshot.json                 # 세션 압축 스냅샷

Components

CLAUDE.md

  • Responsibility — 프로젝트 핵심 컨텍스트. 모든 세션 시작 시 자동 로드.
  • Auto-generated — 프로젝트명, 기술 스택, 빌드/테스트 커맨드, 디렉토리 구조, rules/ 참조
  • Manual — 아키텍처 결정, 비즈니스 로직 등 자동 감지 불가 항목

config/session.json

  • Responsibility — 현재 세션 컨텍스트. hook/skill이 상태를 기록/참조.
{
  "currentPhase": 2,
  "activeStack": ["typescript", "react"],
  "lastCompact": "2026-04-15T10:30:00Z"
}

config/snapshot.json

  • Responsibility — 세션 종료 또는 /compact 시 압축 스냅샷. 다음 세션 컨텍스트 복원.
{
  "timestamp": "2026-04-15T10:30:00Z",
  "summary": "...",
  "decisions": [],
  "openQuestions": []
}

Interactions

/bonie:init 실행 흐름

flowchart TD
    Start["/bonie:init"] --> Detect["1. 환경 감지"]
    Detect --> Scan["package.json, go.mod,\nCargo.toml 등 스캔"]
    Detect --> Git["git 상태 확인"]
    Detect --> Exists["기존 .claude/ 확인"]

    Exists --> Interactive["2. 인터랙티브 설정\n(AskUserQuestion)"]
    Interactive --> ConfirmStack["감지된 스택 확인/수정"]
    Interactive --> Preset["팀 규칙 프리셋 선택"]
    Interactive --> Plugins["카테고리 플러그인 선택"]

    Interactive --> Create["3. 디렉토리 생성"]
    Create --> GenClaude["4. CLAUDE.md 생성"]
    GenClaude --> UpdateGit["5. .gitignore 업데이트"]
    UpdateGit --> Report["6. 완료 보고\n→ /todo:plan 안내"]

병합 전략

기존 .claude/가 존재하는 경우:

Situation Behavior
.claude/ 없음 전체 스캐폴딩
CLAUDE.md 있음 보존, 누락 디렉토리/파일만 추가
rules/ 있음 기존 보존, 누락 하위 디렉토리만 추가
settings.json 있음 보존, 병합하지 않음
.templates/ 있음 기존 보존, 새 템플릿만 추가

원칙: 기존 파일은 절대 덮어쓰지 않는다. 사용자 확인 후 실행.

.gitignore 권장

# Bonie — 개인/세션 설정
.claude/settings.local.json
.claude/config/session.json
.claude/config/snapshot.json

Trade-offs

Benefit Cost
일관된 초기 구조 보장 스캐폴딩 로직 유지보수 필요
기존 설정 보존 (안전) 부분 업데이트로 구조 불완전할 수 있음
git 커밋으로 팀 공유 .gitignore 관리 필요

Constraints

  • 기존 파일 덮어쓰기 금지 (명시적 --force 제외)
  • .claude/ 구조는 L1 고정 — 다른 레이어가 변경 불가
  • settings.local.json과 config/는 반드시 gitignore

See also