Communitygithub.com

文档厨师

自动生成和维护项目文档。创建 README、API 文档、架构文档、变更日志,并使它们与代码变更保持同步。一个解决“文档永不落后”问题的技能。

文档厨师 是什么?

文档厨师是一个全面的文档生命周期管理技能,专为 AI 代理(如 Claude Code、Cursor 等)设计,用于自动生成和维护项目文档。其核心功能包括:在项目初始化时生成 README、架构说明和 API 参考;在代码变更后增量更新受影响的部分;根据 Git 提交历史自动生成变更日志。该技能特别强调一个关键原则:文档必须源自实际代码,绝不凭空捏造。它能够扫描代码库以提取项目名称、技术栈、路由、导出项和配置,并生成可追溯到具体文件或函数的文档。更重要的是,它内置了“交叉文档一致性检查”,确保 README、CLAUDE.md、CHANGELOG 等不同文档中的版本号、功能列表和统计数据保持一致,从根本上解决了文档过时或相互矛盾的问题。同时,它通过“硬门控”机制来防止删除用户内容或凭空捏造 API,确保文档的准确性和可靠性。该技能适用于 scaffold、cook、launch 等开发流程,并可通过 `/rune docs` 命令直接调用。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Rune-kit/rune/tree/HEAD/skills/docs

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

文档

目的

文档生命周期管理器。生成初始项目文档,使文档与代码变更保持同步,生成 API 参考,并自动生成变更日志。解决了文档领域的头号问题:文档存在但已过时。

触发器

  • 由 scaffold 的 Phase 7 在初始文档生成时调用
  • 由 cook 在 Phase 7 之后调用,以在功能实现后更新文档
  • 由 launch 在部署前调用,以确保文档是最新的
  • /rune docs init — 首次文档生成
  • /rune docs update — 将文档与最近的代码变更同步
  • /rune docs api — 生成 API 文档
  • /rune docs changelog — 从 Git 历史自动生成变更日志

调用(出站)

  • scout (L2):扫描代码库以获取文档目标(路由、导出、组件、配置)
  • doc-processor (L3):按需生成 PDF/DOCX 导出
  • git (L3):读取变更日志生成的提交历史

被谁调用(入站)

  • scaffold (L1):Phase 7 — 为新项目生成初始文档
  • cook (L1):实现后 — 为变更的模块更新文档
  • launch (L1):部署前 — 验证文档是最新的
  • mcp-builder (L2):生成 MCP 服务器文档
  • 用户:直接调用 /rune docs

模式

初始化模式 — /rune docs init

项目的首次文档生成。

更新模式 — /rune docs update

增量同步 — 仅更新受近期代码变更影响的文档。

API 模式 — /rune docs api

专门生成或更新 API 文档。

变更日志模式 — /rune docs changelog

从 Git 提交历史自动生成变更日志。

可执行步骤

初始化模式

步骤 1 — 扫描代码库

调用 rune:scout 以提取:

  • 项目名称、描述、技术栈
  • 目录结构和关键文件
  • 入口点(main, index, app)
  • 公共 API 表面(导出、路由、组件)
  • 配置文件(.env.example, 配置模式)
  • 现有文档(如有 — 合并,而非覆盖)

步骤 2 — 生成 README.md

结构:

# [项目名称]
[一行描述]

## 快速开始
[3-5 条命令启动:安装、配置、启动]

## 功能特性
[从代码中提取的列表 — 路由、组件、能力]

## 技术栈
[从 package.json, requirements.txt, Cargo.toml 等检测]

## 项目结构
[关键目录及其一行描述]

## 配置
[来自 .env.example 的环境变量及其描述]

## 开发
[开发服务器、测试、检查、构建命令]

## API 参考
[API.md 的链接(如适用),或内联摘要]

## 许可证
[从 LICENSE 文件或 package.json 检测]

步骤 3 — 生成 ARCHITECTURE.md(如果项目有 10 个以上文件)

结构:

# 架构

## 概述
[以文本/mermaid 形式呈现的系统图 — 组件和数据流]

> 架构概述可以调用 `rune:diagram` 来生成设计的系统图(类型为 `architecture`)而不是原始的 Mermaid — `suggested_next: diagram`。

## 关键决策
[检测到的模式:框架选择、状态管理、数据库、认证方式]

## 模块映射
[每个顶级目录:目的、关键文件、依赖关系]

## 数据流
[请求生命周期或数据管道描述]

步骤 4 — 生成 API.md(如果检测到路由/端点)

