scaffold-docs

Scaffold Docs

以自上而下的方式迭代构建代码库的技术文档，并在每一步征求用户审阅。编写文档也是写作的一部分。文案质量也在考量范围内，而不仅仅是结构。

核心原则

这些原则影响每一项决策。请始终遵循。

1. 面向特定受众写作。 文档是为某些人而写的。主要受众（在阶段 1b 中选定）决定之后的每一项选择：使用场景、脚手架、收益阐述、需要解释的内容和可以略过的内容。全程应用 references/audience-check.md。次要受众只用于打破平局，绝不能凌驾于主要受众之上。
2. 先建立心智模型。 文档应帮助读者建立对代码库的可用心智模型，而不是复述代码。决定纳入或删去哪些内容时，请自问：这是否能帮助读者建立心智模型？
3. 以用户心智模型为纲，而非软件包布局。 根据读者想要完成的任务来组织内容。源代码目录结构很少适合作为文档结构。
4. 解释原因，而不只是内容。 如果某项设计决策对理解或正确使用至关重要，就要解释为什么这样设计，而不只是说明是什么。利用代码注释、命名选择和代码异味作为意图的证据。
5. 只展示读者需要的依赖。 对于任何主题，先找出它依赖什么，然后只说明建立该主题的可用心智模型所必需的依赖。
6. 渐进式披露。 读者不应为了开始使用代码库而必须先理解整个代码库。分层组织文档，让读者可以在任意深度停下，同时仍拥有可用的心智模型。
7. 持续迭代，绝不一次成稿。 每个阶段都以用户审阅结束。用户批准当前版本之前，不要进入下一轮。
8. 清晰而不枯燥。 文案质量也是交付内容的一部分。每次润色文案时都要应用 references/prose-style.md。

输出结构

分为三个部分。每部分都有自己的用途、结构和文件布局。

• 入门指南：getting-started.md。一篇端到端的叙述式教程，围绕一个典型用例展开，并涵盖代码库最重要的组件。内容应通俗易懂。读者读完或跟着操作后，应能建立足够的心智模型，以便自行探索。
• 深入探索：diving-deeper/<topic>.md，每个主题一个文件。每个主题依次介绍主题意图、设计决策及其原因，然后按照每个对象的意图（而非字母顺序）讲解相关 API。
• 参考：reference/<module>.md，每个模块一个文件。内容应接近纯 API 规范，并按类、函数和模块组织。以便查阅为主，而非叙述式介绍。
• 元数据：.scaffold-docs.yml。以机器可读的形式记录受众、最近同步的 git SHA 和 ask_audience 标志。由阶段 1 写入，并由阶段 5 读取，以便在代码变更后更新文档。

工作流概览

Phase 1: Discovery and overall structure          → phases/1-discovery.md         [USER REVIEW]
  (read code → audiences → use case → topic inventory → overall-structure.md)
Phase 2: Build Getting Started in three passes    → phases/2-getting-started.md   [USER REVIEW × 3]
  Pass A: headers + learning bullets + code blocks
  Pass B: sub-headers + paragraph topic sentences (≤20 words, single SVO, no `; : — – ()`)
  Pass C: full paragraphs (using references/prose-style.md)
Phase 3: Build each selected Diving Deeper topic  → phases/3-diving-deeper.md     [USER REVIEW × 2 per topic]
Phase 4: Build Reference                          → phases/4-reference.md         [USER REVIEW per module]
Phase 5: Update existing docs after code changes  → phases/5-update.md            [USER REVIEW per bucket]
  (read .scaffold-docs.yml → baseline diff → classify changes → walk buckets)

如何使用此技能

每个阶段在 phases/ 下都有自己的文件。只加载当前正在处理的阶段。

更新现有文档？ 如果文档已存在，且用户希望在代码变更后更新文档，请从阶段 5（phases/5-update.md）开始，而不是阶段 1。阶段 5 会读取 .scaffold-docs.yml，以恢复受众信息和上次同步的提交。

阶段之间可以清除上下文。 磁盘上的产物（overall-structure.md、getting-started.md 等）是可靠的交接内容。每个阶段文件都以“在全新上下文中恢复”部分开头，其中会准确列出开始该阶段前需要读取哪些文件，以便了解最新进展。当对话变得冗长、跨会话继续，或清除上下文有助于集中注意力时，请使用此方式。

references/ 下的参考文件按需加载：

• references/audience-check.md：必须在阶段 2 和阶段 3 开始时阅读；阶段 5 找到受众时也必须阅读。主要受众（在阶段 1b 中选定）决定所有写作选择。
• references/diving-deeper-heuristics.md：用于阶段 1d 的主题标记，以及阶段 4 的退回决策。
• references/headline-style.md：在确定章节名称的结构审阅环节必须阅读（阶段 1e、阶段 2 的 A 轮、阶段 3 的 A 轮）。章节名称应体现读者的行动，而非仅使用名词。此文件比在行文审阅环节加载的 prose-style 更早加载。
• references/prose-style.md：进行任何行文审阅前都必须阅读（阶段 2 的 C 轮；阶段 3 的 B 轮）。阶段文件会明确指出具体时机。

执行规则（适用于所有阶段）

• 保存文件时始终显示文件路径。
• 不要跳过检查点，即使用户看起来很着急。迭代审阅正是此技能的意义所在。
• 修复当前轮次时，不要撰写下一轮的内容。 如果用户在 A 轮要求修改，就修复 A 轮并返回供其审阅。不要顺带加入 B 轮内容。
• 如果某个阶段内容较多（例如有 12 个深入探讨主题），建议分批处理，并让用户决定优先级。
• 不要把代码改写成文字。 如果 API 条目从其签名即可清楚理解，就说明这一点，然后继续。对于阅读代码无法看出的内容，再补充思维模型相关说明。