Init Claude

init-claude Skill

> Multi-agent team으로 프로젝트를 분석하고 Claude Code 문서 초안을 생성/개선한다 (최종 확정은 사용자 검증 후). > P4 관계: 이 스킬은 "자동 생성 금지" 원칙의 예외가 아니라, 검증 가능한 초안 생성 + 사용자 승인 워크플로우. > 22개 원칙(references/guide-principles.md) 기준, 3-5회 적응형 PDCA 평가 루프로 9.0/10+ 달성. > > vs deepinit: deepinit은 모든 디렉토리에 AGENTS.md 생성. init-claude는 루트 문서 품질 최적화. > > 실행 모드: standard (기본, 3에이전트 병렬) | lightweight (단일 에이전트, no-MCP, 소규모 프로젝트용)

즉시 실행 프로토콜

1. PROJECT_PATH 확인 (인수 없으면 현재 디렉토리)
2. 기술 스택 자동 감지 (아래 참조)
3. Phase 1: Discovery — 3개 Agent tool 호출을 하나의 메시지에서 병렬 실행
4. 3개 에이전트 완료 알림 수신 후 Discovery Report 통합
5. Phase 2: Architect — 3계층 문서 초안 생성
6. Phase 3: 3-5 적응형 PDCA — 매 라운드 3개 Agent tool 병렬 호출
7. 최종 리포트 출력

기술 스택 자동 감지

Glob tool로 프로젝트 루트 파일을 검색하여 스택 판별:

• package.json → Node.js/TypeScript (pnpm-workspace.yaml → monorepo)
• build.gradle / pom.xml → Java/Kotlin
• Cargo.toml → Rust
• pyproject.toml / setup.py → Python
• go.mod → Go

감지 결과를 모든 에이전트 프롬프트의 컨텍스트로 전달.

Language Policy

Default: 팀의 주 언어. 교차 도구(Copilot/Cursor) 사용 시 영어 권장. 코드 예시의 BAD/GOOD 주석은 항상 영어. Details: references/language-policy.md

문서 소유권 모델

채점 전에 소유권을 확인한다. 소유권이 명확해야 C3/C4/C5가 충돌하지 않는다.

