⭐ Terrain 开源地址：https://github.com/sopaco/terrain（MIT License）· 给 AI Agent 铺好「地图 + 道路 + 路标」的高性能工程环境开源方案，欢迎 Star / Issue

每个做过三年以上项目的开发者，大概都经历过同一种「背叛感」：

你打开一份架构文档，文档里写的还是三年前的模块划分。你问团队里资历最深的同事，他说「文档早过时了，你看代码吧」。你开始看代码，看了两小时，才在某个角落发现真正的主流程。

文档不是没有，是永远比代码慢半拍。 而代码又是唯一不会说谎的真相——只是它太啰嗦了。

在 AI Coding 时代，这个问题从「让人烦」升级成了「让 Agent 废」。Agent 读到的文档是旧的，它对整个项目的判断就是错的；它不信文档、直接去读代码，又烧掉大量 token 和时间。文档漂移，正在成为 AI 工程化的隐性成本。

Terrain 给出的答案很直接：

不维护文档，而是让知识从代码里自动「长」出来，并且永远追踪代码的变化。

---

一座「知识工厂」：从源码到知识契约的全自动流水线

Terrain 的核心，是一条把「Git 仓库」加工成「知识资产」的流水线。注册一个仓库后，它自动完成以下环节：

这条流水线最大的特点，是几乎所有环节都围绕「代码」而不是「人的记忆」运转：

• 扫描：采集仓库结构、Git 元数据，必要时导入 OpenAPI 规范——先把项目的「骨架」摸清；
• 打包：用 repomix 把源码打包成便于 grep 的索引包（agent/repomix.md），作为 Agent 按需检索的原材料；
• 生成：产出人类可读的 C4 架构文档（human/），以及 Agent 直接可读的高度压缩上下文（agent/context.md）；
• 保鲜：追踪 Git HEAD 与工作区状态，为每份资产计算「新鲜度评分」。

一句话总结：你只负责写代码，文档的事交给流水线。

---

双轨产物：同一条流水线，喂饱两类读者

这份流水线最聪明的地方，是它把「给人看的」和「给 Agent 读的」放进了同一个 .terrain/ 目录，由同一套逻辑产出，而不是各自维护：

产物	给谁	形态
human/	人类开发者	叙述式 C4 文档（概述、架构、工作流、模块深挖、边界接口、数据库概览），带 Mermaid 图
agent/context.md	AI Agent	结构化宏观上下文，控制在 14 KiB 以内，进仓库先读它
agent/repomix.md	AI Agent	可 grep 的源码包，按需切片读取，避免全量加载
knowledge/	人与 Agent	业务词汇表、团队内部约定

给 Agent 的不只是「文档」，而是一套分级的知识访问模型。

无论你接进来的是 Claude Code、Codex，还是最近大火的 DeepSeek Harness（DSH），读到的都是这同一套三层知识——这正是「知识契约」能跨 Agent 通用的基础。

Agent 消费这套知识时，遵循「宏观 → 中观 → 微观」的三层检索：

• 宏观（Macro）：先预载 context.md，掌握模块划分与系统边界；
• 中观（Meso）：按需搜索 human/、knowledge/ 文档，补齐具体模块细节；
• 微观（Micro）：最后才用 grep-pack 到 repomix.md 源码包里精确切片。

三层模型的意义在于 成本与准确度的平衡：不该把整份代码塞进上下文，但也不该让 Agent 在信息真空中猜。先看地图，再找街道，最后才进具体那栋楼。

当不同来源互相矛盾时，Terrain 还给 Agent 定了一条明确的信任优先级：repomix 源码 > CodeGraph 符号图 > context.md > human 文档。宁可相信代码，也不要相信二手描述。

---

保鲜：比「生成」更值钱的，是「让文档不腐」

很多工具都能「生成文档」，Terrain 真正拉开差距的，是生成之后的保鲜机制：

• 增量更新 —— 代码变了，只重算变化的部分，而不是全量重跑整个知识库；
• 新鲜度评分 —— 追踪 Git HEAD 与工作区脏状态，为每份资产打分。分数低的资产，Agent 和开发者都知道「这可能是旧的，要降低信任权重」；
• 可恢复流水线 —— 长任务的中间研究产物会持久化，中断后可以接着跑，而不是从头再来。

打个比方：传统文档维护是「每隔半年人工校对一遍」，Terrain 是「每次提交都自动校对被改动的那一页」。文档的时效性，从「月」级别压缩到了「提交」级别。

---

这对团队意味着什么？

把「知识跟着代码走」这件事落地后，几个老问题会被直接消解：

老问题	Terrain 之后
新同事上手要一周	读一遍 human/ 文档 + context.md，几小时建立全局观
架构文档永远过期	文档由代码驱动、增量更新，还有新鲜度评分兜底
业务术语各说各话	knowledge/ 词汇表，人和 Agent 用同一套语言
Agent 在仓库里瞎猜	先读 context，再按需查文档，最后才碰源码切片

代码是唯一真相，知识只是它的投影。投影过时了，就让投影跟着真相走。

---

你只需要做一件事

# 注册仓库，剩下的交给流水线
terrain init
terrain assets

然后打开桌面 App 或 CLI，就能看到一份从你的代码里长出来、且永远在保鲜的架构知识库。

🚀 开源地址：github.com/sopaco/terrain （MIT License）
⭐ 如果你也受够了「过期文档」和「慢半拍的知识」，欢迎来 Star。

---

下一篇我们会聊：如何让 Claude Code、Codex、Cursor 这些 Agent 用同一种方式读你的仓库——一份「知识契约」的威力。