项目文档生成技能Skill project-documentation

---

name: project-documentation description: 遵循分层方法的综合代码库文档生成器。此技能适用于首次扫描和记录代码库时、为新开发人员创建入门文档时、生成架构概述、演练和API参考时。支持README生成、架构图、入口点文档、模式指南和边缘情况文档。

项目文档

用于扫描代码库并生成分层文档以帮助开发者快速熟悉的综合技能。

概述

此技能实现了6阶段文档方法：

1. 理解 - 在文档化之前探索代码库
2. 结构化 - 创建分层文档（高层/中层/低层）
3. 核心文档 - 生成核心文档
4. 函数 - 以意图记录代码
5. 入门 - 创建自定步调学习材料
6. 维护 - 保持文档版本化和可搜索

文档工作流程

阶段1：文档化前理解

在编写文档之前，彻底探索代码库：

1. 探索版本控制历史

   git log --oneline -50           # 最近更改
   git log --all --oneline --graph # 可视化分支历史
   git shortlog -sn                # 主要贡献者
   

2. 分析代码结构

   • 运行 tree -L 3 -I node_modules 获取结构
   • 识别入口点（main., index., app.*）
   • 检测框架模式（React, Express, FastAPI 等）

3. 阅读开发测试

   • 测试揭示代码预期如何工作
   • 失败的测试历史显示已修复问题
   • 测试结构镜像代码架构

4. 跟踪执行流

   • 从入口点跟踪导入
   • 映射API路由到处理程序
   • 记录数据流模式

阶段2：创建分层文档

生成三个文档层：

层	目的	受众	位置
高层	架构、设计原则	新开发者、利益相关者	docs/architecture/
演练	流程、模式、交互	贡献开发者	docs/walkthroughs/
低层	函数、参数、返回值	活跃维护者	内联 + docs/api/

阶段3：核心文档

使用 templates/ 中的模板生成：

1. README.md - 参见 templates/readme-template.md
2. 架构概述 - 参见 templates/architecture-template.md
3. 演练指南 - 参见 templates/walkthrough-template.md
4. API/函数参考 - 参见 templates/api-reference-template.md
5. 设置指南 - 参见 templates/setup-guide-template.md

阶段4：有效文档化函数

当文档化单个函数时：

• 描述原因，而非仅描述内容 - 业务假设、算法步骤
• 使用有意义的名字 - 自文档化代码
• 记录意图 - 设计选择、权衡
• 包括示例 - 预期使用模式

参考：references/function-documentation.md

阶段5：入门导向文档

创建自定步调入門材料：

• 清晰语言 - 避免未经解释的行话
• 代码片段 - 用示例说明概念
• 一致命名 - 类、函数、变量、文件
• 决策理由 - 解释编码决策

阶段6：可维护性

• 将文档与源代码版本化
• 使文档可搜索
• 从团队沟通渠道链接
• 随代码库演进逐步改进

文档优先级顺序

按此顺序生成文档：

1. README 与设置指令（让开发者运行）
2. 架构图 显示主要组件
3. 入口点 文档（代码起始处）
4. 核心模式 在整个代码库中使用
5. 关键函数/模块 带有目的和示例
6. 边缘情况和陷阱 让新手困惑的问题

输出结构

docs/
├── README.md                    # 项目概述
├── architecture/
│   ├── overview.md              # 系统架构
│   ├── components.md            # 组件描述
│   └── diagrams/                # 架构图
├── walkthroughs/
│   ├── entry-points.md          # 代码起始处
│   ├── data-flow.md             # 数据流动方式
│   └── patterns.md              # 重复模式
├── api/
│   ├── endpoints.md             # API端点
│   └── functions.md             # 关键函数
├── setup/
│   ├── installation.md          # 安装指南
│   ├── configuration.md         # 配置选项
│   └── troubleshooting.md       # 常见问题
└── onboarding/
    ├── quickstart.md            # 5分钟起步
    ├── tutorials/               # 动手教程
    └── gotchas.md               # 边缘情况与提示

扫描清单

• [ ] 分析版本控制历史
• [ ] 识别项目类型和框架
• [ ] 文档化入口点
• [ ] 映射目录结构
• [ ] 列出依赖项
• [ ] 识别关键模式
• [ ] 文档化配置文件
• [ ] 创建/更新README
• [ ] 生成架构概述
• [ ] 创建演练指南
• [ ] 生成API参考
• [ ] 完成设置指南
• [ ] 准备入门材料