revol-guide-creator
by @revolgmphl
通用项目文档指南生成器：为任何项目创建和维护标准化的 guide 文档体系（start.md + guide/ 目录），覆盖设计理念、技术架构、更新日志、踩坑记录等完整生命周期。支持三种模式：(1) 初始化模式 — 一键创建标准化文档骨架；(2) 更新模式 — 追加 changelog/pitfalls/版本号同...
clawhub install guide-creator📖 About This Skill
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"
1. 运行 scripts/init_guide.py --project-name "项目名" --type game|web|cli|lib|general --root /path/to/project
2. 自动创建 start.md + guide/ 目录及全部模板文件
3. 按提示填充关键内容（启动命令、文件清单、架构图等）
模式 2：更新项目文档
用户说："更新guide" / "总结经验教训" / "update guide"
1. 运行 scripts/update_guide.py --action add-changelog|add-pitfall|bump-version|sync-files --root /path/to/project
2. 或直接告诉 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，按项目类型）：
格式约束
1. 版本号：vX.Y 格式（如 v2.3），记录在 guide.md 元信息和 08-changelog.md 顶部
2. Changelog 条目格式：## vX.Y — 标题摘要 (YYYY-MM-DD) + 按子系统分组 + 🐛Bug修复 + 📝代码改动
3. Pitfall 条目格式：## 🔥 坑N：标题 + 问题现象 + 问题根因 + 解决方案 + ⚠️开发注意 + 加粗通用原则
4. 文档索引表：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架构图 |
文件保护
guide/archive/详细模式指令
完整的模式执行指令请参考以下文件：
初始化模式 — 详细执行步骤
当用户触发初始化（说 当用户触发初始化（说"初始化项目guide"、"创建项目文档"等）时：
1. 确认项目信息：询问项目名称和类型（游戏/web/cli/lib/通用）
2. 运行初始化脚本：python3 scripts/init_guide.py --project-name "名称" --type 类型 --root 项目根目录
3. 引导填充 start.md：帮助用户填写启动命令、服务地址、文件清单表
4. 引导填充 guide.md：帮助用户填写元信息、架构图、实体/模块概览
5. 验证检查清单：
- [ ] start.md 启动命令可执行
- [ ] guide.md 文档索引表中的所有文件都存在
- [ ] 01-design.md 至少有项目定位描述
- [ ] 06-tech.md 至少有文件结构
- [ ] 08-changelog.md 有 v0.1 初始版本记录
- [ ] 09-pitfalls.md 有文件头和空模板
更新模式 — 详细执行步骤
当用户触发更新（说 当用户触发更新（说"更新guide"、"总结经验教训"等）时：
1. 读取当前版本：从 guide/08-changelog.md 获取最新版本号
2. 收集更新内容：询问用户本次完成的功能/修复/改动
3. 生成 changelog 条目：
- 版本号递增（补丁 +0.1，功能 +1.0）
- 按子系统分组描述改动（含方法名和具体行为）
- 🐛 Bug修复章节（问题+根因+修复）
- 📝 代码改动章节（文件:方法 列表）
4. 检查踩坑记录：询问是否有踩坑需要记录
- 生成 pitfall 条目（编号+现象+根因+方案+⚠️注意+通用原则）
- 检查通用原则章节是否需要新增
5. 同步更新：
- guide.md 版本号同步
- start.md 文件清单检查（有新文件则更新）
- 07-plan.md checklist 更新（如有）
6. 自动提醒：功能开发完成后，主动提示用户更新文档
上下文恢复模式 — 详细执行步骤
AI 在新对话中需要理解项目时，按以下分层策略读取文档。目标：用最少的文件读取获得最大的项目认知。
第1步：start.md — 30秒知道怎么跑
读取文件：项目根目录的 start.md
提取信息：
读取后应能回答：
第2步：guide/guide.md — 2分钟获得全景
读取文件：guide/guide.md
提取信息：
读取后应能回答：
第3步：guide/08-changelog.md — 了解最新进展
读取策略：
提取信息：
- [ ] 标记的）读取后应能回答：
第4步：guide/09-pitfalls.md — 避免重蹈覆辙
读取策略：
提取信息：
读取后应能回答：
第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步通用原则 |
💡 Examples
模式 1：初始化项目文档
用户说："初始化项目guide" / "创建项目文档" / "init guide"
1. 运行 scripts/init_guide.py --project-name "项目名" --type game|web|cli|lib|general --root /path/to/project
2. 自动创建 start.md + guide/ 目录及全部模板文件
3. 按提示填充关键内容（启动命令、文件清单、架构图等）
模式 2：更新项目文档
用户说："更新guide" / "总结经验教训" / "update guide"
1. 运行 scripts/update_guide.py --action add-changelog|add-pitfall|bump-version|sync-files --root /path/to/project
2. 或直接告诉 AI 本次更新内容，由 AI 生成格式化条目并追加
模式 3：上下文恢复
AI 在新对话开始时，按推荐顺序读取文档快速理解项目。
推荐阅读顺序：start.md → guide/guide.md → guide/08-changelog.md → guide/09-pitfalls.md → 按需读取 01~07