Kiro 实战：让 AI 自动「记住」你的系统——知识自沉淀机制设计

在构建了由23个Java微服务组成的后端项目后，开发团队利用Kiro CLI和Multi-Agent流水线实现了样板代码的自动生成。然而，运行两个月后，一个核心问题逐渐显现：Agent的“一次性记忆”导致每次新需求都需要重新理解代码，无法复用过往的上下文信息。

原有的开发模式中，Agent仅在单次会话中了解模块的修改历史。当后续再次处理相同模块时，它无法记住之前的接口变更、表结构调整或跨服务调用关系，只能重新加载全部代码，这对于拥有数十万行代码的项目而言效率极低。团队最初尝试通过编写总结文档来弥补，但“追加式文档”在持续迭代中迅速腐烂，最终与代码事实脱节。

为了解决这一结构性矛盾，团队设计了一套“知识自沉淀机制”，核心思路是将追加式文档替换为“自修正地图”。这套机制不记录历史操作流水账，而是围绕模块的“当前状态”构建一份实时更新的、轻量级的模块知识层。

旧方案的核心问题

传统的“追加式文档”模式存在三个根本性问题：

• 信噪比低：Git已经完整记录了所有代码变更，再手动记录变更流水账是冗余行为。
• 信息缺失：代码表面无法体现“为什么这样改”以及“对全局的影响”，例如接口契约、状态机约束、锁策略等关键信息。
• 必然腐烂：追加式文档写出来后就开始过时，三个月后文档与代码通常不再是同一回事。

新方案：自修正地图的设计思路

基于“自修正地图”的核心理念，团队提出了五个设计原则：

1. 不追加历史，只修正当前状态：知识载体像地图一样，发生变更时直接修改对应的区域，而不是贴一张新纸条。
2. 按模块切分，按需加载：23个模块的知识文件彼此独立，Agent只加载当前任务涉及的模块文件。
3. 来源必须是事实源：知识更新必须基于Git diff和代码，避免LLM凭聊天记忆推测不准确的信息。
4. 坦诚对待不确定性：对于无法确认的内容，标注“待人工确认”，不编造。
5. 懒创建：不提前批量生成所有模块的知识文件，只在Agent首次触及某个模块时，依据真实的diff创建。

知识自沉淀的三步改造方案

第一步：将structure.md瘦身为“路由索引”

原有的structure.md文件包含模块树、包布局、每个模块的详情，变化频率不同的信息混在一起。改造后，它只保留几乎不变的顶层模块树和标准包布局模板，并增加一张路由索引表，包含模块名、一句话职责和详情文件路径。这个文件作为全局加载的“目录页”。

第二步：建立“模块知识层”，每模块一份，按需加载

在.kiro/steering/modules/目录下，为每个模块创建一个独立的Markdown文件。通过Kiro的frontmatter机制，Agent仅在修改对应模块时才会加载该文件：

---
inclusion: fileMatch
fileMatchPattern:'modules/order/**'
---

每份文件遵循固定的schema，包含7个字段：

• 职责
• 核心表
• 对外接口面
• 出向依赖
• 入向契约
• MQ消息
• 关键业务规则

这个schema是“写入契约”，确保无论是Agent还是人工更新，都知道往哪个槽位填写内容。

第三步：通过“沉淀知识”Hook闭合循环

构建一个userTriggered类型的Hook。开发完成后，在Kiro面板点击“沉淀模块知识”按钮，Agent自动执行以下步骤：

1. 通过git diff origin/master...HEAD获取变更文件，并按模块归类。
2. 对于每个受影响模块：若知识文件不存在则懒创建；然后读取diff和相关代码，按照schema就地更新对应的字段。
3. 只更新发生变化的字段，不重写未变部分，不追加流水账。
4. 对于无法确认的内容，标注“待人工确认”。
5. 更新路由索引，并输出简短的复核报告。

实测效果显示，这套机制不仅在开发完成后自动沉淀了模块知识，还顺带发现了代码中隐含的bug。

机制的生命周期与适用边界

这套机制不会过期的原因在于：

• 来源始终是事实源：每次都从Git diff和代码中蒸馏信息，不依赖任何人的记忆。
• 就地修正不追加：知识文件永远反映“当下”的模块状态，不堆积历史噪音。
• 按需加载不稀释：23个模块的文件各自独立，Agent只加载当前任务所需的部分。
• 懒创建不造假：未触及的模块知识文件保持空状态，诚实反映事实。

随着开发的持续进行，这份“地图”会越来越完整，而无需任何人额外维护文档。开发行为本身即成为维护知识的主要方式。

后续计划

团队计划将L2（架构决策记录/ADR）也接入这套机制，让Agent在识别到非显然的决策时，自动追加对应的架构决策记录。

本文信息基于原始资料记录时的状态，版本、价格、接口和开放范围可能继续变化，实际情况以使用时的官方文档为准。