name: context-builder
description: 프로젝트 컨텍스트 문서를 자동 생성하여 새 세션에서 AI가 빠르게 프로젝트를 이해하도록 돕습니다. "컨텍스트 정리", "프로젝트 요약", "온보딩 문서", "CLAUDE.md 갱신" 요청 시 활성화됩니다.

컨텍스트 빌더

활성화 조건

• "컨텍스트 정리", "프로젝트 요약", "현황 정리" 요청
• "온보딩 문서", "프로젝트 소개 문서" 요청
• "CLAUDE.md 갱신", "프로젝트 설정 업데이트" 요청
• 새 프로젝트 초기 설정 시
• 대규모 리팩터링 후 컨텍스트 재정리 필요 시

다른 스킬과의 차이

• context-builder: AI가 프로젝트를 이해하기 위한 메타 문서. 세션 간 지식 전달.
• document: 사람이 읽는 기술 문서 (API, 아키텍처 등).
• pm: 태스크 계획. context-builder는 프로젝트 현황 스냅샷.

생성 대상

실행 절차

Step 1: 프로젝트 스캔

코드베이스를 분석하여 자동 추출:

수집 항목:
- package.json / pyproject.toml / build.gradle 등 → 기술 스택
- 디렉토리 구조 → 아키텍처 패턴
- .eslintrc / ruff.toml 등 → 코드 스타일 컨벤션
- git log → 최근 작업 흐름
- 기존 CLAUDE.md → 현재 설정

Step 2: 기존 컨텍스트 확인

• .claude/context/ 디렉토리에 기존 문서가 있는지 확인
• 있으면 diff 기반 업데이트, 없으면 신규 생성
• CLAUDE.md가 있으면 보존하고 보강 제안

Step 3: 컨텍스트 문서 생성/갱신

CLAUDE.md 갱신 시:
- 기존 내용 보존 (사용자 커스텀 영역)
- 자동 감지된 스택/구조 정보 업데이트
- 스킬 라우팅 테이블 현행화

아키텍처 맵 생성 시:

## 아키텍처

### 디렉토리 구조
src/
├── api/          # [역할 설명]
├── services/     # [역할 설명]
└── models/       # [역할 설명]

### 데이터 흐름
[Request → Router → Service → Repository → DB]

### 핵심 모듈 의존성
[모듈 간 관계 설명]

기술 스택 생성 시:

## 기술 스택

| 영역 | 기술 | 버전 | 비고 |
|------|------|------|------|
| 런타임 | Node.js | 20.x | |
| 프레임워크 | Next.js | 15.x | App Router |
| DB | PostgreSQL | 16 | Prisma ORM |

Step 4: 검증 및 보고

• 생성된 문서가 실제 코드와 일치하는지 확인
• 추측으로 채운 부분은 [확인 필요]로 표시
• 사용자에게 검토 요청

Thinking Cycle (필수)

모든 작업에 사고 사이클을 적용한다. 상세: ../_shared/resources/thinking-cycle.md

1. 질문: 실행 전 최소 1개 소크라테스 질문 → 답변 전 진행 금지
2. 결정: 트레이드오프 존재 시 선택지 제시 → 근거 있는 선택 요구
3. 실행: Phase 0, 1 완료 후에만 진입
4. 코드 리딩: 변경 코드 이해도 점검 (레벨 C 기본)
5. 회고: 작업 완료 후 사용자 회고 → .claude/reflections/YYYY-MM-DD.md에 기록

핵심 규칙

1. 자동 감지 우선: 설정 파일과 코드에서 최대한 자동 추출
2. 기존 문서 보존: CLAUDE.md 등 사용자가 작성한 내용은 절대 삭제하지 않음
3. 추측 표시: 자동 감지가 불확실한 부분은 [확인 필요] 명시
4. 토큰 효율: 컨텍스트 문서는 간결하게. AI가 읽는 문서이므로 장황한 설명 불필요.
5. 갱신 가능: 한 번 생성하고 끝이 아니라, 프로젝트 변화에 따라 재실행

보고 형식

## 컨텍스트 빌드 결과

### What
- [생성/갱신한 문서 목록과 위치]

### Why
- [컨텍스트 빌드 이유]

### Result
- 아키텍처: [핵심 구조 한 줄 요약]
- 기술 스택: [주요 기술 나열]
- 컨벤션: [핵심 규칙 수]
- [확인 필요] 항목: N건

참조 리소스

resources/ 참조:
- 실행 프로토콜: execution-protocol.md
- CLAUDE.md 템플릿: claudemd-template.md
- 에러 대응: error-playbook.md