gstack 文档补齐实战用 /document-release 与 /document-generate 完成功能上线后的 Diataxis 文档覆盖【免费下载链接】gstackUse Garry Tans 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 workflowPR 已合并或即将合并、文档已过时的场景下如何通过/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.5Blast-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 9PR 正文中的文档债务汇总绝不自动生成缺失的文档页面——发现显著缺口时只建议运行/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链式调用范围就是覆盖地图中的实体。它的步骤与产出顺序是刻意设计的Step 0 Scope Intent——确定范围并询问文档落点A) 内联写入现有文件README、ARCHITECTURE 等B) 创建独立文档文件如docs/目录C) 两者兼有默认推荐兼顾可发现性与深度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. 的摘要——这个数字表明它真的读了代码而不是从文件名猜Step 2 Diataxis Partitioning——按实体类型决定写哪些象限。决策矩阵决定矩阵是实体类型Tutorial?How-to?Reference?Explanation?用户直接交互的新功能✅✅✅MaybeCLI 命令或 flagMaybe✅✅No内部模块/架构NoNo✅✅配置项No✅✅No设计模式/理念NoNoNo✅API 端点Maybe✅✅No多步工作流✅✅NoMaybe计划超过 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-visibilityHIGH 结果会阻断提交——因为生成文档中常出现示例凭据提交进文档里的活格式密钥就是泄露。步骤 4重跑 /document-release 验证缺口已闭合再次运行/document-release覆盖地图中此前被标记的实体应在先前为空的象限上显示绿色对勾。PR 正文的 Documentation Debt 小节应为空或只减少到你有意搁置的条目。最终验证清单打开 PR逐项确认PR 正文有## Documentation小节且包含 doc diff preview### Documentation Debt小节列出零个关键缺口或只有你已知晓并有意搁置的条目docs/中每个生成的文档文件能正常打开并且与同侪文档交叉链接reference → how-to → tutorial → explanation运行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-generatedocs/tutorial-document-generate.md解释为什么 gstack 采用 Diataxis 框架docs/explanation-diataxis-in-gstack.md审计技能参考document-release/SKILL.md生成技能参考document-generate/SKILL.mdPR 正文写入与 redaction 扫描的执行细节document-release/sections/release-body.md扫描顺序的回归测试test/document-skills-redaction.test.ts【免费下载链接】gstackUse Garry Tans 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考