企业官网建设流程全解析

gstack 文档补齐实战：用 /document-release 与 /document-generate 完成功能上线后的 Diataxis 文档覆盖

【免费下载链接】gstackUse Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack

本文讲解 gstack 的"上线后文档工作流"（post-ship workflow）：PR 已合并或即将合并、文档已过时的场景下，如何通过/document-release审计出文档覆盖缺口，再用/document-generate按 Diataxis 四象限（tutorial / how-to / reference / explanation）补齐缺口。读完后你能掌握完整的审计命令、覆盖地图（coverage map）的读法、PR 正文中 Documentation Debt 小节的含义，以及每一步的验证方法与排障手段。

工作流定位与前置条件

这套工作流的设计前提是：你刚刚合并（或即将合并）一个 PR，代码已上线，但文档很可能与代码脱节。整个流程分两步走——先跑/document-release做审计，再跑/document-generate填补它发现的缺口。

运行前需满足以下前置条件：

• gstack 已安装（./setup执行完毕；可用which gstack验证，或在 Claude Code 中输入/能看到技能列表）；
• 已检出包含该上线功能的分支；
• GitHub 或 GitLab 上存在对应 PR（推荐——工作流会把覆盖地图写进 PR 正文）。

如果 PR 还不存在，先运行/ship创建一个，这是/document-release的设计运行对象。没有 PR 时/document-release仍然可以做审计，但会跳过 PR 正文更新。

理解审计语言：Diataxis 覆盖地图

/document-release的核心不是"文档是否存在"，而是按 Diataxis 框架给每个新暴露的公共实体打分。其定义来自 document-release/SKILL.md 的 Step 1.5（Blast-Radius Analysis），四个象限的定义是：

• Reference（参考）——事实性描述：它是什么、API 长什么样、有哪些选项（如 README 表格、AGENTS.md 技能列表、API 文档）；
• How-to（任务指南）——任务导向："如何用这个完成 X"（如 README 示例、CONTRIBUTING 工作流）；
• Tutorial（教程）——学习导向：面向新手的分步演示（如 getting started 指南）；
• Explanation（解释）——理解导向："为什么是这个设计"（如 ARCHITECTURE 中的设计决策）。

为什么选 Diataxis 作为审计词汇，而不是自定分类？gstack 自己的解释文档 docs/explanation-diataxis-in-gstack.md 给出了三个理由：文档腐化是无声的（README 依然能解析、安装命令依然能复制粘贴，唯一信号是几周后用户的困惑）；团队各自为政的文档格式无法被工具跨项目审计；以及工程师在"构建模式"下只会写参考文档、在"发布模式"下才会写教程，导致解释类文档腐化最快。Diataxis 因为被 CPython、Django、NumPy、FastAPI、GitHub docs 等广泛采用，是最容易被下游用户理解的通用词汇。

步骤 1：运行 /document-release 审计当前覆盖

运行：

/document-release

技能会遍历你的分支与基线分支的 diff，提取新的公共表面（新技能、CLI flag、配置项、API 端点、新模块），然后对每个实体在四个象限上打分。你会看到形如这样的覆盖地图：

Coverage map: [entity] [reference?] [how-to?] [tutorial?] [explanation?] /new-skill ✅ AGENTS.md ❌ ❌ ❌ --new-flag ✅ README ✅ README ❌ ❌ FooProcessor ❌ ❌ ❌ ❌

其中：

• 零覆盖的条目是critical gaps（关键缺口）；
• 仅有 reference 覆盖的条目是common gaps（常见缺口）——这是 gstack 自身历史上最常见的失败模式。

两类缺口都会以### Documentation Debt小节的形式落到 PR 正文里，让评审者直接看到。

底层实现细节：从源码看，document-release/SKILL.md 中 Step 1.5 明确要求"在动任何文档文件之前"先构建覆盖地图，并规定了它的边界：

• 地图只"喂给" Step 2-3（审计与修复什么）和 Step 9（PR 正文中的文档债务汇总），绝不自动生成缺失的文档页面——发现显著缺口时只建议运行/document-generate；
• 附带架构图漂移检测：如果 ARCHITECTURE.md 中有 ASCII 图或 Mermaid 块，会提取图中的实体名（模块、服务、数据流）与 diff 交叉比对，标记那些在代码中被重命名、拆分、移除或挪动位置的实体。但漂移标记只是建议性的——技能不会自动修改 ASCII 艺术或 Mermaid 块，因为那需要人类判断。

若/document-release报告一切都有覆盖，你可以跳过本 how-to 的其余部分，直接去合入。

步骤 2：阅读 PR 正文中的 Documentation Debt 小节

打开你的 PR（技能会打印 URL），滚动到## Documentation→### Documentation Debt。每条缺口都标注了"能填补它的是哪个象限"：

### Documentation Debt - ⚠️ /new-skill — has reference in AGENTS.md but no how-to example in README. Diataxis quadrant: how-to. - ⚠️ FooProcessor — zero coverage. Diataxis quadrants: reference, explanation.

这就是下一步的输入。每一行都告诉你缺了什么、以及补哪个象限能填上这个缺口。

从 document-release/sections/release-body.md（技能 Step 9 的执行细节）可以看到，## Documentation小节实际包含两块内容：doc diff preview（本次每个文档文件具体改了什么，例如 "README.md: added /document-release to skills table, updated skill count from 9 to 10"）和documentation debt（关键缺口、仅参考覆盖的常见缺口、以及实体名漂移的过期图）。若存在债务条目，技能还会建议给 PR 打上docs-debt标签。

步骤 3：用 /document-generate 填补缺口

运行：

/document-generate

