让 AI 写文档、建 Skill,算知识沉淀吗?

最近看招聘 JD，我看到一个要求：使用 coding agent 时，要能够沉淀知识。

我开始对照自己的做法：让 AI 写文档、整理 Jira task，连 Git commit 和 GitLab MR 的说明也交给 agent。过去嫌麻烦、不愿细写的背景和验证步骤，现在往往能记录得更完整。我还会把有用的操作做成 Skill，寻找合适的 MCP，并维护项目上下文和 Claude rules。

这些算不算知识沉淀？如果算，更专业的做法又多了什么？

我的判断是：这些已经包含知识沉淀。接下来值得补齐的是来源、适用条件、复用入口和反馈。 文档篇幅、Skill 数量和工具数量，都不足以单独证明效果。更有说服力的证据是：下次遇到类似任务，别人或新会话中的 agent 能找到这些知识，正确使用，并知道什么时候不能照搬。

我查阅了 Claude Code、Agent Skills、MCP 的官方文档，以及架构决策记录和 Google SRE 复盘资料。下面把产品机制与我的实践建议分开讨论。

1. 先看“写下来了”之后发生什么

设想一个常见场景：agent 修复了某个发布脚本，还写了一份结构完整的 MR 描述。

一个月后，同事修改相邻脚本，再次碰到同类问题。他不知道旧 MR 的编号，也不知道当时为何放弃了一个看起来更简单的方案。即使旧 MR 写了两千字，它的价值仍然难以进入这次工作。

反过来，一条很短的模块说明可能更有用：

此模块会重试外部写入。修改重试逻辑前，先读 docs/decisions/007-write-retry.md，并检查关联回归测试。该决策仅适用于已提供幂等保证的接口。

这段话把三个东西接起来了：当前修改位置、过去的决策，以及可以执行的验证。

因此，我会用四个问题判断沉淀是否有效：

• 能找到吗？ 用问题关键词、模块路径或任务入口，能否找到相关记录？

• 能相信吗？ 结论是否有代码、测试、日志或已确认决策支撑？

• 能使用吗？ 是否写清前提、步骤、停止条件和成功标准？

• 能更新吗？ 环境变化后，是否有人负责修订或标记失效？

这是本文的工作判断标准，并非行业统一认证。它可以帮助我发现：自己缺的是检索入口，还是证据，或者维护机制。

2. 我现在做的事情，各自沉淀了什么

文档、Jira、commit 和 MR：保存任务背景与证据

这些记录本来就有价值。Jira 可以保留需求、验收条件和进度；commit 连接具体代码变化；MR 可以保留实现理由、评审讨论和验证结果。AI 降低了整理成本，让原本只留在脑子里的信息有机会被写下来。

不过，丰富的说明也需要核对。agent 可能把“建议执行的测试”写成“测试已通过”，把推测写成根因，或者为实现补上一套从未讨论过的设计理由。

我会让它明确区分：已观察的现象、尚未验证的假设、已执行的检查、没有执行的检查，以及待确认的决定。涉及“为什么这么选”，应以实际讨论和证据为准，不能由 AI 事后编一个合理故事。

MR 还可以保留具有长期价值的知识。若其中一项决策会持续影响后续开发，就给它一个稳定入口，例如模块文档或架构决策记录，再从 MR 链过去。小改动只保留在 MR 中也完全合理，不必每次都另写文档。

项目上下文和 rules：保存协作约定

维护上下文是一种实际的知识工作：决定当前任务需要什么信息、到哪里取，以及哪些旧信息应退出。

例如，项目采用的测试命令、特殊的目录边界、容易踩坑的兼容条件，都可以写进项目指令。Claude Code 官方文档支持用 .claude/rules/ 组织规则，并用 paths 限定适用文件；同时说明这些指令用于影响模型行为，不能替代强制约束。重要检查仍需要测试、CI 或权限机制落实。Claude Code：项目记忆与规则

这里有一个很实际的区别：

“修改接口时注意兼容性”很难执行。

“修改此接口的响应字段时，检查已登记的旧客户端契约测试；需要破坏兼容性时先提交迁移方案”更容易执行和复核。

规则最好写清适用对象、具体动作，以及关联依据。一次特殊情况，也不应直接升级成所有项目都必须遵守的规则。

Skill：保存可重复的方法

把有用的流程做成 Skill，已经在沉淀程序性知识，也就是“遇到这类任务该怎样做”。Agent Skills 官方定义允许将指令、脚本、参考材料和模板打包，并按任务需要加载。Agent Skills 官方概述

一个适合复用的 Skill，通常要说明什么时候触发、需要哪些输入、执行哪些步骤、遇到什么情况停止，以及如何判断结果合格。只把一段成功对话复制进去，可能保留了太多偶然条件。