| 파일 | 소유 범위 | 허용 내용 | |------|----------|----------| | AGENTS.md | trap 설명 + BAD/GOOD | 유일한 trap 소스. 다른 파일에서 복사 금지 | | CLAUDE.md (root) | 구조 + 포인터 | trap은 AGENTS.md 참조만. 한줄 제약 요약 허용 | | .claude/CLAUDE.md | 규칙 인덱스 | rules 파일 목록 + 프로젝트 고유 규칙 | | .claude/rules/*.md | 도메인별 action | trap은 AGENTS.md #N 참조만. BAD/GOOD 복사 금지 |

7가지 평가 기준 + 채점 루브릭

| # | 기준 | 가중치 | |---|------|--------| | C1 | Line Budget | 2 | | C2 | Non-discoverability | 2 | | C3 | Single Source of Truth | 2 | | C4 | Trap Reference Coverage | 1 | | C5 | Practical Completeness | 2 | | C6 | Guide Compliance | 2 | | C7 | Consistency | 1 |

채점 보간 규칙: 앵커(10/8/5/0) 사이 소수점 점수 허용. 보간 기준: 앵커 조건 충족 여부 + 경미한 개선/결함 수. 예: C1이 148 lines면 10, 155 lines면 9 (8 앵커 충족 + 여유 있으므로 +1).

C1: Line Budget (w2)

wc -l CLAUDE.md AGENTS.md .claude/CLAUDE.md의 합계. (guide-principles의 "≤200 lines" 예산 기준)

• 10: ≤150 lines (여유 있음)
• 8: 151-200 lines (예산 내)
• 5: 201-250 lines (초과)
• 0: >250 lines

C2: Non-discoverability (w2)

각 trap에 대해 체크리스트 적용: (1)런타임 증상 명시 (2)컴파일/스타트업 미감지 (3)코드/설정에서 발견 불가 (4)BAD 예시 (5)GOOD 예시.

• 10: ≥90% trap이 5/5 체크 통과, false trap 없음
• 8: 75-89% 통과, 경미한 표현 문제만
• 5: 50-74% 통과, 일부 discoverable 항목 혼재
• 0: 현재 검증된 non-discoverable runtime trap 없음. 새 trap은 검증 후만 추가.`
• 파일 존재 = "검토 완료" 시그널이며, 향후 trap 추가 위치를 명시

주의 원칙: 이 스킬은 초안을 생성하며, 사용자의 수동 검증이 필수 (P4). 자동 생성된 trap은 반드시 사용자/팀이 검증한 후에만 최종 확정한다. AGENTS.md의 trap은 코드 스멜이다 (P5) — 코드가 개선되면 제거한다. 잘못된 문서는 올바른 코드를 무시하게 만든다 — 앵커링 위험 (P13).

교차 평가 권장: 최종 라운드에서 Codex/Gemini 등 외부 모델로 독립 채점 수행. C1은 반드시 wc -l로 라인 수 측정 지시. 모델 간 ±1.0 이상 차이나는 기준은 추가 개선 대상.

에러 핸들링

• Architect 실패: 오케스트레이터가 Discovery Report만으로 직접 작성 (Phase 2는 항상 진행 가능)

Phase 3: PDCA Evaluation Loop

최소 3라운드, 9.0 미달 시 최대 5라운드. 3라운드 후 9.0+ 달성 시 조기 종료 가능. 각 라운드마다 3개 Agent tool을 하나의 메시지에서 동시 호출한다.

매 라운드 실행 순서

1단계: 3개 에이전트 동시 호출 (모두 run_in_background: true) Agent tool 파라미터 형식은 Phase 1의 예시와 동일. description, subagenttype, model, runin_background, prompt 키를 사용.

• Practitioner (subagent_type="general-purpose", model="sonnet"):

입력: 문서 경로 전체 목록 + 해당 라운드 C5 시나리오 (스택별 시나리오 테이블에서 선택). 작업: (1) 각 문서를 Read tool로 읽는다 (2) 시나리오별로 문서만 보고 작업을 시뮬레이션한다 (3) 각 AGENTS.md trap을 회피할 수 있는지 확인한다. 출력: 시나리오별 PASS/FAIL + 실패 시 원인(어떤 정보가 부족했는지) + 구체적 수정 제안(어떤 파일에 무엇을 추가해야 하는지)

• Critic (subagent_type="general-purpose", model="sonnet"):

입력: 문서 경로 전체 목록. 작업: (1) 각 파일을 Read tool로 읽는다 (2) 파일 간 동일 문장/개념 중복 탐지 — 참조(AGENTS.md #N)와 코드 예시는 중복이 아님 (3) AGENTS.md에 discoverable 콘텐츠가 있는지 확인 (4) always-loaded 파일 라인 수 합산. 출력: 중복 목록(file:line ↔ file:line), discoverable 항목 목록, 라인 수 보고(always-loaded N줄)

• Evaluator (subagent_type="general-purpose", model="opus"):

입력: 문서 경로 전체 목록 + C1-C7 채점 루브릭 전문(각 기준 10/8/5/0점 앵커 포함, 위 '채점 루브릭' 섹션 참조). 작업: (1) 모든 문서를 Read tool로 읽는다 (2) 각 기준별 근거를 1-2줄로 작성 (3) 가중 평균 계산. 출력: C1-C7 각 점수(소수점 1자리) + 가중 평균 + Top 3 개선사항(파일:라인 수준 구체성)

2단계: 완료 알림 수신 대기 — Claude Code가 각 에이전트 완료 시 자동 알림. 3개 모두 완료될 때까지 다른 작업 가능. Agent tool이 runinbackground=true로 실행되면, Claude Code가 에이전트 완료 시 자동으로 결과를 반환한다. 반환된 텍스트가 오케스트레이터의 대화 컨텍스트에 직접 나타나므로 별도 조회가 불필요하다.

3단계: 결과 통합 + 교차 검증

• practitioner FAIL 항목 중 evaluator도 지적 → 우선 수정
• critic 중복 발견 → 즉시 수정
• evaluator 점수 < 8 인 기준 → 해당 영역 집중 수정

4단계: Edit/Write tool로 파일 수정

5단계: 점수 기록 후 다음 라운드 진행

라운드별 초점

| Round | Practitioner 시나리오 | Critic 초점 | Evaluator 초점 | |-------|---------------------|------------|---------------| | 1 | C5 시나리오 1-2 | AGENTS.md trap 적정성 | C2 + C5 | | 2 | C5 시나리오 3-4 | 파일 간 중복 탐지 | C3 + C4 | | 3 | C5 시나리오 5 + 재검증 | discoverable 콘텐츠 제거 | C1 + C5 | | 4 | 전체 시나리오 재실행 | 라인 수 최적화 | C1 + C3 | | 5 | 최종 통합 시뮬레이션 | 참조 무결성, 일관성 | C4 + C6 + C7 |

에러 핸들링

• 에이전트 타임아웃: 해당 역할만 재실행 (1회). 2회 연속 실패 → 건너뛰고 나머지로 진행
• 점수 하락: 하락 기준의 수정 사항 식별 후 해당 변경만 git revert 또는 수동 롤백
• 5라운드 후 9.0 미달: 사용자에게 현재 점수 + 병목 보고, 추가 라운드 여부 확인

산출물 형식 + 기존 문서 처리

각 라운드 후 C1-C7 스코어카드 출력 (형식은 references/sample-typescript-monorepo.md 참조). 모드별 처리:

• 기존 파일 있음: diff-aware로 개선. 기존 trap은 재검증 후 유지/제거.
• 필수 파일 누락: 필수 산출물 목록에서 누락된 파일은 신규 생성.
• 기존 trap 재검증 후 0건: AGENTS.md는 유지하되 empty-state 템플릿으로 갱신.

git diff 제공.

유지보수 원칙 (P14-P16): 문서는 코드와 함께 버전 관리. 코드 리팩토링 시 관련 trap 재검증. AGENTS.md가 줄어드는 것은 좋은 신호 (P15).

참조 문서

• references/guide-principles.md: 22개 문서 작성 원칙 (P1-P22)
• references/sample-typescript-monorepo.md: 실제 프로젝트 적용 사례 (C1-C7 9.0+)
• SKILL-EVAL.md: 이 스킬 자체의 품질 평가 기준 (S1-S8)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: goddaehee
• Source: goddaehee/init-claude-plugin
• License: MIT

Install and usage instructions live in the source repository linked above.