如果你的团队正在用 AI 编程助手或构建 Agent，这四条原则能直接帮你减少 Agent 的「猜错」和「瞎改」，从代码结构层面提升自动化效率。做工程基建或维护大型代码库的开发者，建议对照检查自己的仓库。
Lee Robinson 分享了四条让代码库更适配 AI Agent 的原则：源码必须是真相或提供可编程访问路径（如 MCP/CLI），Agent 需能通过类型、测试、Linter 自检，AGENTS.md 应精简只写项目特有信息而非通用常识，以及通过自动化实现持续改进。他以 Cursor 官网从 CMS 迁回 Markdown 为例，说明移除抽象层后 Agent 效率显著提升。这些原则旨在降低 Agent 的认知与验证成本，让 token 和人力聚焦于产品价值。
Lee Robinson 分享了四条「Agent 友好型代码库」原则：把信息放进代码、让 Agent 能自检、能查文档、能自动化巡检 一、源码必须是真相，或有一条 Agent 能走通的路径 内容要么...
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 @leerob 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. For example, if marketing site content is actually stored in a CMS, you need to either delete the CMS and move that content into code, or make the CMS legible through and MCP, CLI, or skill: leerob.com/agents 2. Agents need to be able to verify their work. This includes but is not limited to: using a typed language, having high-quality and fast tests, having a well-configured linter: x.com/leerob/status/… 3. You need to have a concise and effective AGENTS.md file, which is included in every message to your agent. Models are quite good now, so some things you can omit as the models know them. You don’t need to say the tests live inside /tests for example. It’s worth asking the models to find things in your codebase and making sure they’re named what the models might expect, otherwise consider refactoring: cursor.com/learn/customiz… 4. Set up automations which give you suggestions for refactoring code, catching security issues which may have slipped through code review, and optionally continuous documentation of the codebase. You can effectively create a self-driving codebase which gets better while you sleep: cursor.com/blog/security-… 🔗 View Quoted Tweet 💬 0 🔄 0 ❤️ 2 👀 319 ⚡