Generate and maintain a structured wiki for Vibe Coding projects (humans describe intent, Agents write code). The wiki is the Agent's input material and directly determines output quality.
Execution Flow
Initialization (wiki/ does not exist or is empty)
- Scan
wiki/directory, list existing files - Compare against the required file checklist(see "File System" below), identify missing items
- Confirm with the userthe list of files to be created
- Generate skeletons: read the corresponding templates from this Skill's
assets/directory, fill in user context (leave uncertain parts as<!-- TODO: ... -->placeholders) - Update navigation: if
01-project-roadmap.mdalready exists, append an index row for the new stage - Mark freshness: add at the top of each generated file
<!-- Last verified: YYYY-MM-DD | Current stage: X --> - Inject maintenance rules: append the contents of the "Daily Maintenance Rules" section below to the project's
CLAUDE.md(if it already exists, merge the differences; do not replace the entire file). This step cannot be skipped—the wiki's daily synchronization depends on these rules being written into CLAUDE.md
Restructuring / Updating (wiki/ already has files)
- Scan
wiki/all files and subdirectories under it, check the numbering scheme (compact or expanded) and freshness markers - Diagnose：
- Missing numbering prefix? Overlapping information? Completed stages not archived? Content inconsistent with code?
- Bloat detection: stage files over 300 lines, other files over 500 lines → recommend splitting
- Stray files: files in the wiki root directory that do not belong to any numbered section (e.g.
ui-audit-*.md) → recommend moving them into an appropriate subdirectory (reviews/) or an operations section (8x） - Naming consistency：
specs/contains a mix oftask-spec-*andspec-*→ migration is not mandatory, but all new ones should usespec-*; specs scattered in the wiki root directory → recommend moving them intospecs/ - Custom subdirectories: identify
plugins/、images/and other project-specific directories, mark them as known custom directories, and do not report them as anomalies
- Generate a change list(rename / merge / split / archive / migrate / update content), confirm with the user
- Execute the changes
- Verify consistency: inter-file reference links are valid, roadmap index corresponds to actual files
- Check maintenance rules: confirm that the project's
CLAUDE.mdalready has wiki maintenance rules; if missing, append them (do not replace the entire file)
File System
Numbering System
Numbering is layered by **"Strategy → Architecture → Specification → Stage → Operations → Log"**. Choose a compact or expanded scheme based on project size:
Compact scheme(≤5 stages, suitable for most projects):
wiki/
├── 00-product-proposal.md
├── 01-project-roadmap.md
├── 02-system-architecture.md # 紧凑方案用 0x 统一放战略+架构
├── 03-design-principle.md
├── 04-api-reference.md
├── 1x 阶段 Stages
│ ├── 10-stage-a.md
│ ├── 11-stage-b.md ...
├── 80-known-pitfalls.md
├── 85-backlog.md
├── 90-changelog.md
├── specs/ · refs/ · reviews/ · archive/
Expanded scheme(>5 stages or when more layering space is needed):
wiki/
├── 0x 战略 Strategy — 全局视角
│ ├── 00-product-proposal.md
│ ├── 01-project-roadmap.md
│ ├── 02-business-model.md
│ └── 03-technical-pillars.md
├── 2x 架构 Architecture — 系统是怎么建的
│ ├── 20-system-architecture.md
│ └── 21-design-principle.md
├── 3x 接口 API
│ └── 30-api-reference.md
├── 4x 规范 Conventions
│ ├── 40-conventions.md
│ └── 41-dev-pitfall-patterns.md
├── 6x 阶段 Stages — 各阶段详细 spec
│ ├── 60-stage-a.md ...
├── 8x 运维 Operations
│ ├── 80-known-pitfalls.md
│ ├── 81-postmortem-*.md
│ ├── 84-design-exploration.md
│ └── 85-backlog.md
├── 9x 日志 Log
│ └── 90-changelog.md
├── specs/ · refs/ · reviews/ · archive/
Selection rules: Ask the user during initialization, or automatically detect based on existing files. The file contents and templates for both approaches are exactly the same; only the number prefix differs. The key isbe consistent within a project, do not mix them.
Project-specific subdirectories: the wiki may contain subdirectories not predefined by the skill (e.g., plugins/、images/); this is normal project evolution. When scanning, recognize them as "custom directories", do not report them as anomalies, and do not force renaming.
Core model: Why / What / How / Look × Global / Stage
| Global (stable, changes only with a new stage) | Stage (incremental updates) | |
|---|---|---|
| Why | product-proposal |
— |
| What | project-roadmap — feature index |
stage-X — design decisions |
| How | system-architecture — architecture + types |
stage-X — API, data models, affected files |
| Look | design-principle — visual language |
— |
Key rules: stage files contain both What and How. A feature's design decisions, API contracts, and data models go in one file. Global files only serve as indexes and navigation, and do not repeat stage details.
Planning levels
Roadmap (01) |
Backlog (85) |
|
|---|---|---|
| Time span | Month / quarter level | Week / iteration level |
| Granularity | Direction, milestones, major features | Specific tasks, bugs, small requirements |
| Answers | Where are we going? | What to do next? |
When to use: Before starting a task, first check the roadmap to confirm stage alignment, then take specific tasks from the backlog to execute. After a task is completed, check it off in the backlog; at release time, organize completed entries and write them into the changelog.
Essential files (first tier)
| Number | File | Written for | Core content |
|---|---|---|---|
| 00 | product-proposal.md |
Agent + you | Product vision, product positioning,what not to do, target users, feature matrix, roadmap narrative |
| 01 | project-roadmap.md |
Agent + you | Stage overview table, full feature index (feature × status × stage link), milestones |
| 20 | system-architecture.md |
Agent | Tech stack, directory structure, data flow, core types, environment variables (300-500 lines) |
On-demand files (second tier)
| Number | File | When needed |
|---|---|---|
| 02 | business-model.md |
When there are commercialization/monetization needs |
| 03 | technical-pillars.md |
When there is a clear technical barrier or research direction |
| 21 | design-principle.md |
When there is a custom visual language (not default UI library styles) |
| 30 | api-reference.md |
When the API exceeds 5 routes, or API details still need to be looked up after stage archiving |
| 40 | conventions.md |
When there are clear coding preferences/constraints (library choices, naming, error handling patterns, etc.) |
| 41 | dev-pitfall-patterns.md |
When accumulated pitfalls need systematic recording |
| 6X | stage-X.md |
When feature complexity exceeds what can be said in one sentence (150-300 lines) |
| — | specs/spec-{name}.md |
Specs for small features / improvements; move to archive/specs/ |
| — | refs/ref-{topic}.md |
External mechanism research, technology selection comparisons, third-party API documentation summaries |
| — | reviews/review-{date}-{subject}.md |
Conclusions and action items from code reviews, spec reviews, design reviews |
| 80 | known-pitfalls.md |
Record pitfalls as they happen, do not wait until the end of the stage |
| 81 | postmortem-*.md |
When multiple bugs are interrelated and expose systemic problems (use pitfalls for single-point issues, postmortem for systemic issues) |
| 84 | design-exploration.md |
When there are creative process artifacts such as UI design explorations, prototype records, etc. |
| 85 | backlog.md |
When there are temporary bugs, technical debt, or improvement ideas that need to be tracked |
| 90 | changelog.md |
At release time, from 85-backlog.md organize completed items and write them in, describing changes for users, without recording internal implementation details |
For detailed descriptions of each file and the rationale for "why it is needed," see
references/file-reference.md。
Stage File Lifecycle
When a stage is fully delivered and subsequent stages no longer reference its API/data model → move it into wiki/archive/，01-project-roadmap.md , keep an index line and annotate [archived]。
Archival criteria: Archive only when both of the following are satisfied: ① the stage has been completed for more than one stage; ② there are no cross-references to it in current and future stage files. When uncertain, keep it; prefer redundancy over broken links.
Subdirectory Management
The four subdirectories each have independent naming conventions, lifecycles, and archival rules.
specs/ — Task Specifications
Active feature specs, which are finer-grained task descriptions than stage files.
| Project | Rules |
|---|---|
| Naming | spec-{feature-name}.md(recommended). Legacy task-spec-*.md is also acceptable; migration is not mandatory |
| Location | Place under wiki/specs/ . If a spec is found scattered in the wiki root directory → prompt to migrate it into specs/ |
| When to Create | Feature complexity falls between "a single backlog line" and "a full chapter of a stage file" |
| Content | Background, goals, boundaries, acceptance criteria, list of affected files |
| Archive | Implementation complete → move into archive/specs/, check off the corresponding backlog item |
| Status Tracking | Location is status: in specs/ = active, in archive/specs/ = complete. No need to maintain a Status header marker |
refs/ — Reference Materials
Internal mirrors of external knowledge—third-party API behavior, protocol formats, technology selection research, etc.
| Project | Rules |
|---|---|
| Naming | A descriptive file name is sufficient (e.g. git-sync-workflow.md、npx-skills-mechanism.md）。ref- prefix is optional |
| When to Create | External knowledge is repeatedly consulted in 2+ files/conversations |
| Content | Mechanism explanation, key API summary, integration points with this project, notes on pitfalls |
| Archive | Do not proactively archive; when the integration solution is abandoned, mark `<!-- Deprecated: YYYY-MM-DD |
| References | In stage/spec, link via → 详见 [refs/xxx.md](./refs/xxx.md) ; do not copy content |
reviews/ — Review Records
Archives of conclusions from code reviews, spec reviews, and design reviews.
| Project | Rules |
|---|---|
| Naming | review-{YYYY-MM-DD}-{subject}.md(e.g. review-2026-03-18-auth-spec.md） |
| When to Create | After spec review is completed, after review of major code changes, after design solution review |
| Content | Review target (linked to spec/PR), conclusion (pass/modify/reject), action items, remaining discussion points |
| Archive | All action items completed → move into archive/reviews/ |
| Linkage | After creating a review, append to the header of the corresponding spec <!-- Reviewed: YYYY-MM-DD → reviews/review-xxx.md --> |
archive/ — Archive directory
Long-term storage for completed documents. Retains the full history for traceability without polluting the active directory.
archive/
├── specs/ — 已完成的 spec（保留原文件名）
├── reviews/ — 历史评审
└── stages/ — 已归档的 stage 文件
| Rules | Description |
|---|---|
| Archive operations | git mv wiki/specs/spec-xxx.md wiki/archive/specs/ |
| Leave a trace in place | In 01-project-roadmap.md or 85-backlog.md annotate [archived → archive/specs/spec-xxx.md] |
| References stay unbroken | After archiving, full-text search for the old path (grep -r "specs/spec-xxx" wiki/), update all references to point to the new path under archive/ New path under |
| Do not delete | Files under the archive directory are only appended to and consulted, not deleted |
Progressive disclosure
Wiki files are loaded in three layers to avoid the Agent reading all content at once and wasting context.
Layer 1: Index (always available)
When the Agent enters the project, it reads only two files to build a global mental model:
00-product-proposal.md → 知道"做什么、不做什么"
01-project-roadmap.md → 知道"当前在哪个阶段、有哪些功能"
Each feature line in the roadmap carries a link, and the Agent decides whether to go deeper based on the current task.
Layer 2: Structure (loaded by scenario)
Depending on the task type, the Agent loads the corresponding structure files on demand:
| Task type | Files to load | Do not load |
|---|---|---|
| New feature development | system-architecture → current stage → related specs/ |
Other stages, refs, reviews |
| Bug fix | system-architecture → known-pitfalls → related stage |
Strategy files, unrelated stages |
| UI adjustment | design-principle → system-architecture(directory section) |
stage files (unless feature logic is involved) |
| Technical research | refs/{topic} → system-architecture(integration points) |
spec、review |
| Review | Corresponding specs/ → related refs/ → conventions |
Unrelated stages |
Layer 3: Details (drilled down on demand)
The Agent reads deeper files only when the following signals appear:
- The stage file says
→ 详见 refs/ref-xxx.md→ load that ref - The spec header has
<!-- Reviewed: ... -->→ load that review to see historical decisions - pitfalls mentions
→ 复盘见 81-postmortem-xxx.md→ load that postmortem - backlog has
[archived → archive/specs/spec-xxx.md]→ load when traceability is needed
Key principles: Does not actively scan subdirectories. The links in the index files (roadmap, backlog) are the only "entry navigation".
Relationship management
Wiki files have reference dependencies among them. After one file changes, files that reference it may need to be updated in sync. These rules help the Agent track and maintain these relationships.
Reference syntax
References between files uniformly use relative paths + anchors:
→ 详见 [20-system-architecture.md](./20-system-architecture.md#数据流)
→ 详见 [refs/ref-stripe-webhook.md](./refs/ref-stripe-webhook.md)
→ 归档于 [archive/specs/spec-auth.md](./archive/specs/spec-auth.md)
Dependency graph (which files reference whom)
| Referenced file | Typical referrers | Check on change |
|---|---|---|
00-product-proposal |
roadmap, stage files | Product direction change → check the "Background" section of all stages |
20-system-architecture |
All stages, all specs | Architecture change → grep -r "system-architecture" wiki/ check references |
21-design-principle |
Frontend-related stages, specs | New token → check whether existing components need adaptation |
refs/ref-* |
Reference the stage/spec of that external system | External API update → update all consumers along the reference chain |
specs/spec-* |
backlog (index), reviews (review) | spec completed → update backlog status, archive spec |
Change linkage Checklist
When the Agent modifies wiki files, perform the following checks:
修改文件 X
→ grep -r "X" wiki/ # 找到所有引用 X 的文件
→ 逐一检查：引用的信息是否仍然准确
→ 不准确 → 更新引用方（或在引用旁加 <!-- May be outdated -->）
High-frequency linkages requiring special attention:
- Rename/move file → full-text search for old path, update all references
- stage archived → update roadmap index row, update the corresponding backlog entry
- spec completed → check off backlog, move into archive, check action items in review
Corruption detection
At the start of each stage (or when triggering the refactoring process), the Agent performs an integrity scan:
- Broken link detection：
grep -rn '\./[a-z].*\.md' wiki/Check whether all relative path reference targets exist - Freshness check: scan all
<!-- Last verified: YYYY-MM-DD -->markers; markers not verified for over 30 days are marked as<!-- May be outdated --> - Orphan file detection：
refs/andspecs/files under it, if not referenced by any other wiki file → prompt the user: should they be archived or deleted? - Duplicate information detection: the same concept has paragraph-level elaboration in two files → suggest merging, keep one authoritative source, and change the other to a reference link
- Bloat detection：
wc -l wiki/*.md wiki/**/*.md→ list files with stage >300 lines and others >500 lines, suggest splitting - Scattered files: in the wiki root directory, those that do not match the numbering system
.mdfiles (such as audit reports, temporary notes) → suggest moving them into an appropriate subdirectory - Naming migration：
specs/intask-spec-*andspec-*mixed use → prompt but do not enforce (new ones always usespec-*）
After detection is complete, output thesummary table(check item × severity × number of findings) andpriority recommendations(sorted by severity, each with specific operation steps). After reading the report, the user should clearly know "which to do first and how to do it".
Agent reading order (progressive)
First layer (required reading):00-product-proposal → 01-project-roadmap(locate the current stage)
Second layer (loaded by task):
| Scenario | Path |
|---|---|
| New conversation / new feature | system-architecture → current stage → related specs/ |
| Fix Bug | system-architecture → known-pitfalls → related stage |
| Fix Bug (recurring) | postmortem-* → system-architecture → known-pitfalls → related stage |
| UI adjustment | design-principle → system-architecture(directory structure) → related components |
| Understand the full picture | product-proposal → project-roadmap → system-architecture |
| Technical research | Related refs/* → system-architecture(integration points section) |
| Review task | Corresponding specs/* → conventions → related refs/ |
Third layer (drill down by reference): only when → 详见 xxx links appear in a file are the target files loaded. Do not proactively scan subdirectories.
Documentation writing standards
- Documentation for Agents should use structured formats. Tables > paragraphs, code blocks > prose descriptions, type definitions > natural language.
- Documentation for yourself should record decisions, not details. "Why choose X over Y" > "X's installation command".
- Maintain one piece of information in only one place. Recording the same information in two places will inevitably be inconsistent.
- The Stage file is the sole authoritative source for a feature. Global files only serve as indexes.
- Mark freshness:
<!-- Last verified: YYYY-MM-DD | Current stage: X | May be outdated after Stage Y --> - Better not to write than to write without maintaining. Outdated documentation is more dangerous than no documentation.
- Use relative paths for references between files. wiki files reference each other using the
./XX-filename.md#锚点format, and references to source code use the../server/src/xxx.tsformat. - Pursue information density, not length. Specific standards:
Content selection—what to write and what not to write:
- Write decisions and constraints ("use dayjs, because moment is deprecated"), not facts the Agent can read from the source code ("LoginForm accepts an onSubmit prop")
- Write cross-module relationships ("A pushes to B via WebSocket"), not obvious logic internal to a module
- Write "why not" ("do not use SSR, because it is a pure intranet tool"); when "why yes" is obvious, do not write it
Expression density—convey the same information with the fewest words:
- If one row of a table can explain it clearly, do not expand it into a paragraph
- Do not write lead-in sentences ("In this section we will discuss..."), do not write summary sentences ("In summary..."), and do not restate context
- Delete every sentence until deleting more would lose information
Bloat signals—the following situations indicate you have written too much:
- A Stage file exceeds 300 lines (e.g.,
65-stage-knowledge-api696 lines → an independent API spec or ref should be split out) - A non-stage file exceeds 500 lines (e.g.,
82-external-*1057 lines → it should be split intorefs/） - A section exceeds 20 lines without a code block or table
- The same concept is expanded at the paragraph level in two files
- After reading a paragraph, it can be summarized as one row of a table without losing key information
Splitting strategy: Identify independent topic blocks in a bloated file → extract them as refs/ or a new stage → replace them in place with a one-line reference link. After splitting, the original file should shrink to within the recommended line count.
For investment signals and timing guidance for documentation maintenance, see
references/writing-guide.md。
Daily maintenance rules
The wiki structure is generated when the Skill is triggered, but the daily synchronization of the wiki happens in every development conversation. The following rules should be written into the project after initialization is complete CLAUDE.md, so that the Agent automatically maintains the wiki during the normal development process without repeatedly triggering this skill.
Content to write into CLAUDE.md (trim according to the wiki files that actually exist in the project, keeping only the lines corresponding to files that have been created):
## Wiki 维护
开发过程中，以下操作需要同步更新对应 wiki 文件：
| 当你做了这件事 | 更新哪个文件 |
|--------------|------------|
| 新增/修改 API 路由 | `wiki/30-api-reference.md` 追加或修改对应条目 |
| 完成一个 stage 的功能 | `wiki/01-project-roadmap.md` 对应行状态改为 ✅ |
| 遇到非显而易见的坑 | `wiki/80-known-pitfalls.md` 追加一条（现象、原因、解法） |
| 多个 bug 互相关联、暴露系统性问题 | 新建 `wiki/81-postmortem-*.md`（单点问题用 pitfalls，系统性问题用 postmortem） |
| 架构变更（新模块、新数据流） | `wiki/20-system-architecture.md` 更新对应章节 |
| 阶段全部交付 | `wiki/90-changelog.md` 补一笔（从 backlog 已完成条目整理） |
| 发现 bug / 技术债 / 改进想法 | `wiki/85-backlog.md` 追加一条 |
| 新增设计 token / 动效 | `wiki/21-design-principle.md` 追加对应条目 |
| 出现新领域术语 | `wiki/05-glossary.md` 追加定义，防止 Agent 后续用词混乱 |
| 重命名 / 移动 wiki 文件 | 同步更新所有引用该文件的链接 |
**新建文件时机：**
- 新功能复杂度超过一句话说清 → 新建 `wiki/6X-stage-X.md`
- 小功能 / 改进点需要 spec → 新建 `wiki/specs/spec-{name}.md`（完成后移入 `archive/specs/`）
- 外部机制调研 → 新建 `wiki/refs/ref-{topic}.md`
- Spec / 代码 / 设计评审完成 → 新建 `wiki/reviews/review-{date}-{subject}.md`
**归档时机：**
- Spec 完成且 review 通过 → `git mv wiki/specs/spec-xxx.md wiki/archive/specs/`，backlog 打勾
- Review 的 action items 全部完成 → `git mv wiki/reviews/review-xxx.md wiki/archive/reviews/`
- Stage 归档 → `git mv wiki/6X-stage-X.md wiki/archive/stages/`，roadmap 标注 `[archived]`
**关联维护（每次修改 wiki 文件时）：**
- `grep -r "{被修改文件名}" wiki/` → 检查引用方是否需要同步更新
- 重命名/移动文件 → 全文搜索旧路径，更新所有引用
**定期检查（每个阶段开始时）：**
- 扫描 wiki/ 下所有文件，更新 `Last verified` 日期
- 标出内容可能已过时的章节（加 `<!-- May be outdated -->` 注释）
不需要在每次 commit 时都更新——在功能完成、API 变更、架构调整这些"节点"时同步即可。
Template
All templates are located in this Skill's assets/ directory. When generating files, read the corresponding template and fill in the project context.
| Template file | Corresponding wiki file |
|---|---|
product-proposal.tmpl.md |
00-product-proposal.md |
project-roadmap.tmpl.md |
01-project-roadmap.md |
business-model.tmpl.md |
02-business-model.md |
technical-pillars.tmpl.md |
03-technical-pillars.md |
system-architecture.tmpl.md |
20-system-architecture.md |
design-principle.tmpl.md |
21-design-principle.md |
api-reference.tmpl.md |
30-api-reference.md |
conventions.tmpl.md |
40-conventions.md |
stage-x.tmpl.md |
6X-stage-X.md |
known-pitfalls.tmpl.md |
80-known-pitfalls.md |
postmortem.tmpl.md |
81-postmortem-*.md |
design-exploration.tmpl.md |
84-design-exploration.md |
backlog.tmpl.md |
85-backlog.md |
changelog.tmpl.md |
90-changelog.md |
spec.tmpl.md |
specs/spec-{name}.md |
ref.tmpl.md |
refs/ref-{topic}.md |
review.tmpl.md |
reviews/review-{date}-{subject}.md |