haizei-project-wiki-generator

Project Wiki Generator

Deeply analyze project code, generate systematic technical Wiki and business Wiki, delivered as a VitePress documentation site.

Skill Positioning

This is acode-analysis-drivenwiki generation skill, whose core value is:

Deeply read project source code, trace call chains, identify module boundaries, extract business rules
Produce structured technical analysis documents (01-07 series) and business domain documents
Each document is generated by an independent subagent, ensuring analysis depth and quality
Use a VitePress documentation site as the delivery format, supporting local preview and team sharing

Working Principles

Analysis as the main thread: First deeply understand the code, then produce documents. It is not about building a site first and then filling in content.
Facts as the basis: Strictly write only content that can be confirmed from code/configuration/existing documents. Mark inferred items as "to be confirmed".
Traceable sources: Each key conclusion is bound to at least one code source (class, method, configuration, table).
User confirmation gate: Catalog planning must be confirmed by the user before starting to generate the main text.
Subagents ensure quality: Each document is generated by an independent subagent, avoiding quality degradation caused by context dilution.
Incremental priority: For existing documents, prioritize partial supplementation, and do not rewrite the whole document by default.

Reference File Routing Table

File	Purpose	When to use
`references/tech-prompts.md`	Writing rules and required sections for each of Technical Wiki 01-07	When generating technical documents in Phase 4mustrefer to
`references/biz-prompts.md`	Writing rules for Business Wiki domain documents	When generating business documents in Phase 4mustrefer to
`references/agent-prompts.md`	Subagent prompt template (including common prefix)	When constructing subagent instructions in Phase 4mustrefer to
`references/vitepress-template.md`	VitePress homepage and config.mts templates	During Phase 1 initializationmustrefer to
`references/output-structure.md`	Output directory structure specification	When planning the directory in Phase 3mustrefer to
`references/edit-checklist.md`	Incremental revision checklist	When modifying existing documentsmustrefer to
`references/known-gotchas.md`	Known pitfalls and avoidance (❌/✅ comparison)	In Phase 4 subagent promptmustinclude

Phase 1: Scope Determination and Environment Initialization

1.1 Identify User Intent

mustfirst determine which type of need the user has:

First-time generation：The project has no wiki and requires the complete process (analysis → planning → confirmation → generation)
Continue generation：There is already a partial wiki, and the user says "continue generating wiki / tech wiki / biz wiki"
Incremental refresh：Existing documentation needs additional sections, corrections, and navigation refresh
Quality check：The user requests a check of the current wiki quality

1.2 Determine analysis target

By default, analyze the current working directory
If the user specifies a path (e.g., "analyze D:/projects/my-app"), use the specified path
Output is always in the current working directory's docs/

1.3 Smart initialization of VitePress

Check whether docs/ exists:

