⚡

代码文档化Skill DocumentingCode

代码文档化技能用于维护项目文档与代码同步，确保功能规范、API合同和README等文档与项目标准保持一致。适用于代码变更后更新文档、添加新功能或确保文档完整性。关键词：代码文档、项目管理、文档同步、API文档、功能规范、SEO优化。

DevOps 0 次安装 0 次浏览 更新于 3/8/2026

name: 代码文档化 description: 维护项目文档与代码同步。保持功能规范、API合同和README与初始项目标准一致。适用于代码变更后更新文档、添加新功能或确保文档完整性时使用。

代码文档化

标准参考

所有文档遵循初始项目约定：

  • IDs: F-##（功能），US-###（用户故事）- 唯一且可在文档间追溯
  • 文件: docs/feature-specs/F-##-slug.yaml，docs/user-stories/US-###-slug.yaml
  • 前端内容: 必需的 title、status、last_updated 字段
  • 可追溯性: 每个 F-## 链接到产品需求文档（PRD），每个 US-### 链接到 F-## 功能

参考 /file-templates/init-project/CLAUDE.md 获取完整约定。

文档清单

必需文档（来自初始项目模板）：

  • docs/product-requirements.yaml - 项目目标、范围、功能、成功指标
  • docs/feature-specs/F-##-*.yaml - 每个 F-## 功能一个文件
  • docs/user-stories/US-###-*.yaml - 每个用户故事一个文件
  • docs/user-flows/*.yaml - 主要用户流程
  • docs/api-contracts.yaml - API 端点
  • docs/system-design.yaml - 架构
  • docs/data-plan.yaml - 指标和数据存储
  • docs/design-spec.yaml - UI/UX 规范

工作流程

1. 检查当前状态

在更改前，了解现有内容：

  • 阅读 docs/product-requirements.yaml 查看功能列表和当前状态
  • 检查 docs/feature-specs/ 中的现有功能文档
  • 查看 docs/api-contracts.yaml 的 API 覆盖情况
  • 扫描是否有损坏链接、过时示例或缺失文档

2. 更新文档

针对功能更改：

  • 在对应的 docs/feature-specs/F-##-*.yaml 中更新新需求
  • 在 docs/api-contracts.yaml 中添加/更新 API 端点
  • 如果范围改变，更新 docs/product-requirements.yaml
  • 在复杂逻辑的代码中添加 JSDoc 注释

针对新功能：

  • 创建 docs/feature-specs/F-##-slug.yaml，遵循初始项目模板
  • 在 PRD 功能表中添加 F-## 条目
  • 如果适用，在 docs/api-contracts.yaml 中创建 API 端点条目
  • 如果需要，在 docs/user-stories/US-###-slug.yaml 中创建用户故事

3. 验证标准符合性

最终确定前的检查清单：

  • [ ] 所有 PRD 中的 F-## IDs 都有对应的功能规范
  • [ ] 所有 US-### 故事链接到有效的 F-## 功能
  • [ ] API 合同匹配功能规范中的端点
  • [ ] 代码示例有效且最新
  • [ ] 文档间的链接有效
  • [ ] 前端内容包含必需字段（title、status、last_updated）
  • [ ] IDs 在文档间正确链接

4. 更新 README

保持主 README 最新：

  • 更新功能列表以匹配 PRD F-## 功能
  • 如果更改了安装/设置说明，进行刷新
  • 更新 API 参考链接
  • 根据需要添加新使用示例
  • 验证所有链接有效

项目管理命令

更新特定文档：

/manage-project/update/update-feature      # 更新功能规范
/manage-project/add/add-api                # 添加 API 端点
/manage-project/update/update-design       # 更新系统设计
/manage-project/update/update-requirements # 更新成功指标

验证命令：

/manage-project/validate/check-consistency # 验证所有 IDs 正确链接
/manage-project/validate/check-coverage    # 验证无孤立文档
/manage-project/validate/check-api-alignment # 验证 API 对齐

Bash 实用程序（从 docs/ 目录运行）：

./check-project.sh    # 完整验证
./list-features.sh    # 显示所有功能
./list-stories.sh     # 显示所有故事
./list-apis.sh        # 显示所有 API 端点

快速修复

  • 损坏链接： 用正确路径更新并验证
  • 过时示例： 测试代码样本并更新
  • 缺失功能文档： 创建 F-##-slug.yaml，遵循模板
  • API 更改： 更新 api-contracts.yaml 和对应的功能规范
  • 状态更新： 实施后标记功能为已完成

何时上报

  • 缺少初始项目模板中的必需文档
  • 可追溯性损坏（孤立 IDs）
  • 文档与实施冲突
  • 用户投诉文档过时