init-project
목적
휴대용 번들로 새 프로젝트의 에이전트 문서화 시스템을 한 번에 부트스트랩합니다. 초기화 후 프로젝트는 배포된 표준(doc-organization.md §8.3 결정 트리 + 휴대용 메타 표준)을 사용하여 자체 유지보수합니다. init은 프로젝트당 한 번 실행되며, update는 나중에 해당 프로젝트에서 다시 실행하여 번들에서 최신 휴대용 파일을 가져올 수 있습니다(3방향 안전 병합 — 승격되지 않은 로컬 편집을 절대 덮어쓰지 않음). check/promote는 번들 자체를 유지보수하며 이 마스터 저장소에서만 실행됩니다.
의존성
./portable/rules/ — 7개의 휴대용 규칙(항상 로드됨 + 경로 범위)./portable/agent-guide/ — five-why.md, markdown.md, mermaid.md, orchestration-policy.md, worktree.md (docs/agent-guide/general/에 배포)./portable/skills/ — skill-designer/, skill-writer/, document-writer/ (전체 트리)./portable/agents/ — skill-writer-auditor.md./templates/ — CLAUDE.md.tpl, agent-guide/index.md.tpl, docs/index.md.tpl./VERSION — 번들 버전, 모든 승격 시 증가scripts/update.mjs (저장소 루트) — update 모드용 엔진(3방향 번들→실행 중 병합); scripts/sync-version.mjs — 버전 단일 소스 동기화
모드
| 호출 | 실행 위치 | 동작 |
|---|
/init-project | 새 프로젝트 | 번들 배포 (아래 워크플로우) |
/init-project check | 마스터 저장소 | §맵에 따라 번들 ↔ 실행 중 파일 sha256 비교 → 차이 보고 |
/init-project promote | 마스터 저장소 | 매핑된 모든 파일에 대해 실행 중 → 번들 복사, VERSION 증가 |
/init-project update | 초기화된 프로젝트 | 최신 휴대용 파일 번들 → 실행 중, 3방향 안전 (매니페스트 ↔ 실행 중 ↔ 번들); 충돌 건너뜀 (아래 워크플로우) |
워크플로우 (init — 새 프로젝트)
- 프로젝트 스캔:
## module matrix 신호 열에 따라 스택 + 선택적 모듈 감지. 출력: 제안된 모듈 세트 + 발견된 슬롯 값.
- 인터뷰: 제안된 모듈 세트 확인; 스캔 불가능한 슬롯 질문 (사용 중인 개발 포트, 범위 소유권, 문서 언어). 답변 불가능 슬롯 → TODO 마커 남기고, 값을 절대 임의로 생성하지 않음; 모듈 불확실 → 건너뜀.
portable/ 그대로 복사: portable/rules/* → .claude/rules/; portable/agent-guide/* → docs/agent-guide/general/; portable/skills/* → .claude/skills/; portable/agents/* → .claude/agents/.- 템플릿 렌더링: 인터뷰에서 얻은
{{slots}}를 CLAUDE.md, docs/agent-guide/index.md, docs/index.md에 채움; 누락된 슬롯 → TODO 마커 유지.
- 선택적 규칙 생성: 확인된 각 선택적 모듈에 대해
rule-writing-standards에 따라 프로젝트에 맞춘 규칙을 docs/agent-guide/general/에 작성하고, 같은 단계에서 트리거 라인을 CLAUDE.md에 추가 — 하드코딩된 템플릿 없음.
- 매니페스트 작성
.claude/init-manifest.json: { version, deployedAt, files:[{path,sha256}], templates:[{path,sha256}], modules:[...] } (출처; files[]는 update에서 3방향 드리프트 감지를 위해 읽음 — sha256 정확히 유지; templates[]는 각 렌더링된 파일이 빌드된 .tpl sha를 기록 — path = templates/에 상대적인 템플릿 경로 (예: CLAUDE.md.tpl), update에서 템플릿이 배포 이후 변경되었을 때 WARN을 발행하는 데 사용).
- 검증: 모든 배포 파일이 올바른 계층에 있는지; 모든 규칙/에이전트-가이드 파일이
scope: 프론트매터를 가지고 있는지; CLAUDE.md가 토큰 예산 내에 있는지; 모든 행동에 영향을 미치는 온디맨드 파일에 트리거 라인 또는 라우터 항목이 있는지 (도달 가능성, 파일→트리거); 모든 MUST Read 트리거가 CLAUDE.md에서 배포된 파일로 연결되는지 (도달 가능성, 트리거→파일 — 죽은 트리거 없음); 의도적인 TODO 마커를 제외하고 렌더링되지 않은 {{slot}}이 없는지. 완료 = 체크리스트 통과 + 매니페스트 기록됨.
번들 ↔ 실행 중 맵 (check / promote — 마스터 저장소; update — 초기화된 프로젝트)
| 번들 경로 | 실행 중 경로 |
|---|
portable/rules/* | .claude/rules/* |
portable/agent-guide/* | docs/agent-guide/general/* |
portable/skills/* | .claude/skills/* |
portable/agents/* | .claude/agents/* |
check: 각 쌍 sha256 → 불일치 목록. 기본 업데이트 방향은 실행 중 → 번들 (promote); 실행 중을 먼저 수정한 후 승격.promote: 매핑된 모든 파일에 대해 실행 중 → 번들 복사, 그런 다음 node scripts/sync-version.mjs set <x.y.z>를 통해 버전 증가 (정식 VERSION 기록 + .claude-plugin/* 및 README 배지에 미러링).
워크플로우 (update — 초기화된 프로젝트)
방향 번들 → 실행 중 (promote의 반대). 그대로 복사된 휴대용 세트에만 영향을 미침; 렌더링된 표현형(CLAUDE.md, index.md, 프로젝트 작성 가이드)은 범위 밖입니다. 설치된 플러그인 내부의 경로로 update.mjs를 호출합니다 (플러그인이 자신의 위치에서 번들을 찾음); --project는 초기화된 프로젝트 루트이며 기본값은 현재 디렉터리입니다.
- 드라이런:
node <plugin>/scripts/update.mjs --project <project-root> → ADD / UPDATE / CONFLICT 계획 및 버전 델타 검토.
- 먼저 모든 CONFLICT 해결 — 충돌 = 배포 이후 로컬에서 편집된 휴대용 파일. 업스트림으로 승격 (개선 사항이 번들에 들어가도록) 또는 검토 후 수동으로 덮어씀. 절대 블라인드 덮어쓰기 금지.
- 적용:
node <plugin>/scripts/update.mjs --apply --project <project-root> → ADD + UPDATE 작성, 충돌 건너뜀, 매니페스트 version + files[].sha256 갱신.
- 추가 및 제자리 수정만 —
update는 절대 삭제하지 않음: 번들에서 제거된 파일은 프로젝트에 남아 있고, 로컬에서 삭제된 파일은 다시 추가됨. 필요시 수동으로 정리.
templates/* (CLAUDE.md, index.md — 렌더링된 표현형)는 절대 덮어쓰지 않음: 해당 슬롯은 프로젝트별 값을 보유함. update는 배포 이후 .tpl이 변경되었을 때만 WARN을 발행함 (sha vs manifest.templates[]); 수동으로 다시 렌더링 (.tpl과 실행 중 파일 비교, 구조적 변경 사항 재적용, 슬롯 값 유지) 또는 /init-project 재실행. WARN은 다음 init이 템플릿 sha를 다시 기록할 때까지 지속됨.
- 종료 코드: 0 = 최신 상태이거나 깔끔하게 적용됨; 1 = 충돌이 남아 있음; 2 = 설정 오류 (매니페스트 없음 → 프로젝트가 이 플러그인으로 초기화되지 않음).
모듈 매트릭스
| 모듈 | 포함 항목 | 배포 시기 | 스캔 신호 (예시, 완전하지 않음) |
|---|
| 핵심 | portable/* (4개 그룹 모두) + 3개 템플릿 | 항상 | — |
| 런타임 | agent-guide/general/local-runtime.md + CLAUDE.md 트리거 (스캔에 따라 스킬이 작성, 5단계) | 프로젝트가 자체적으로 dev 서버를 실행 | package.json dev/start 스크립트, launchSettings.json, vite/next/dotnet/django/cargo 설정 |
| e2e | agent-guide/general/<도구>.md (감지된 도구 이름으로) + CLAUDE.md 트리거 (5단계) | 프로젝트에 E2E 브라우저 테스트 존재 | playwright/cypress/selenium 의존성, e2e/ 폴더, E2E 설정 |
- 선택적 모듈은 스캔이 확인하거나 사용자가 인터뷰에서 확인한 경우에만 배포됨; 불확실 → 건너뜀.
- Git: 최소 보호 장치 (요청 시에만 커밋, 절대 푸시 금지)는
CLAUDE.md.tpl에 포함됨; 상세 정책은 scope: project — 프로젝트가 필요 시 docs/agent-guide/general/git.md를 작성하고, 같은 커밋에서 트리거 라인을 추가함 (도달 가능성 — 존재하지 않는 파일을 가리키는 트리거 금지).
- 나중에 건너뛴 모듈이 필요해지면 → 프로젝트가 배포된 표준에 따라 규칙을 직접 작성함. 새 모듈은 실제 프로젝트에서 패턴이 검증된 후에만
promote를 통해 번들에 들어감.
독립성 규칙
- 스킬은 프로젝트당 한 번 실행됨; 배포된 파일은 이 마스터 저장소의 어떤 파일도 참조하지 않음; 프로젝트 규칙은 이 스킬을 절대 언급하지 않음.
- 위의 번들↔실행 중 맵을 제외하고 자체 포함됨; 이 맵은 check/promote를 위해 마스터 저장소에서만 실행됨.
예시
✅ 스캔 결과 package.json에 "dev" 스크립트 발견 → 런타임 모듈 제안 → 5단계에서
general/local-runtime.md 작성 + CLAUDE.md에 "self-run dev 서버 → MUST Read ..." 추가
❌ 스캔 신호도 인터뷰 확인도 없이 런타임 모듈 배포 (추측된 모듈)
✅ /init-project check → "불일치: portable/rules/doc-organization.md != .claude/rules/doc-organization.md"
→ 실행 중 파일 먼저 수정 → /init-project promote
❌ portable/*를 직접 편집한 후 새 프로젝트 초기화 (번들이 실행 중 파일과 조용히 분기됨)
참조 파일
- 번들:
./portable/**
- 템플릿:
./templates/**
- 버전:
./VERSION