Claude Code 知识沉淀：创建可复用结构化文档

这份文档给谁读

给人读的文档求好读，给 AI 读的文档求好定位。模型不会像人那样先翻目录再挑着看；它通常把整份文件读进上下文，然后靠标题、列表、表格判断哪一段和当前任务有关。

判断标准因此变了：结构清晰压倒文采。三百字的流畅叙述，不如三行带小标题的条目——后者能被准确切分、准确引用。

由此得出三条设计原则。对机器友好：关键信息用表格或清单，能写成「字段：值」的，就别写成一整句话。方便人维护：同一个事实只出现一处，其他位置引用它，改起来只需动一个地方。够用就行：粗糙但当天记下的版本，价值高于三个月后精心整理的版本，因为后者多半不会发生。

为什么用纯文本

标题分级、有序无序列表、表格、代码块，这几样就是全部需要的语法。好处很实际：模型看标题就知道这段讲什么，不必读完全文；层级用 # 的数量表达，不会出现「这是标题还是正文」的歧义；纯文本能被版本管理工具记录，改动可回退，谁改的、何时改的都留痕。

排版软件里的加粗、缩进、批注、页眉，传到模型那里要么丢失，要么变成一堆无意义标记。把知识存进这种格式，等于给自己加一层损耗。

骨架：六个分区

一份知识文档按这个顺序排，基本不会漏：

# 文档名
**最后核实：** YYYY-MM-DD
**什么时候用：** 一句话

## 1. 背景
## 2. 关键事实（表格优先）
## 3. 步骤（有序列表）
## 4. 范例
## 5. 禁止事项
## 6. 更新记录

第六区最容易被省掉，却最有用。写上「哪天改了什么、为什么改」，三个月后的你不用重新推理。

每一格都按可复用的标准写

表格和清单只是外壳，真正决定文档能不能用起来的，是每一格里的写法。日期统一成 YYYY-MM-DD，不要出现「上个月」「近期」这类相对时间；金额写清币种和是否含税；同一个事实只在唯一的位置维护，别处只写「见第 3 节」，不要复制一份新的。标题尽量用名词短语，避免「其他」「杂项」「相关」这类指向不明的词——模型遇到它们只能整段跳过，人也会跳过。表格一行只回答一个问题，把两个问题塞进一行，后续引用一定出错。空格也别留空：写「暂无」或「不适用」，比空白更能说明是「没有」还是「忘了填」。这套字段约定和结构化输出的思路一致：先定槽位，再填内容，最后才谈措辞。

模板一：业务知识

# 产品知识
**最后核实：** 2026-11-01

## 一句话介绍
[产品] 为 [谁] 解决 [什么问题]。

## 目标用户
| 客户类型 | 典型情况 | 最头疼的事 |
|---|---|---|
| A | … | … |
| B | … | … |

## 常见问题
**Q：** …
**A：** …

## 不能说的话
- 不承诺尚未上线的功能
- 价格一律以报价单为准，本文不写具体数字

注意最后一段。给 AI 划禁区，比给它讲十遍「要专业」管用：写清不能承诺什么、哪些数字不能写，模型在生成时就会主动绕开。

模板二：任务手册

# 月度经营会材料
**什么时候用：** 每月末的周五之前

## 需要的材料
- 当月订单明细（从后台导出，口径：含退款）
- 上月的成稿（作对比基线）

## 步骤
1. 导出数据，按 `YYYY-MM` 命名
2. 让 AI 算环比、列出异常项，附原始行号
3. 按上月结构成稿
4. 人工核对每个数字
5. 定稿分发

## 提示词
> 这是本月订单表，列为……请计算环比，并把异常项单列，
> 每条注明依据哪几行。算不出来的写「数据未提供」。

## 质量标准
- 数字全部人工复核过
- 有对比，不只有本期

文档失修的前兆

文档失修通常有前兆：新人宁可来问你也不翻文档，多半是只写了结论、没写判断依据；顶部日期很新而内容过期，是改正文时忘了回填。对应的处理都简单——给关键步骤补一句「为什么这样做」，把日期更新当成发布动作的一部分。

写完先过三道自检

不用找人评审，自己回答三个问题就能筛掉大半毛病：

1. 换个人能不能照做？ 把文档给没做过这件事的同事，看他在哪一步停下来提问；停下的地方，就是步骤缺了细节。
2. 关键数字会不会变？ 会变的价格、时效、额度只写去处、不写死值，例如「以当日报价单为准」，文档就不必跟着每次调价重写。
3. 出现分歧以哪句为准？ 同一个事实只留一个权威来源，其他文件用一行说明指过去；两处各写一遍，迟早改漏一处。

命名也顺手定下来：文件名用「主题-用途」的短名，全小写、用连字符，比如 product-facts.md、monthly-report.md；版本不靠 v2、最终版 这类后缀区分，改动记在更新记录里。三个月后回来看，只有这类名字还能一眼认出内容。

今天就能动笔

动笔不要从目录开始。新建 kb/first.md，挑今天做过、以后还会再做的一件事，写清步骤、卡点与提示词，下次做同类事之前先打开它。提示词的固定写法可参考提示词模板。文档写好了，接着是让它进入工作流：让 AI 自动读取知识库。