扫描路由文件并提取:

  • HTTP 方法 + 路径
  • 请求参数(路径、查询、主体)
  • 响应格式
  • 认证要求
  • 错误响应

格式化为 Markdown 表格或兼容 OpenAPI 的参考。

步骤 5 — 报告

向用户呈现生成的文档,并附上摘要:

  • 生成的文件:[列表]
  • 覆盖率:[记录了哪些内容与存在哪些内容]
  • 差距:[没有文档的代码区域 — 建议下一步操作]

更新模式

步骤 1 — 检测变更

读取自上次文档更新以来的 git diff(通过文档文件的 Git 日志或 .rune/docs-sync.json 跟踪)。

识别:

  • 新文件/模块 → 需要新的文档章节
  • 变更的函数/路由 → 需要文档更新
  • 已删除的代码 → 需要删除文档
  • 新配置 → 需要更新配置文档

步骤 2 — 更新受影响的章节

对于每个变更的区域:

  1. 读取变更的代码
  2. 找到对应的文档章节
  3. 更新文档以匹配当前代码
  4. 如果文档章节不存在 → 创建它
  5. 如果代码已被删除 → 在文档中标记为已删除或弃用

步骤 3 — 生成变更日志条目

委托给 rune:git changelog,以从上次文档更新以来的提交中生成变更日志条目。

步骤 4 — 交叉文档一致性检查

交叉文档一致性可防止第二常见的文档问题:文档存在但相互矛盾。

在更新任何文档后,验证所有项目文档的一致性:

检查项文件比较内容
版本号README, CLAUDE.md, package.json, CHANGELOG必须全部匹配当前版本
功能列表README, 登录页面, CLAUDE.md列出的功能相同(详细程度可能不同)
统计数据README, CLAUDE.md, 登录页面, 仪表盘技能数量、测试数量、信号数量必须匹配
命令README, CLAUDE.md, docs/相同的命令带有相同的标志
技术栈README, ARCHITECTURE.md, CLAUDE.md一致的框架/库引用
交叉文档一致性:
- [x] README.md ↔ CLAUDE.md:版本匹配,命令匹配
- [x] README.md ↔ docs/index.html:统计数据匹配,功能匹配
- [ ] README.md 说“62 个技能”但 CLAUDE.md 说“59 个” → 修复 CLAUDE.md

立即修复不一致之处 — 不仅仅是报告它们。更新陈旧的文档以匹配事实来源(通常是代码或最近更新的文档)。

步骤 5 — 报告

向用户展示:更新了什么,添加了什么,标记了哪些内容以供审查。包括交叉文档一致性结果。

API 模式

步骤 1 — 检测 API 框架

