⭐Terrain 开源地址https://github.com/sopaco/terrainMIT License· 给 AI Agent 铺好「地图 道路 路标」的高性能工程环境开源方案欢迎 Star / Issue每个做过三年以上项目的开发者大概都经历过同一种「背叛感」你打开一份架构文档文档里写的还是三年前的模块划分。你问团队里资历最深的同事他说「文档早过时了你看代码吧」。你开始看代码看了两小时才在某个角落发现真正的主流程。文档不是没有是永远比代码慢半拍。而代码又是唯一不会说谎的真相——只是它太啰嗦了。在 AI Coding 时代这个问题从「让人烦」升级成了「让 Agent 废」。Agent 读到的文档是旧的它对整个项目的判断就是错的它不信文档、直接去读代码又烧掉大量 token 和时间。文档漂移正在成为 AI 工程化的隐性成本。Terrain 给出的答案很直接不维护文档而是让知识从代码里自动「长」出来并且永远追踪代码的变化。一座「知识工厂」从源码到知识契约的全自动流水线Terrain 的核心是一条把「Git 仓库」加工成「知识资产」的流水线。注册一个仓库后它自动完成以下环节Git 仓库(唯一真相)① 扫描结构 · Git 元数据 · OpenAPI② 打包repomix 源码索引③ 生成上下文agent/context.md④ 生成文档human/ C4 文档⑤ 保鲜追踪freshness 评分 知识资产.terrain/这条流水线最大的特点是几乎所有环节都围绕「代码」而不是「人的记忆」运转扫描采集仓库结构、Git 元数据必要时导入 OpenAPI 规范——先把项目的「骨架」摸清打包用 repomix 把源码打包成便于 grep 的索引包agent/repomix.md作为 Agent 按需检索的原材料生成产出人类可读的 C4 架构文档human/以及 Agent 直接可读的高度压缩上下文agent/context.md保鲜追踪 Git HEAD 与工作区状态为每份资产计算「新鲜度评分」。一句话总结你只负责写代码文档的事交给流水线。双轨产物同一条流水线喂饱两类读者这份流水线最聪明的地方是它把「给人看的」和「给 Agent 读的」放进了同一个.terrain/目录由同一套逻辑产出而不是各自维护产物给谁形态human/人类开发者叙述式 C4 文档概述、架构、工作流、模块深挖、边界接口、数据库概览带 Mermaid 图agent/context.mdAI Agent结构化宏观上下文控制在 14 KiB 以内进仓库先读它agent/repomix.mdAI Agent可 grep 的源码包按需切片读取避免全量加载knowledge/人与 Agent业务词汇表、团队内部约定给 Agent 的不只是「文档」而是一套分级的知识访问模型。无论你接进来的是 Claude Code、Codex还是最近大火的 DeepSeek HarnessDSH读到的都是这同一套三层知识——这正是「知识契约」能跨 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 和开发者都知道「这可能是旧的要降低信任权重」可恢复流水线—— 长任务的中间研究产物会持久化中断后可以接着跑而不是从头再来。无影响有影响代码提交 / 重构对比 Git HEAD 与工作区变化影响哪些资产?增量重生成受影响部分重算新鲜度评分消费者决策低分 → 降权 · 高分 → 信任打个比方传统文档维护是「每隔半年人工校对一遍」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 用同一种方式读你的仓库——一份「知识契约」的威力。
⭐Terrain 开源地址https://github.com/sopaco/terrainMIT License· 给 AI Agent 铺好「地图 道路 路标」的高性能工程环境开源方案欢迎 Star / Issue每个做过三年以上项目的开发者大概都经历过同一种「背叛感」你打开一份架构文档文档里写的还是三年前的模块划分。你问团队里资历最深的同事他说「文档早过时了你看代码吧」。你开始看代码看了两小时才在某个角落发现真正的主流程。文档不是没有是永远比代码慢半拍。而代码又是唯一不会说谎的真相——只是它太啰嗦了。在 AI Coding 时代这个问题从「让人烦」升级成了「让 Agent 废」。Agent 读到的文档是旧的它对整个项目的判断就是错的它不信文档、直接去读代码又烧掉大量 token 和时间。文档漂移正在成为 AI 工程化的隐性成本。Terrain 给出的答案很直接不维护文档而是让知识从代码里自动「长」出来并且永远追踪代码的变化。一座「知识工厂」从源码到知识契约的全自动流水线Terrain 的核心是一条把「Git 仓库」加工成「知识资产」的流水线。注册一个仓库后它自动完成以下环节Git 仓库(唯一真相)① 扫描结构 · Git 元数据 · OpenAPI② 打包repomix 源码索引③ 生成上下文agent/context.md④ 生成文档human/ C4 文档⑤ 保鲜追踪freshness 评分 知识资产.terrain/这条流水线最大的特点是几乎所有环节都围绕「代码」而不是「人的记忆」运转扫描采集仓库结构、Git 元数据必要时导入 OpenAPI 规范——先把项目的「骨架」摸清打包用 repomix 把源码打包成便于 grep 的索引包agent/repomix.md作为 Agent 按需检索的原材料生成产出人类可读的 C4 架构文档human/以及 Agent 直接可读的高度压缩上下文agent/context.md保鲜追踪 Git HEAD 与工作区状态为每份资产计算「新鲜度评分」。一句话总结你只负责写代码文档的事交给流水线。双轨产物同一条流水线喂饱两类读者这份流水线最聪明的地方是它把「给人看的」和「给 Agent 读的」放进了同一个.terrain/目录由同一套逻辑产出而不是各自维护产物给谁形态human/人类开发者叙述式 C4 文档概述、架构、工作流、模块深挖、边界接口、数据库概览带 Mermaid 图agent/context.mdAI Agent结构化宏观上下文控制在 14 KiB 以内进仓库先读它agent/repomix.mdAI Agent可 grep 的源码包按需切片读取避免全量加载knowledge/人与 Agent业务词汇表、团队内部约定给 Agent 的不只是「文档」而是一套分级的知识访问模型。无论你接进来的是 Claude Code、Codex还是最近大火的 DeepSeek HarnessDSH读到的都是这同一套三层知识——这正是「知识契约」能跨 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 和开发者都知道「这可能是旧的要降低信任权重」可恢复流水线—— 长任务的中间研究产物会持久化中断后可以接着跑而不是从头再来。无影响有影响代码提交 / 重构对比 Git HEAD 与工作区变化影响哪些资产?增量重生成受影响部分重算新鲜度评分消费者决策低分 → 降权 · 高分 → 信任打个比方传统文档维护是「每隔半年人工校对一遍」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 用同一种方式读你的仓库——一份「知识契约」的威力。
