project-wiki

Project Wiki Skill

为 Vibe Coding 项目（人类描述意图，Agent 写代码）生成和维护结构化 wiki。wiki 是 Agent 的输入物料，直接决定输出质量。

---

执行流程

初始化（wiki/ 不存在或为空）

1. 扫描 wiki/ 目录，列出已有文件
2. 对照必要文件清单（见下方"文件体系"），识别缺失项
3. 与用户确认将要创建的文件列表
4. 生成骨架：从本 Skill 的 assets/ 目录读取对应模板，填入用户上下文（不确定的部分留 <!-- TODO: ... --> 占位）
5. 更新导航：如已有 01-project-roadmap.md，追加新阶段索引行
6. 标记新鲜度：每个生成的文件头部加 <!-- Last verified: YYYY-MM-DD | Current stage: X -->
7. 注入维护规则：将下方"日常维护规则"章节的内容追加到项目 CLAUDE.md（已有则合并差异，不替换整个文件）。这一步不能跳过——wiki 的日常同步依赖这些规则写入 CLAUDE.md

重构 / 更新（wiki/ 已有文件）

1. 扫描 wiki/ 下所有文件和子目录，检查编号方案（紧凑 or 展开）、新鲜度标记
2. 诊断：
   • 缺编号前缀？信息重叠？已完结 stage 未归档？内容与代码不一致？
   • 膨胀检测：stage 文件超 300 行、其他文件超 500 行 → 建议拆分
   • 散落文件：wiki 根目录中不属于任何编号区段的文件（如 ui-audit-*.md）→ 建议归入合适的子目录（reviews/）或运维区段（8x）
   • 命名一致性：specs/ 下混有 task-spec-* 和 spec-* → 不强制迁移，但新建一律用 spec-*；spec 散落在 wiki 根目录 → 建议迁入 specs/
   • 自定义子目录：识别 plugins/、images/ 等项目特有目录，标记为已知自定义目录，不报为异常
3. 生成改动清单（重命名 / 合并 / 拆分 / 归档 / 迁移 / 更新内容），与用户确认
4. 执行改动
5. 验证一致性：文件间引用链接有效、roadmap 索引与实际文件对应
6. 检查维护规则：确认项目 CLAUDE.md 中已有 wiki 维护规则，缺失则追加（不替换整个文件）

---

文件体系

编号体系

编号按**"战略 → 架构 → 规范 → 阶段 → 运维 → 日志"**分层。根据项目规模选择紧凑或展开方案：

紧凑方案（≤5 个 stage，适合多数项目）：

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/

展开方案（>5 个 stage 或需要更多分层空间）：

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/