例如，发布 Skill 如果包含目标环境检查、变更预览、执行步骤、结果验证和失败后的处理，会比“帮我发布”更有复用价值。但如果流程只成功过一次，就应保留实验状态；真正复用时继续修订。

寻找 MCP 和社区 Skill：引入外部能力与知识

这部分也有价值，但需要区分“采用工具”和“形成项目经验”。

MCP 官方定义强调连接 AI 应用与外部数据、工具和工作流。它提供访问通道；知识可以存在于它连接的 Jira、文档库或数据库中，具体 server 也可能实现记忆功能。协议本身不会自动完成知识审核、组织和维护。MCP 官方介绍

对我而言，更值得保留的是：这个工具解决了什么问题，为什么适合当前项目，怎样配置，实际有什么限制，以及替换它时要注意什么。社区 Skill 也需要检查项目路径、权限、依赖和成功标准是否适用。

这样，工具探索才逐渐转化成可复用的选型经验。

3. 更专业的做法：让不同记录承担不同责任

工程团队早就有一些适合沿用的方法，不必为了 agent 重新发明整套体系。

架构决策记录（ADR）保存“为什么”。 Michael Nygard 提出的 ADR 方法，用短文档记录背景、决定、状态和后果。后果包括收益与代价；决定被替代后，保留旧记录并指向新决定。这尤其适合那些后来者很容易推翻，却不知道原始约束的选择。

操作手册（runbook）保存“怎样做”。 比如故障排查顺序、所需权限、停止条件和恢复检查。正文可以解释原因，脚本承担稳定、重复的操作，Skill 则说明如何选择和调用这些材料。

复盘保存“哪里出了问题，以及如何减少再发生”。 Google SRE 强调记录事件、影响、原因和后续预防动作，也强调复盘有成本，需要选择触发条件。这说明知识沉淀可以有取舍：重复失败、重要事故和有长期影响的误判，值得投入更多整理工作。

测试保存“哪些行为必须成立”。 回归测试把一次错误转成可执行的检查；契约测试记录接口边界。测试不能解释全部背景，因此适合与决策记录互相链接。

这些载体没有固定的高低等级。一个短 MR 配上一项有效测试，可能已经足够；重要架构变更则需要保留更完整的决策依据。

看下面蓝色主路径：任务经验经过审核，才进入可复用材料；右侧的反馈箭头把使用结果带回审核。这张图表达的是我建议采用的工作循环，并非某个产品的自动机制。

知识经过审核和实际复用，才能持续修正，而旧材料也需要退出。

4. 用一个例子，把任务记录变成下一次能用的知识

下面是一个教学示例，未指向真实项目，也没有实测数据。

假设 agent 修改订单接口时加入自动重试。评审发现：请求超时可能发生在订单已经创建、响应尚未返回之后；再次请求有可能创建重复订单。

我会这样整理这次发现。

先保留任务证据。 Jira 写清现象和验收条件，MR 连接修改代码、复现步骤和测试结果。若只根据代码推测风险，应标为待验证，不声称已经发生过生产事故。

再记录适用条件。 对这个接口，可以写下：写入结果不确定时，不能仅凭超时就判断操作失败。自动重试需要该接口明确支持的幂等方案，例如约定好的幂等键、重复请求识别与结果返回机制。具体实现和生命周期必须由项目确认。

把指导放到修改入口。 订单模块规则提示：修改创建订单的重试逻辑前，阅读关联决策，并检查重复请求的回归用例。不要泛化成“所有 HTTP 请求都不能重试”。

让测试约束结果。 测试覆盖项目已约定的幂等行为，例如相同请求标识的重复请求不创建第二笔订单；还应检查标识冲突等项目实际规定的边界。测试在这里约束业务行为，规则帮助 agent 找到检查入口。

等流程稳定后再考虑 Skill。 如果多个任务反复需要审查写入重试，可以提炼一个流程：识别副作用，检查接口契约，寻找幂等证据，检查失败场景，再输出审查结果。单一接口的偶发补丁未必值得独立做 Skill。

同一次经验因此可以产生几种材料，但不需要重复复制全文。让任务记录链接证据，让规则链接决策，让 Skill 调用流程和测试即可。

5. 保存很多知识，如何避免上下文越来越乱

长期保存的材料可以很丰富；单次任务需要加载的内容则应经过选择。

Anthropic 的上下文工程文章讨论了精简高价值上下文、保留路径等轻量引用，以及运行时按需检索。它也提醒，过多或含糊的工具会增加选择困难。我的实践建议是：常驻入口提供少量约定和材料位置，细节按任务加载。Effective context engineering for AI agents

注意下图中间的窄入口：资料保存量可以增长，但进入当前任务的信息需要符合相关性和有效性条件。右侧保留“执行中按需补读”，避免把精简上下文理解成永远不读细节。

知识库可以保存很多材料，当前任务只加载相关、有效的信息，并在执行中补读。