Does not exist → Run node scripts/init-vitepress.mjs <project-root> to initialize
Exists but has no .vitepress/config.mts → Add VitePress configuration
Exists and has configuration → Check whether it is managed by this skill (contains the // project-wiki-generator managed config comment), and prepare for incremental updates

Output prompt：[Phase 1 完成] 模式：<首次生成|继续生成|增量刷新>，分析目标：<路径>

Phase 2: Deep project analysis

This is the core of the skill — Claude itself performs deep code analysis.

2.1 Analysis action checklist

Perform the analysis in the following order (using tools such as Glob, Grep, and Read):

Tech stack identification：Build tools, frameworks, languages, dependency management
Entry point identification：Startup classes, Controllers, Jobs, message entry points, external callbacks
Module division：Directory structure, package responsibilities, module boundaries
Core classes and inheritance relationships：Key implementations of abstract classes/interfaces (expand at least 1-3)
Call chain tracing：Trace main-chain methods to a depth of 3 levels, annotating key branches and state changes
Data model：Entity classes, database tables, field meanings, object relationships
External dependencies：Third-party services, middleware, message queues, caches
Business rule extraction：if/switch conditional branches, state machines, configuration switches
Business domain identification：Identify business domain boundaries from module responsibilities and business processes

2.2 Analysis scope control

Prioritize analyzing modules/processes explicitly specified by the user
Prioritize covering main-chain methods, state updates, conditional branches, and external calls
If the project is too large, first produce an analysis of the core modules, and mark the scope still to be completed
For conclusions that do not appear directly in the code and can only be inferred from naming, mark them as "to be confirmed"

2.3 Output analysis results

Write the analysis results to docs/wiki/.wiki-state/analysis.json：

{
  "projectName": "string",
  "projectRoot": "string",
  "analyzedAt": "ISO timestamp",
  "techStack": ["java", "spring-boot", "mybatis"],
  "entryPoints": [{"type": "controller", "path": "src/...", "description": "..."}],
  "modules": [{"name": "...", "path": "...", "responsibility": "...", "fileCount": 0}],
  "domains": [{"name": "...", "relatedModules": [...], "description": "..."}],
  "stats": {"codeFileCount": 0, "moduleCount": 0, "domainCount": 0}
}

Output prompt：[Phase 2 完成] 已识别 N 个模块、M 个业务域，分析结果已写入 analysis.json

Phase 3: Wiki directory planning and user confirmation

This is a gated step — the generation phase can only be entered after user confirmation.

3.1 Generate directory plan

Based on the analysis results, plan the complete wiki directory:

Newcomer guide (5 categories, 12 articles in total)：

Fundamentals (base/):

01_Quick Start — Build a first impression of the project in 30 minutes
02_Reading Guide and Onboarding Roadmap — Reading paths by role/goal
03_Key Entry Point Checklist for Taking Over Maintenance — Locate Entry Points by Problem Type

Environment section (setup/):

01_Local Environment Setup — Get the Project Running from Scratch
02_Integration and Test Environment — Environment Checklist, Mocks, Test Commands

Code section (codebase/):

01_Code Navigation Map — Locate Code by Feature/Page/Data Flow
02_Core Flow Quick Reference — User Action → Complete Call Path
03_Debugging and Troubleshooting Tips — Logs, Breakpoints, SQL Troubleshooting

Practice section (practice/):

01_How to Make Your First Change — Complete Steps from Taking a Requirement to Submitting
02_Common Modification Scenario Guide — Scenarios Such as Adding APIs/Fields/Rules
03_Notes on Testing Submission and Release — Checklist and Rollback Plan

FAQ（faq/）：

index — Common Questions Aggregated from Other Documents

Technical Wiki (fixed 01-07 series)：

Each document notes which modules it will cover and what content it will analyze
Provide a 2-3 sentence content summary

Business Wiki (organized by domain)：

List the identified business domains
Plan the 01-05 series of documents under each domain
Note the modules associated with each domain

3.2 Present the Plan to the User

MustPresent it to the user in a clear format:

## Wiki 目录规划

### 新人指南（12 篇）

#### 入门概览（base/）
1. 01_快速上手 — 项目做什么、技术栈、主业务主线、第一小时阅读顺序
2. 02_阅读指南与接手路线图 — 按角色/目标推荐不同阅读路径
3. 03_接手维护关键入口清单 — 按问题类型定位代码入口

#### 环境搭建（setup/）
4. 01_本地环境搭建 — 前置依赖、启动命令、配置说明、常见报错
5. 02_联调与测试环境 — 环境清单、Mock 方式、测试命令

#### 代码导航（codebase/）
6. 01_代码导航地图 — 按功能/页面/数据流找代码
7. 02_核心链路速查 — 用户操作 → 完整调用路径（卡片式）
8. 03_调试排查技巧 — 日志、断点、SQL 排查路径

#### 实战上手（practice/）
9. 01_第一个改动怎么做 — 典型改动示例、修改 checklist、自测方法
10. 02_常见修改场景指南 — 新增接口/字段/规则/定时任务等场景
11. 03_提测与上线注意事项 — 提测 checklist、SQL 规范、回滚方案

#### 常见问题（faq/）
12. FAQ — 从其他文档聚合的非显而易见知识点

### 技术知识（7 篇）
1. 01_系统架构分析 — 覆盖模块 A、B、C，分析系统分层与调用链
2. 02_专业术语词汇表 — 提取项目中的领域术语与代码命名规范
...

### 业务知识
#### 用户管理域（5 篇）
- 关联模块：user-service, auth-module
- 01_业务目标与范围 — 用户注册、认证、权限的业务边界
...

#### 订单域（5 篇）
...

### 本轮生成范围
建议按阶段分批生成：
- 第一批：base/ 全部 + tech-01 + tech-06（新人第一天需要的基本认知）
- 第二批：setup/ 全部 + codebase/01（有了环境才能看代码）
- 第三批：codebase/02-03 + practice/01（能调试后开始实战）
- 第四批：practice/02-03 + faq/（前面文档都有了才能写好场景指南）

请确认：
1. 域划分是否合理？
2. 命名是否需要调整？
3. 本轮先生成哪些？

3.3 Wait for User Confirmation

After the user confirms, write the final plan to docs/wiki/.wiki-state/plan.json
If the user requests adjustments, revise the plan and present it again
ProhibitedSkip confirmation and generate directly

Output prompt：[Phase 3 完成] 目录规划已确认，准备生成 N 篇文档

Phase 4: Sub-agents Generate Documents in Batches

4.1 Sub-agent Scheduling Strategy

For each confirmed document in the plan, start an independent sub-agent (Agent tool):

Rules for constructing the sub-agent prompt:

Read references/agent-prompts.md the full text of the "common prefix" in
Replace the {通用前缀} placeholderFully expandinto the actual content of the common prefix (not a reference, but inline expansion)
Replace all variables:{projectName}、{projectRoot}、{targetPath}、{relatedModules}、{scope}、{audience}、{date}
Concatenate the template for the corresponding document type (tech-01 to tech-07, guide-base-01 to guide-base-03, guide-setup/codebase/practice/faq templates, or biz domain templates)
Append at the end of the prompt the full content of references/known-gotchas.md (list of known pitfalls)
The prompt ultimately sent to the sub-agent must be a complete, self-contained instruction containing no unexpanded placeholders

ProhibitedPass only the {通用前缀} text to the sub-agent — the sub-agent cannot see the references files, so the complete constraints must be inlined into the prompt.

4.2 Parallelization Strategy

Documents with no dependencies can be generated in parallel (send multiple Agent calls in the same message)
It is recommended to run 2-3 sub-agents in parallel per batch
For tech-wiki, 01 (architecture) is recommended to be generated first, because subsequent documents may reference it

4.3 Sub-agent Quality Requirements

Do not impose a uniform fixed chapter skeleton on sub-agents; the document structure should be determined by the corresponding document type, the density of code materials, and the reader's goals.

4.4 Document Opening Format

At the beginning of each documentMustdeclare:

> **分析范围**：<所属域/文档类型> | **适用对象**：<目标读者> | **生成日期**：<YYYY-MM-DD>

4.5 Information Status Labels

Technical Wiki MustDistinguish:

代码事实 — Directly verifiable from code/configuration
文档口径 — Descriptions in existing documentation (may be inconsistent with the code)
待确认 — Content that cannot be confirmed
风险提示 — Known risks or potential issues

Business Wiki MustDistinguish:

业务目标 — Business purpose of the system or feature
主流程 — Core business flows
参与角色 — User/system roles involved
规则 — Business rules or decision conditions
异常 — Failure paths, compensation logic, edge cases
待确认 — Content that cannot be confirmed

Output Prompt：[Phase 4 进行中] 正在生成第 N 批文档（共 M 篇）...

Phase 5: Assembly and Quality Check

5.1 Update VitePress Configuration

Run:

node scripts/build-vitepress-config.mjs <docs-root>

Automatically scan docs/wiki/ all md files under it, and generate the sidebar and navigation configuration.

5.2 Update the Homepage

Based on the actually generated documentation, update the features section of docs/index.md to ensure the links point to pages that actually exist.

5.3 Quality Check and Self-Correction

Run:

node scripts/check-wiki-quality.mjs <docs-root>

Check each document for: line count, section count, chart count, source index, and cross-links.

Self-Correction Logic：

For documents rated "weak", identify the specific missing items (missing source index? missing charts? insufficient line count? missing analysis scope statement?)
Launch a repair sub-agent to fill in only the missing sections (do not rewrite the entire text), and clearly state in the prompt what is missing
Recheck after repair, with at most 1 retry
Documents that are still "weak" are marked as "needs manual review" and the user is informed in the report

5.4 Update Progress

Run:

node scripts/progress-manager.mjs complete <docs-root> <doc-id>

5.5 Report to the User

MustReport using a structured format:

## 本批完成

| 文档 | 质量 | 行数 | 图表 | 来源索引 |
|------|------|------|------|----------|
| 01_系统架构分析 | ✅ strong | 156 | 3 | 8 条 |
| 06_模块结构分析 | ⚠️ acceptable | 67 | 1 | 3 条 |

## 剩余待生成

- tech: 02-05, 07
- biz: 域"订单管理"全部
- guide: 02, 03（依赖前面文档完成后再生成）

## 下一步

说"继续生成 wiki"生成下一批，或指定"生成 tech 02"单独生成某篇。

Output Prompt：[Phase 5 完成] 本批 N 篇文档已生成，质量评级：X strong / Y acceptable / Z weak

Incremental Maintenance Rules

If the target file already exists,Mustprioritize incremental revision, and do not rewrite unrelated sections
Before modificationMustrefer to references/edit-checklist.md
Preserve the existing numbering system and heading style
Do not rearrange the structure of other modules just because documentation for a certain module is being supplemented
Newly added sections must be compatible with the existing directory hierarchy
If the main structure of the existing page is reasonable, only fill in the missing sections

Common User Expressions and Response Methods

"Generate project wiki" / "Analyze this project and generate documentation"

Execute the complete process: Phase 1 → 2 → 3 (wait for confirmation) → 4 → 5

"Continue generating wiki" / "Continue generating tech wiki" / "Continue generating biz wiki"

Read progress.json, find the next batch of documents to be generated
Execute Phase 4 → 5
ProhibitedRegenerate documents that have already been completed

"Analyze <path> and generate wiki"

Use <路径> as the analysis target, and still output in the current directory docs/

"Check wiki quality"

Directly run the quality check script and report the results

"Refresh VitePress configuration" / "Update sidebar"

Directly run build-vitepress-config.mjs

"Supplement the <section> of <document name>"

Enter incremental revision mode, refer to edit-checklist.md

Prohibited actions

❌ Skip Phase 3 user confirmation and generate the document directly
❌ Fabricate system behavior or business rules without reading the code
❌ Treat inferences as confirmed facts; unverified items must be marked as "to be confirmed"
❌ Generate empty skeleton pages or documents with only headings and no body text
❌ Tamper with fixed identifiers such as class names, method names, and field names
❌ Rewrite unrelated sections during incremental revision
❌ Generated documents lack a source index block

About this skill

Skill Positioning

Working Principles

Reference File Routing Table

Phase 1: Scope Determination and Environment Initialization

1.1 Identify User Intent

1.2 Determine analysis target

1.3 Smart initialization of VitePress

Phase 2: Deep project analysis

2.1 Analysis action checklist

2.2 Analysis scope control

2.3 Output analysis results

Phase 3: Wiki directory planning and user confirmation

3.1 Generate directory plan

3.2 Present the Plan to the User

3.3 Wait for User Confirmation

Phase 4: Sub-agents Generate Documents in Batches

4.1 Sub-agent Scheduling Strategy

4.2 Parallelization Strategy

4.3 Sub-agent Quality Requirements

4.4 Document Opening Format

4.5 Information Status Labels

Phase 5: Assembly and Quality Check

5.1 Update VitePress Configuration

5.2 Update the Homepage

5.3 Quality Check and Self-Correction

5.4 Update Progress

5.5 Report to the User

Incremental Maintenance Rules

Common User Expressions and Response Methods

"Generate project wiki" / "Analyze this project and generate documentation"

"Continue generating wiki" / "Continue generating tech wiki" / "Continue generating biz wiki"

"Analyze <path> and generate wiki"

"Check wiki quality"

"Refresh VitePress configuration" / "Update sidebar"

"Supplement the <section> of <document name>"

Prohibited actions