当技能询问范围（scope）时，告诉它债务小节里点名的具体实体。技能会先读代码库（其 Step 1 的"代码考古"阶段是强制的），再按 Diataxis 象限分区，然后写出缺失的文档。

你也可以让技能自动发现：如果/document-release链式调用了/document-generate（链式运行时它会显式把缺口传过去），/document-generate已经知道该写什么。

生成侧的 9 步工作流：从 document-generate/SKILL.md 可以看到，/document-generate支持两种调用方式——独立调用（你指定一个功能/模块/整个项目，说 "document this"）和从/document-release链式调用（范围就是覆盖地图中的实体）。它的步骤与产出顺序是刻意设计的：

1. Step 0 Scope & Intent——确定范围，并询问文档落点：A) 内联写入现有文件（README、ARCHITECTURE 等）；B) 创建独立文档文件（如docs/目录）；C) 两者兼有（默认推荐，兼顾可发现性与深度）；
2. Step 1 Codebase Archaeology（代码考古）——最关键的步骤。读取项目结构、入口文档（README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md）、目标实体的实现文件（端到端读完整文件，而非只看签名）、测试（揭示预期行为与边界情况）、以及// NOTE:、// DESIGN:、// WHY:等内联注释。产出一句形如 "Researched 47 files, identified 12 public surface items, 8 concepts, and 4 design decisions." 的摘要——这个数字表明它真的读了代码，而不是从文件名猜；
3. Step 2 Diataxis Partitioning——按实体类型决定写哪些象限。决策矩阵（决定矩阵）是：

计划超过 5 个文档时，技能会先请求确认再动手； 4.Step 3-6 按 reference → explanation → how-to → tutorial 的顺序写作——这个顺序匹配依赖关系：reference 先固定词汇表，explanation 论证设计，how-to 构建在前两者之上，tutorial 最后且最难。tutorial 有硬约束："3 步内必须看到可运行的结果"（time to first result < 3 steps）； 5.Step 7 跨文档链接——每个 reference 链接到它的 how-to，反之亦然；每个新文档必须从 README.md 出发 2 次点击内可达；grep 检查](引用不指向缺失文件； 6.Step 8 Quality Self-Review——三道门：准确性（代码示例可复制运行、API 描述与实际签名一致）、完整性（reference 覆盖 100% 公共表面、how-to 覆盖用户最可能做的 3 个任务、tutorial 3 步内出结果、explanation 明确写出 trade-offs）、文风（写给"聪明但没看过代码的人"，术语首次出现需内联解释）； 7.Step 9 Commit & Output——按文件名暂存（绝不git add -A）、提交、推送，并在 PR 存在时向正文写入## Documentation Generated表格（每个新文件 + 象限 + 一句话描述）。

防泄密扫描（源码级证据）：两个技能在提交前都有 redaction 扫描，且有测试固化了扫描与写操作的先后顺序。test/document-skills-redaction.test.ts 断言：/document-release在gh pr edit写回 PR 正文之前先扫描临时文件gstack-redact --from-file /tmp/gstack-pr-body-$$.md，且 HIGH 级（exit 3）结果会阻断编辑；/document-generate在git commit之前扫描git diff --cached的新增行（gstack-redact --repo-visibility），HIGH 结果会阻断提交——因为"生成文档中常出现示例凭据，提交进文档里的活格式密钥就是泄露"。

步骤 4：重跑 /document-release 验证缺口已闭合

再次运行：

/document-release

覆盖地图中，此前被标记的实体应在先前为空的象限上显示绿色对勾。PR 正文的 Documentation Debt 小节应为空，或只减少到你有意搁置的条目。

最终验证清单

打开 PR，逐项确认：

1. PR 正文有## Documentation小节，且包含 doc diff preview；
2. ### Documentation Debt小节列出零个关键缺口（或只有你已知晓并有意搁置的条目）；
3. docs/中每个生成的文档文件能正常打开，并且与同侪文档交叉链接（reference → how-to → tutorial → explanation）；
4. 运行grep -rE '\]\([^)]*\.md\)' docs/，确认没有任何链接指向不存在的文件。

四项全部通过，你的 PR 就可以带着完整文档合入了。

排障（Troubleshooting）

/document-release报告 "No public surface changes detected."diff 是纯内部改动（重构、测试、基础设施）。不需要文档，直接跳到合入。

缺口的 Diataxis 象限标签与你的预期不符。技能用实体分类法（entity taxonomy）决定哪些象限重要：CLI flag 需要 reference + how-to；内部模块需要 reference + explanation；面向用户的功能需要全部四个。如果你不同意，可以在生成后手工编辑文档来覆盖。审计是指南，不是约束。

/document-generate写出了要 8 步才能到可运行结果的教程。教程应在 3 步内达到可运行结果。重跑技能并要求压缩，或手工编辑。Step 8 的 Quality Self-Review 能抓到其中一部分，但抓不到全部。

想给功能补文档，但 PR 还不存在。先运行/ship创建 PR，再走本工作流。没有 PR 时，/document-release仍能审计，但会跳过 PR 正文更新。

生成的 reference 文档出现了幻觉式 API 签名。提交 bug。技能的 Step 1 代码考古本应端到端读取实现文件而不只是签名，正是为了防止这一点。请在报告时附上生成的文本和实际代码，以便追踪考古阶段为何遗漏。

参考资料

• 教程：首次使用/document-generate：docs/tutorial-document-generate.md
• 解释：为什么 gstack 采用 Diataxis 框架：docs/explanation-diataxis-in-gstack.md
• 审计技能参考：document-release/SKILL.md
• 生成技能参考：document-generate/SKILL.md
• PR 正文写入与 redaction 扫描的执行细节：document-release/sections/release-body.md
• 扫描顺序的回归测试：test/document-skills-redaction.test.ts

【免费下载链接】gstackUse Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack