Project Guide Document Generator
概述
此 skill 帮助自动生成和维护项目的 DEVELOPMENT_GUIDE.md 开发指南文档。它会：
-
🔍 自动扫描项目结构和技术栈
-
📝 生成标准化的开发文档模板
-
🚀 提取常用命令和工作流程
-
📚 为新成员提供完整的入职指南
使用场景
当用户提出以下需求时使用此 skill：
-
"帮我创建项目文档"
-
"生成开发指南"
-
"写一个 DEVELOPMENT_GUIDE"
-
"新人怎么快速上手这个项目？"
-
"需要一个项目说明文档"
-
"更新项目的 README 或开发文档"
工作流程
第一步：了解项目需求
首先询问用户项目的基本信息（如果从对话中无法推断）：
-
项目的根目录路径是什么？
-
项目的主要用途是什么？（如：SaaS 平台、移动应用、API 服务等）
-
是否有特殊的架构或约定需要说明？
第二步：运行生成脚本
使用项目根目录运行生成脚本：
python3 scripts/generate_guide.py --project-root <项目根目录> [--output <输出路径>]
参数说明：
-
--project-root : 项目的根目录路径（必需）
-
--output : 输出文件路径（可选，默认为 docs/DEVELOPMENT_GUIDE.md ）
-
--project-name : 项目名称（可选，默认从目录名推断）
-
--update : 更新现有文档而不是覆盖（可选）
示例：
为当前项目生成开发指南
python3 scripts/generate_guide.py --project-root /Users/username/my-project
自定义输出路径
python3 scripts/generate_guide.py --project-root /Users/username/my-project --output docs/DEV_GUIDE.md
更新现有文档
python3 scripts/generate_guide.py --project-root /Users/username/my-project --update
第三步：审阅和定制
脚本会生成包含以下章节的文档：
-
项目概述 - 项目简介和主要功能
-
架构与项目结构 - 目录结构和关键文件说明
-
技术栈 - 使用的语言、框架和工具
-
开发环境设置 - 安装依赖和配置步骤
-
常用命令 - 开发、测试、构建等命令
-
编码规范 - 代码风格和最佳实践
-
API 文档 - API 端点和使用说明（如适用）
-
故障排除 - 常见问题和解决方案
生成后，建议：
-
审阅自动生成的内容
-
补充项目特定的细节
-
添加团队约定和业务逻辑说明
第四步：维护和更新
建议定期更新开发指南：
-
当添加新功能模块时
-
当技术栈发生变化时
-
当团队规范更新时
使用 --update 参数可以保留手动添加的内容。
脚本功能说明
generate_guide.py 脚本会自动检测：
技术栈识别
-
前端：package.json (Node.js, React, Vue, Next.js 等)
-
后端：requirements.txt (Python), go.mod (Go), package.json (Node.js)
-
移动端：pubspec.yaml (Flutter), Podfile (iOS), build.gradle (Android)
-
数据库：配置文件中的数据库连接信息
项目结构分析
-
扫描主要目录（src/, app/, pages/, components/ 等）
-
识别配置文件和重要文档
-
提取项目模式（单体应用、微服务、前后端分离等）
命令提取
-
npm/yarn scripts (package.json)
-
Python 脚本 (scripts/ 目录)
-
Makefile 命令
-
Docker 命令（如有 Dockerfile）
最佳实践
参考 guide_writing_best_practices.md 了解：
-
如何编写清晰的开发文档
-
优秀入职指南的要素
-
文档结构的组织原则
-
保持文档更新的策略
模板定制
如需自定义文档模板，可编辑 assets/DEVELOPMENT_GUIDE_TEMPLATE.md 。模板使用以下占位符：
-
{{PROJECT_NAME}}
-
项目名称
-
{{PROJECT_DESCRIPTION}}
-
项目描述
-
{{TECH_STACK}}
-
技术栈列表
-
{{DIRECTORY_STRUCTURE}}
-
目录结构树
-
{{SETUP_COMMANDS}}
-
安装和设置命令
-
{{DEV_COMMANDS}}
-
开发常用命令
-
{{BUILD_COMMANDS}}
-
构建和部署命令
注意事项
-
首次生成：脚本会创建 docs/ 目录（如不存在）
-
更新模式：使用 --update 时会尝试合并现有内容，但请先备份
-
手动补充：自动生成的内容是基础框架，需要补充业务逻辑和团队约定
-
版本控制：建议将生成的文档纳入版本控制
示例输出
生成的 DEVELOPMENT_GUIDE.md 将类似于：
My Project - Development Guide
📋 项目概述
[自动生成的项目描述]
🏗️ 架构与项目结构
[目录树和说明]
🛠️ 技术栈
- Frontend: React 18 + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL ...
🚀 开发环境设置
[安装步骤]
💻 常用命令
[npm scripts 和其他命令] ...
完整的模板请查看 assets/DEVELOPMENT_GUIDE_TEMPLATE.md 。