用Claude构建骨架技术文档：Doc-to-Code追踪矩阵实践

在一个快速迭代的代码库中维护文档，一直是公认的难题。新功能不断上线，API 持续变化，配置开关越来越多——而 docs/ 目录往往慢慢沦为过时搭建指南和缺失参考资料的一片废墟。

与其把写文档当作事后补救，不如借助 Claude（通过 Claude Code、API 或网页界面）来引导出一套骨架文档系统，并建立一份显式的文档到代码的追踪矩阵（Doc-to-Code Tracking Matrix）。

本指南将带你走过一个系统化的方法：

• 从原始代码库结构中架构出一套清晰的文档骨架。
• 生成代码到文档的映射矩阵（Code-to-Doc Mapping Matrix），追踪哪些文件负责哪些文档页面。
• 使用定制化的 prompt 运行自动化的「文档缺口」审计（Doc-Gap Audits）。
• 将文档检查集成到 PR 工作流中。

1. 为什么先做「骨架」？

当开发者试图一次性为整个平台编写文档时，往往会因为范围过大而陷入瘫痪。骨架优先的方法将结构与内容drafting分离：

骨架：目录结构、文件路径、用途说明，以及每个页面所需的小节。

内容：实际的解释说明、代码片段和图表，渐进式填充。

尽早确立骨架后，缺失的文档会变成一个可见的空白（空章节或未链接的追踪项），而不是一个不可见的未知。

2. 步骤 1：引导骨架架构

要创建一个干净的骨架，需要将项目结构或目录树喂给 Claude，并使用一条专门设计的 prompt 来应用标准技术写作框架（如 Diátaxis——教程、How-To 指南、技术参考、解释说明）。

Prompt 1：文档架构生成器

You are a Principal Technical Writer analyzing a codebase to design a comprehensive documentation skeleton.

Here is the file structure and brief description of our application:
<codebase_tree>
[PASTE YOUR TREE OR DIR STRUCTURE HERE]
</codebase_tree>

Project Description:
[INSERT BRIEF DESCRIPTION OF THE APP / STACK]

Task:
1. Propose a `docs/` directory structure using the Diátaxis framework:
   - Getting Started / Tutorials
   - How-To Guides
   - Architecture & Concepts
   - Reference (API, CLI, Config)
2. For every proposed markdown file, provide:
   - Target file path (e.g., `docs/reference/config-flags.md`)
   - Objective statement (1 sentence)
   - Outline (H2/H3 headers)
   - Status (e.g., `[ ] Unwritten`, `[ ] Draft`, `[x] Complete`)

Format the response as clean Markdown ready to be placed in `docs/README.md`.

运行此 prompt 后，你将得到一份结构化的 docs/ 目录布局，每份文件都有用途说明和待办状态。接下来可以将其保存为 docs/README.md，作为整个文档站的入口索引。

3. 步骤 2：生成代码到文档的映射矩阵

骨架搭建完毕后，下一步是建立一份矩阵，追踪哪些源文件映射到哪些文档页面。这在代码频繁变动时尤为重要——有了这份矩阵，你就能快速识别哪些文档会因为某个代码改动而需要更新。

Prompt 2：代码到文档映射生成器

You are a Senior Software Engineer who also excels at technical writing.

Here is our codebase structure:
<codebase_tree>
[PASTE YOUR PROJECT TREE HERE]
</codebase_tree>

Here is our documentation structure:
<doc_tree>
[PASTE YOUR DOCS TREE HERE]
</doc_tree>

Task:
1. Create a markdown table mapping each source file to its corresponding doc page(s).
2. For each mapping, note:
   - Source file path
   - Doc page(s) it impacts
   - Relationship type: "defines", "configures", "example for", "references"
   - Change risk: Low / Medium / High (how likely this file changes and breaks docs)
3. Sort by Change Risk (High first).

Output format: a markdown table, then a summary paragraph.

该矩阵可直接放入 docs/tracking-matrix.md，作为 living document 追踪代码与文档之间的关联。

4. 步骤 3：运行自动化的文档缺口审计

