- name
- guide-creator
- description
- 通用项目文档指南生成器：为任何项目创建和维护标准化的 guide 文档体系（start.md + guide/ 目录），覆盖设计理念、技术架构、更新日志、踩坑记录等完整生命周期。支持三种模式：(1) 初始化模式 — 一键创建标准化文档骨架；(2) 更新模式 — 追加 changelog/pitfalls/版本号同步；(3) 上下文恢复 — AI 在新对话中快速理解项目全貌。触发关键词：'初始化项目guide'、'创建项目文档'、'更新guide'、'总结经验教训'、'project guide'、'init guide'、'update guide'、'context recovery'。当用户说'帮我建一套项目文档'、'记录这次的更新和踩坑'、'新对话帮我恢复项目上下文'时触发。
Guide Creator — 通用项目文档指南生成器
为任何项目创建和维护标准化的 guide 文档体系。提炼自实际项目（福音雪镇）经过 20+ 版本迭代验证的文档最佳实践。
Quick Start
模式 1：初始化项目文档
用户说："初始化项目guide" / "创建项目文档" / "init guide"- 运行
scripts/init_guide.py --project-name "项目名" --type game|web|cli|lib|general --root /path/to/project - 自动创建
start.md+guide/目录及全部模板文件 - 按提示填充关键内容（启动命令、文件清单、架构图等）
模式 2：更新项目文档
用户说："更新guide" / "总结经验教训" / "update guide"- 运行
scripts/update_guide.py --action add-changelog|add-pitfall|bump-version|sync-files --root /path/to/project - 或直接告诉 AI 本次更新内容，由 AI 生成格式化条目并追加
模式 3：上下文恢复
AI 在新对话开始时，按推荐顺序读取文档快速理解项目。推荐阅读顺序：start.md → guide/guide.md → guide/08-changelog.md → guide/09-pitfalls.md → 按需读取 01~07
Key Rules
文件结构规范
project-root/
├── start.md # 启动说明（怎么跑 + 文件清单）
└── guide/
├── guide.md # 项目总览索引（入口文件）
├── 01-design.md # 设计理念（必须）
├── 02-{domain}.md # 按项目类型（可选）
├── 03-{domain}.md # 按项目类型（可选）
├── 04-{domain}.md # 按项目类型（可选）
├── 05-{domain}.md # 按项目类型（可选）
├── 06-tech.md # 技术架构（必须）
├── 07-plan.md # 开发计划（必须）
├── 08-changelog.md # 更新日志（必须）
└── 09-pitfalls.md # 踩坑记录（必须）必须文件（所有项目类型）：start.md、guide.md、01-design.md、06-tech.md、07-plan.md、08-changelog.md、09-pitfalls.md
可选文件（02~05，按项目类型）：
- 游戏：地图(02)、NPC/实体(03)、属性/数值(04)、AI系统(05)
- Web应用：路由(02)、组件(03)、状态管理(04)、API(05)
- CLI/库：命令(02)、核心模块(03)、数据模型(04)、算法(05)
- 通用：架构(02)、核心模块(03)、数据模型(04)、逻辑(05)
格式约束
- 版本号：
vX.Y格式（如 v2.3），记录在guide.md元信息和08-changelog.md顶部 - Changelog 条目格式：
## vX.Y — 标题摘要 (YYYY-MM-DD)+ 按子系统分组 + 🐛Bug修复 + 📝代码改动 - Pitfall 条目格式：
## 🔥 坑N：标题+ 问题现象 + 问题根因 + 解决方案 + ⚠️开发注意 + 加粗通用原则 - 文档索引表：guide.md 中维护完整的文档索引表（文档名 + 内容摘要 + 说明）
更新时机
| 事件 | 必须更新 | 可选更新 |
|---|---|---|
| 完成功能开发 | 08-changelog | guide.md版本号, start.md文件清单 |
| 修复Bug | 08-changelog | 09-pitfalls（如有经验教训） |
| 踩坑/发现问题 | 09-pitfalls | — |
| 新增文件 | start.md文件清单 | 06-tech.md文件结构 |
| 版本发布 | guide.md版本号, 08-changelog | 07-plan checklist |
| 架构变更 | 06-tech.md | guide.md架构图 |
文件保护
- 不要删除已有的 changelog/pitfalls 条目，只追加
- guide.md 的文档索引表中引用的文件必须存在且非空
- changelog >500 行时归档到
guide/archive/ - pitfalls >30 条时按类型分组（UI类/数据类/LLM类/性能类等）
详细模式指令
完整的模式执行指令请参考以下文件：
- Guide 体系规范：references/guide-spec.md — 文件结构、章节要求、版本号规范、更新触发规则、归档策略
- 文档模板：references/templates/ — 所有文档的标准模板
- start-template.md — start.md 模板 - guide-template.md — guide.md 模板 - changelog-template.md — changelog 模板 - pitfalls-template.md — pitfalls 模板 - sub-doc-templates.md — 01~07 子文档模板集
初始化模式 — 详细执行步骤
当用户触发初始化（说 当用户触发初始化（说"初始化项目guide"、"创建项目文档"等）时：
- 确认项目信息：询问项目名称和类型（游戏/web/cli/lib/通用）
- 运行初始化脚本：
python3 scripts/init_guide.py --project-name "名称" --type 类型 --root 项目根目录 - 引导填充 start.md：帮助用户填写启动命令、服务地址、文件清单表
- 引导填充 guide.md：帮助用户填写元信息、架构图、实体/模块概览
- 验证检查清单：
- [ ] start.md 启动命令可执行 - [ ] guide.md 文档索引表中的所有文件都存在 - [ ] 01-design.md 至少有项目定位描述 - [ ] 06-tech.md 至少有文件结构 - [ ] 08-changelog.md 有 v0.1 初始版本记录 - [ ] 09-pitfalls.md 有文件头和空模板
更新模式 — 详细执行步骤
当用户触发更新（说 当用户触发更新（说"更新guide"、"总结经验教训"等）时：
- 读取当前版本：从
guide/08-changelog.md获取最新版本号 - 收集更新内容：询问用户本次完成的功能/修复/改动
- 生成 changelog 条目：
- 版本号递增（补丁 +0.1，功能 +1.0） - 按子系统分组描述改动（含方法名和具体行为） - 🐛 Bug修复章节（问题+根因+修复） - 📝 代码改动章节（文件:方法 列表）
- 检查踩坑记录：询问是否有踩坑需要记录
- 生成 pitfall 条目（编号+现象+根因+方案+⚠️注意+通用原则） - 检查通用原则章节是否需要新增
- 同步更新：
- guide.md 版本号同步 - start.md 文件清单检查（有新文件则更新） - 07-plan.md checklist 更新（如有）
- 自动提醒：功能开发完成后，主动提示用户更新文档
上下文恢复模式 — 详细执行步骤
AI 在新对话中需要理解项目时，按以下分层策略读取文档。目标：用最少的文件读取获得最大的项目认知。
第1步：start.md — 30秒知道怎么跑
读取文件：项目根目录的 start.md
提取信息：
- 项目名称和一句话简介
- 启动/关闭/重启命令
- 服务地址（如有）
- 项目文件清单表（快速了解项目组成）
读取后应能回答：
- 这个项目怎么启动？端口是多少？
- 项目有哪些文件？每个文件做什么？
第2步：guide/guide.md — 2分钟获得全景
读取文件：guide/guide.md
提取信息：
- 技术路线（语言、框架、依赖）
- 当前版本号
- 文档索引表（知道还有哪些详细文档可读）
- Mermaid 架构图（核心系统间的关系）
- 核心实体/模块概览表
读取后应能回答：
- 项目是做什么的？核心目标是什么？
- 用了什么技术栈？
- 有哪些核心模块/子系统？它们之间什么关系？
- 当前开发到什么阶段了？
第3步：guide/08-changelog.md — 了解最新进展
读取策略：
- 如果文件 <200 行：全部读取
- 如果文件 >200 行：只读取最新 2-3 个版本 + 底部 Checklist
提取信息：
- 最新版本做了什么改动（功能/修复/重构）
- 未完成的 TODO 项（
- [ ]标记的） - 已知的紧急问题（🔴 标记的）
读取后应能回答：
- 最近做了什么？
- 还有什么没做完？哪些是紧急的？
- 上次修了什么 Bug？
第4步：guide/09-pitfalls.md — 避免重蹈覆辙
读取策略：
- 必读：文档末尾的「📋 通用开发原则」章节（这是最高优先级）
- 按需读：最近 5 条踩坑记录的标题和⚠️开发注意部分
- 如果即将修改某个子系统，搜索相关的坑记录
提取信息：
- 通用开发原则列表（直接作为开发约束使用）
- 已知的陷阱和规避方法
- 反复出现的问题模式
读取后应能回答：
- 开发时有哪些必须遵守的原则？
- 修改 XXX 时有什么需要注意的？
- 之前踩过什么坑？怎么解决的？
第5步：按需深入
根据用户的具体需求，选择性读取：
| 用户需求 | 读取文件 |
|---|---|
| 了解设计决策/为什么这样做 | 01-design.md |
| 理解代码结构/核心类 | 06-tech.md |
| 查看开发计划/排期 | 07-plan.md |
| 了解地图/场景设计（游戏） | 02-map.md |
| 了解NPC/角色系统（游戏） | 03-npc.md |
| 了解属性/数值系统（游戏） | 04-attributes.md |
| 了解AI/Prompt系统（游戏） | 05-ai.md |
| 了解路由设计（Web） | 02-routes.md |
| 了解组件设计（Web） | 03-components.md |
| 了解API设计（Web） | 05-api.md |
恢复模式选择
| 场景 | 推荐模式 | 读取范围 |
|---|---|---|
| 日常开发继续 | 快速恢复 | 第1步 + 第2步 + changelog最新版本 |
| 首次接手项目 | 完整恢复 | 第1~5步全读 |
| 排查特定问题 | 定向恢复 | 第4步（pitfalls）+ 相关领域文档 |
| 版本发布前检查 | 审查恢复 | 第2步 + 第3步 + 第4步通用原则 |