框架路由模式文件模式
Expressrouter.get/post/put/deleteroutes/*.ts, *.router.ts
FastAPI@app.get/post/put/deleterouters/*.py, main.py
NestJS@Get/@Post/@Put/@Delete*.controller.ts
Next.js Appexport async function GET/POSTapp/**/route.ts
Next.js Pagesexport default function handlerpages/api/**/*.ts
SvelteKitexport function GET/POSTsrc/routes/**/+server.ts
Honoapp.get/post/put/deletesrc/*.ts

步骤 2 — 提取端点

对于每个检测到的路由:

  • 方法(GET, POST, PUT, DELETE, PATCH)
  • 路径(高亮参数)
  • 请求:参数、查询、主体形状(来自 Zod schema、TypeScript 类型、Pydantic 模型)
  • 响应:形状(来自返回类型或响应辅助函数)
  • 认证:是否需要?(检测诸如 authMiddleware, @UseGuards 之类的中间件)
  • 描述:如果可用,来自 JSDoc/docstring

步骤 3 — 生成 API 参考

格式化为 Markdown:

# API 参考

## 认证
[认证机制描述]

## 端点

### `POST /api/auth/login`
**描述**:验证用户身份并返回令牌
**认证**:无
**请求体**:
| 字段 | 类型 | 必填 | 描述 |
|-------|------|----------|-------------|
| email | string | 是 | 用户邮箱 |
| password | string | 是 | 用户密码 |

**响应** (200):
```json
{ "token": "string", "refreshToken": "string" }

错误:

  • 401:无效凭据
  • 422:验证错误

#### 步骤 4 — 输出

保存到 `docs/API.md` 或项目特定位置。如果请求 OpenAPI,则生成 `openapi.yaml`。

### 变更日志模式

#### 步骤 1 — 委托给 Git

调用 `rune:git changelog` 以按类型对提交进行分组,并格式化为“Keep a Changelog”。

#### 步骤 2 — 增强

向原始变更日志添加上下文:
- 将 PR 编号链接到实际描述
- 将相关更改分组到功能标题下
- 突出显示重大变更

#### 步骤 3 — 输出

追加到或更新 `CHANGELOG.md`。

## 输出格式

### 初始化模式输出

在项目根目录生成的文件:
- `README.md` — 快速开始、功能特性、技术栈、结构、配置、开发命令
- `ARCHITECTURE.md` — 概述图、关键决策、模块映射、数据流(如果有 10 个以上文件)
- `docs/API.md` — 端点参考,包含方法、路径、参数、响应、认证(如果检测到路由)

### 更新模式输出

修改的文档章节及变更摘要:

文档更新报告:

  • 已更新:[修改的文档章节列表]
  • 已添加:[新代码的新章节]
  • 已标记:[引用已删除代码的陈旧章节]
  • 变更日志:[已追加到 CHANGELOG.md 的条目]

### API 模式输出

`docs/API.md` — 按端点的 Markdown 参考:

METHOD /path/:param

描述:[来自 JSDoc/docstring] 认证:[必需/无] 请求:[参数、查询、主体表格] 响应:[包含状态码的形状] 错误:[错误码及描述]


### 变更日志模式输出

`CHANGELOG.md` — “Keep a Changelog”格式,按以下分组:新增、修复、变更、移除。

## 约束

1. 必须从实际代码生成文档 — 绝不捏造不存在的功能或 API
2. 必须保留现有文档 — 更新章节,而不是覆盖整个文件
3. 必须检测文档过时 — 标记引用已删除/变更代码的章节
4. 每个 README 必须包含快速开始 — 用户需要在 2 分钟内启动
5. 不得为尚不存在的代码生成文档(除非明确创建规范文档)
6. API 文档必须与实际路由签名匹配 — 错误的 API 文档比没有文档更糟糕

## 输出物

| 工件 | 格式 | 位置 |
|----------|--------|--------------|
| README.md | Markdown | 项目根目录 |
| ARCHITECTURE.md | Markdown | 项目根目录(如果有 10 个以上文件) |
| API 参考 | Markdown | `docs/API.md` |
| 变更日志条目 | Markdown (Keep a Changelog) | `CHANGELOG.md` |
| 文档更新报告 | Markdown | 内联(聊天输出) |

**范围护栏:** 只记录代码库中存在的内容 — 绝不捏造功能、端点或 API。

## 边缘情况

| 失败模式 | 严重性 | 缓解措施 |
|---|---|---|
| 凭空捏造不存在的 API 端点 | 严重 | 约束 1:扫描实际路由文件,而非猜测 |
| 覆盖用户编写的 README 章节 | 高 | 约束 2:合并,而非覆盖 — 检测自定义章节 |
| 代码变更后文档过时 | 高 | 更新模式检测差异并更新受影响的章节 |
| API 文档具有错误的请求/响应格式 | 高 | 从 Zod/Pydantic/TypeScript 类型提取,而非凭记忆 |
| 缺少快速开始章节 | 中 | 约束 4:每个 README 都有快速开始 |
| 变更日志包含孤立的 PR 链接 | 低 | 链接前验证 PR 编号是否存在 |
| 交叉文档不一致(README 说 X,CLAUDE.md 说 Y) | 高 | 步骤 7:交叉文档一致性检查 — 验证所有文档中的统计数据、版本和功能列表是否匹配 |
| 更新一个文档但不更新其他文档(统计数据漂移) | 高 | 在更新任何文档后,扫描所有相关文档以查找陈旧的统计数据 — 特别是 README ↔ CLAUDE.md ↔ 登录页面 |

## 完成条件

### 初始化模式
- 使用 scout 扫描代码库
- 生成 README.md,包含快速开始、功能特性、技术栈、结构
- 生成 ARCHITECTURE.md(如果有 10 个以上文件)
- 生成 API.md(如果检测到路由)
- 向用户展示覆盖率报告

### 更新模式
- 检测到自上次文档更新以来的变更
- 更新受影响的文档章节
- 生成变更日志条目
- 向用户展示更新报告

### API 模式
- 检测到 API 框架
- 提取所有端点,包含方法、路径、请求、响应
- 以 Markdown 格式生成 API 参考
- 保存到 docs/API.md

### 变更日志模式
- 提交按类型分组
- 格式化为“Keep a Changelog”
- 更新 CHANGELOG.md

## 成本概况

大约 2000-5000 个输入令牌,大约 1000-3000 个输出令牌。Sonnet — 文档编写需要理解代码模式,但无需深入的架构推理。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能