有了骨架和映射矩阵，现在可以用 Claude 来审计文档覆盖的缺口。这个步骤可以定期运行，也可以在 PR 层面自动触发。

Prompt 3：Doc-Gap 审计器

You are a Principal Technical Writer performing a doc-gap audit.

## Context
Our codebase has these source files:
<codebase_tree>
[PASTE SOURCE FILE LIST]
</codebase_tree>

Our current documentation covers:
<doc_tree>
[PASTE CURRENT DOC TREE]
</doc_tree>

Our code-to-doc mapping:
<code_doc_mapping>
[PASTE MAPPING TABLE FROM PREVIOUS STEP]
</code_doc_mapping>

## Task
1. Identify gaps: source files with no corresponding documentation.
2. Identify stale docs: doc pages with no corresponding source files (or that reference deleted/moved files).
3. For each gap, suggest:
   - A target doc path
   - A one-line objective
   - Suggested section headers (H2/H3)
   - Priority: Critical / High / Medium / Low
4. For each stale doc, flag as `[ ] Needs Update` or `[ ] Deprecate`.

Output: a prioritized gap report in markdown.

审计结果可直接转化为 issue 或 PR 任务项，优先级最高的缺口可以立即着手填补。

5. 步骤 4：将文档检查集成到 PR 工作流

纸上谈兵再好，不落地到开发流程中也没用。以下是将文档检查集成到 CI/PR 的几种方式：

方案 A：PR Comment Bot

在 PR 阶段，用 Claude 分析改动的文件列表，并自动评论提醒需要更新的文档：

Analyze this PR diff and suggest which docs need updating:

<PR_DIFF>
[PASTE DIFF HERE]
</PR_DIFF>

Based on the code-to-doc mapping matrix, list:
1. Docs that may need updates (with file paths and reason)
2. New docs that should be written (with suggested paths)
3. Any stale docs that should be deprecated

方案 B：CI 检查脚本

#!/bin/bash
# .github/scripts/doc-check.sh

# 收集 PR 改动的文件
CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)

# 调用 Claude API 审计文档缺口
claude --prompt "Doc-gap audit for these changed files:
$CHANGED_FILES

Code-to-doc mapping:
$(cat docs/tracking-matrix.md)"

# 如果有高风险缺口，CI 失败
if [ $? -ne 0 ]; then
  echo "Doc-gap check failed"
  exit 1
fi

方案 C：Pre-commit Hook

对于破坏性变更（删除文件、修改 API 签名等），可以在 pre-commit 阶段强制要求关联文档必须同步更新。

6. 维护：让文档骨架保持活力

骨架搭建完成后，关键在于持续维护。以下是几个保持骨架活力的策略：

定期审计：每两周运行一次 Doc-Gap 审计，及时发现新出现的缺口。

追踪矩阵自动化：每次有文件新增或删除时，更新追踪矩阵。可以写一个简单的脚本自动从 docs/ 和 src/ 目录生成矩阵的初稿，再由人工review。

PR 强制检查：在高变更风险的代码上强制要求关联文档同步更新（通过 CI 或 PR 检查）。

文档状态仪表盘：在 docs/README.md 或独立的 dashboard 中展示各文档的编写状态（[ ] Unwritten、[ ] Draft、[x] Complete），让文档覆盖率一目了然。

7. 总结

骨架优先的文档方法论不是一次性项目，而是一种持续的系统化实践：

1. 建立骨架：用 Diátaxis 框架设计 docs/ 结构，让所有缺失的文档变成可见的空白。
2. 追踪映射：维护一份代码到文档的映射矩阵，掌握每次代码改动的影响范围。
3. 定期审计：用定制化 prompt 运行 Doc-Gap 审计，持续发现并修复缺口。
4. 集成工作流：将文档检查嵌入 PR 和 CI，确保文档与代码始终同步。

通过这四个步骤，你将从「文档总是跟不上代码」切换到「文档缺口一目了然、每次改动可追踪」的状态——让文档从被遗忘的负担，变成团队可以真正依赖的资产。