build-project-docs

Build project documentation system (build-project-docs)

Create complete layered LLM-friendly documentation for the project. Supports two modes: documenting an existing project, and PRD-driven development for a new project.

Core Concept

LLM context windows are limited, so documentation must be layered:

.claude/CLAUDE.md = main index (project map, always loaded into context)
.claude/docs/{module}/README.md = module-level documentation (loaded on demand)
.claude/docs/{module}/*.md = in-depth reference documentation (API details, data models, pitfalls)
.claude/docs/{module}/CHANGELOG.md = module change history (debugging and rollback reference)

Mode Detection

Determine the current mode before starting:

Documentation Mode (existing project, has source code)

The project already has code and needs documentation to be organized and generated.

Brand new(no .claude/docs/) → execute all 8 stages of documentation mode in order.

Incremental（.claude/docs/ already exists) →

First check .claude/docs/_progress.md—if it exists, it means the previous session was interrupted; read it to determine:
- Stage status: which stages are complete, which stage is in progress, which are pending
- Module progress: in stages 4/5/7, which modules are complete and which are pending
- Jump directly to the first incomplete stage to continue, without repeating completed stages
If _progress.md does not exist, read the existing .claude/CLAUDE.md and all .claude/docs/ files
Run stage 1 to get the current state
Compare: new module → add, file count changes → update, missing → create, outdated → update
Skip stages that are complete and accurate
Special handling for stage 7 and stage 8: even if _progress.md is marked as complete, if the source code is newer than the documentation (find -newer detection), it still needs to be rerun

New Project Mode (PRD-driven)

The user mentions PRD, requirements document, new project planning, or development standards, and the project is empty or newly created → execute the 5 stages of new project mode.

The user mentions PRD + the project already has code → first use documentation mode to organize the existing code, then use stages 1-3 of new project mode for requirements breakdown of incremental features.

Documentation Mode (8 stages)

Organize code and generate layered documentation for an existing project.

Stage	Content	Detailed Process
1	Project exploration	→ phase-1-explore.md
2	Architecture classification	→ phase-2-classify.md
3	Write .claude/CLAUDE.md	→ phase-3-index.md
4	Base module documentation	→ phase-4-foundation.md
5	Business module documentation	→ phase-5-business.md
6	Configuration layer documentation	→ phase-6-config.md
7	Changelog	→ phase-7-changelog.md
8	Cross-validation	→ phase-8-verify.md

You must read the reference file for the corresponding phase before execution.

New Project Mode (5 phases)

Starting from the PRD, generate the architecture design, requirement breakdown, development standards, and module documentation.

Phase	Content	Detailed Process
1	PRD Parsing	→ phase-1-prd.md
2	Architecture Design	→ phase-2-scaffold.md
3	Requirement Breakdown	→ phase-3-breakdown.md
4	Generate CLAUDE.md Development Guide	→ phase-4-guide.md
5	Module Development Documentation	→ phase-5-devdocs.md

Development Standards Reference:

You must read the reference file for the corresponding phase before execution.

Key Rules

Context Management (Most Important!)

When handling multiple modules,processing all modules at once is prohibited. You must:

Process modules serially one by one (from smallest to largest)
After completing each module → update _progress.md → no longer reference that module's source code
After handling 3+ large modules → proactively prompt the user to start a new session to continue

Progress Tracking (`_progress.md`）

_progress.md is theglobal progress file, common to both modes:

After completing each phase or each module → immediately update _progress.md
After reading it in a new session, you can jump directly to the breakpoint and continue
Delete after everything is complete

Documentation Completeness

❌ Writing only the README without the api sub-files counts as "complete"
✅ As long as a module exposes an API externally (Controller / @Tool / gRPC / Handler, etc.), it must be split by business domain into api-{域}.md
✅ Each business module must have data-model.md + pitfalls.md(documentation mode) or data-model.md + dev-checklist.md(new project mode)
✅ The README is the index, api-*.md is the detail, and the README must link to all sub-files

File Size

.claude/CLAUDE.md：Within 150 lines
Module README.md:Within 200 lines
Anything over 250 lines must be split into sub-files

Core Principles

See principles.md

Start Execution

Based on the mode detection result, enter the corresponding phase process. For each phase, first show the result to the user for confirmation, then continue to the next phase.