小项目可以从一份索引开始，按“修改订单”“排查发布失败”等任务列出资料路径和一句适用说明。关键词检索、目录结构与明确链接，通常值得先试。若跨仓库、跨系统检索已经困难，再考虑 RAG 等检索方式。RAG 是检索相关材料并提供给模型的方法，也需要处理权限、来源、更新和过期问题。

还需要指定每类知识的主要维护位置。例如，接口行为以代码和契约测试为依据，当前决策以有效 ADR 为依据，任务历史留在 Jira 和 MR，规则只提供必要指导与链接。这个安排由团队约定，不是工具自动保证的。

对于长期使用的材料，我还会补上维护者、适用版本和最近核验日期，并约定什么变化需要重新检查。例如，接口契约改变后复核相关决策，发布命令改变后更新操作手册。个人项目的维护者可以就是自己，不必为此新增复杂流程。

保留历史与删除无效内容可以同时进行：旧决策可标记为已替代，失效操作退出当前入口，重复指令合并。没有来源的自动总结应先作为待核查笔记，不要立刻变成团队规则。

6. 怎样证明这些知识有用

最直接的检查，是用新会话或让不熟悉该任务的同事尝试一次类似任务。

我会观察：能否找到相关材料，能否说明适用条件，是否避免了原来的错误，以及输出是否达到验收标准。如果必须由我不断口头提醒，说明入口或流程还需要改进。

更系统的做法，是保留少量代表性任务作为评估集。Anthropic 的 agent 评估文章讨论了代码检查、模型评审和人工评审；针对 coding agent，还强调清晰任务、稳定环境和结果测试。Demystifying evals for AI agents

这里要分清两件事：回归测试判断业务行为是否正确；agent 评估还可以判断它是否找到资料、选对流程，并减少重复的人为纠正。代码正确，不一定说明知识入口有效。

如果想比较改进前后表现，应尽量固定模型版本、任务、环境和权限，并多次运行。可记录成功率、人工纠正次数、耗时与成本。模型输出有波动，一次成功只能提供线索；没有测量，就不应写“效率提升了多少”。

个人使用不必一开始就建设评估平台。一次跨会话复用，加上结果核对，已经能发现许多问题。

7. 下一次任务结束后，我会多做这几步

我会优先选择值得整理的变化：修复重复错误，发现难以从代码看出的限制，做出重要取舍，或者形成稳定流程。普通小改动保留清楚的任务说明即可。

对于值得整理的任务，可以给 agent 这样的收尾要求：

请检查本次任务是否产生了值得长期保存的知识。优先考虑反复出现的问题、重要决策和稳定流程。对于候选知识，请列出：- 结论、适用条件，以及已知的不适用情况。- 来源：代码、测试、日志或已确认的讨论。- 未验证的假设，不要补写不存在的证据。- 建议维护位置：任务记录、决策、操作手册、规则、Skill 或测试。- 与现有材料的重复或冲突，以及需要更新的入口。- 适用版本、维护者，以及哪些变化需要重新核验。- 下一次怎样检查它是否仍然有效。先提出可审核的修改。仅在已授权范围内更新；待确认决定不得写成团队规定。如果没有长期价值，说明理由即可。

随后由我审核事实、推广范围和维护位置。审核通过后，再通过一次后续任务检查复用效果。这段提示只提供整理结构，不能替代审核。

8. 回到 JD：我会怎样描述自己的能力

如果招聘方希望看到的是团队可以复用的 AI 编程实践，那么我现有的文档、规则和 Skill 已经是有价值的基础。更有说服力的表达，可以是：

我用 coding agent 整理任务背景和验证证据，把长期有效的约定维护为项目规则，把重复流程提炼成 Skill，并通过关联测试和后续任务检查这些材料是否可复用。

这段话适合作为能力方向。简历和面试里仍应只描述实际完成的部分，最好带一个能够展示的例子：原问题是什么，留下了哪些材料，别人如何找到，复用时避免了什么错误。如果还没有效果数据，就说明正在建立验证方法。

对我来说，下一步最值得做的，是选一个最近反复出现的问题，把已有 MR、规则或 Skill 接起来，再让新会话真正使用一次。这样既能检查知识是否留下来了，也能发现它是否准确、是否容易找到，以及维护成本是否值得。

参考资料

资料核查日期：2026 年 10 月 11 日。产品文档会更新，具体加载行为应结合所用版本确认。本文的整理标准、教学示例和实施建议为作者分析，并非官方统一流程。

• Claude Code：How Claude remembers your project

• Agent Skills 官方概述

• MCP：What is the Model Context Protocol?

• Michael Nygard：Documenting Architecture Decisions

• Google SRE：Postmortem Culture — Learning from Failure

• Anthropic：Effective context engineering for AI agents

• Anthropic：Demystifying evals for AI agents