# Lee Robinson 分享四条「Agent 友好型代码库」原则

- 来源：meng shao (@shao__meng)
- 发布时间：2026-06-02 08:42
- AIHOT 分数：64
- AIHOT 链接：https://aihot.virxact.com/items/cmpvxrm1902lvslukz7efqbl8
- 原文链接：https://x.com/shao__meng/status/2061609287684903121

## AI 摘要

Lee Robinson 分享了四条构建适合AI智能体的代码库的原则：1. 源码应为真相或提供可读路径（如将内容从CMS迁移回代码）；2. 智能体需能通过类型系统、测试和Linter验证工作；3. 维护精简有效的AGENTS.md文件，提供项目特有上下文；4. 设置自动化流程（如安全扫描）持续改进。他以Cursor官网迁移为例，该过程耗时3天，消耗344次Agent请求，花费$260，证明降低抽象层成本能带来可量化的投资回报。

## 正文

Lee Robinson 分享了四条「Agent 友好型代码库」原则：把信息放进代码、让 Agent 能自检、能查文档、能自动化巡检

一、源码必须是真相，或有一条 Agent 能走通的路径
内容要么在代码里，要么通过 MCP / CLI / Skill 让 Agent 能读到。

@leerob 用 Cursor 官网从 CMS 迁回 Markdown + 代码的案例说明--问题不是 CMS 本身，而是 抽象层在 Agent 时代成本极高。

官网迁回后的好处：
· 统一用 Git
· PR 链接即可分享
· 源码 + 编译/AI 翻译
· 对象存储 + 自研小工具
· 内容直接可见、可改

实践含义：若保留 CMS / 数据库 / 配置中心，必须为 Agent 补一条 可编程访问路径（MCP 读内容、CLI 导出、Skill 描述工作流），否则 Agent 只能猜，或依赖你口述。

二、Agent 必须能验证自己的工作
类型系统、快而好的测试、配置完善的 Linter。

Agent 会犯错；没有反馈闭环，错误只能等人眼发现。验证机制是 Agent 的 感官系统：
· 类型： 编译期约束，减少「看起来对、跑起来错」
· 测试： 可执行的规格说明；快 = Agent 能频繁试、频繁改
· Linter： 风格与常见错误的自动守门员

三点都指向同一目标--让机器能独立判断「改对了没有」。Lee 在 CMS 迁移里用 @ browser 截图对比本地与生产，也是同一思路：用可观测结果验证，而非凭感觉。

实践含义： 若测试慢、 flaky、或无类型，Agent 的迭代会停在「 plausible 但未经检验」；投资验证基础设施，等于投资 Agent 产能。

三、精简有效的 AGENTS.md
每轮对话都带上；写该写的，别写模型已知的常识。

AGENTS.md 是 人类给 Agent 的压缩上下文，不是百科全书。模型已具备通用知识（测试常在 tests/、用 npm test 等），重复只会占 token、稀释重点。

更值得写的是：
· 项目特有的架构决策、命名约定、禁区
· 「非显而易见」的入口（例如内容其实在某 CMS，需用某 CLI）
· 提交/部署/分支策略等团队规则

Lee 还强调：用 Agent 在仓库里找东西，看能否按预期找到；若 Agent 总找不到 utils/helpers/misc.ts 这类路径，说明命名/结构需要为人和 Agent 共同 refactor。

好 AGENTS.md 像 入职第一天老员工口头交代的那几件事，不是 README 复读。定期让 Agent 做「找 X、改 Y」的探路，是检验文档是否有效的低成本方法。

四、自动化：让代码库在后台自我改进
自动 refactor 建议、安全扫描、可选的持续文档化--「睡着也在变好的代码库」。

Cursor 安全 Agent 博客 给出了可落地的形态：
· Agentic Security Review：PR 级安全审查，可阻断 CI
· Vuln Hunter：扫存量代码漏洞
· Anybump：依赖漏洞自动打补丁 + 跑测试 + 开 PR
· Invariant Sentinel：每日检查安全/合规不变量是否漂移

共同架构：Webhook / PR 事件触发 → Cloud Agent + MCP 存状态、去重、统一输出 → Slack / PR 评论闭环。

这不是替代人工 Code Review，而是在 PR 量放大 5x 时补 coverage 和 consistency。静态分析 + CODEOWNERS 仍有用，但挡不住规模；Agent 自动化适合 重复、有规则、可验证 的任务（安全、依赖、文档漂移）。

实践含义： 从一条自动化开始（例如 PR 安全评论），验证噪音/召回后再加阻断、再扩到存量扫描；和第三条一样，验证机制越成熟，自动化越敢放权。

总结：四条原则的关系
1 可读的真相源 -> Agent 能读能改 -> 2 可验证 -> Agent 能自检 -> 3 AGENTS.md 补缺口 -> 4 自动化放大 -> 代码库持续变好

· 可读真相 - Agent 有材料可工作
· 可验证 - Agent 有标准判对错
· AGENTS.md - 补代码里写不下的上下文
· 自动化 - 把 1-3 固化成 24/7 流程

Lee 的 CMS 迁移（$260、344 次 Agent 请求、3 天完成）说明：在 Agent 时代，删复杂度、把信息拉回代码，ROI 可以量化。 四条原则本质是同一策略--降低 Agent 的认知与验证成本，把 token 和人力花在产品价值上，而不是和抽象层搏斗。

### 引用推文

> Lee Robinson：Some tips to help agents understand your codebase: 1. The source code either needs to be the source of truth, or have something legible as a path to the source....