Lee Robinson 分享了四条「Agent 友好型代码库」原则：把信息放进代码、让 Agent 能自检、能查文档、能自动化巡检
TL;DR · AI 摘要
Lee Robinson 提出四条「Agent 友好型代码库」原则：源码即真相或提供可编程路径、建立验证机制、编写精简 AGENTS.md、实现自动化巡检，共同降低 Agent 认知与验证成本。
核心要点
- 源码必须是真相，或通过 MCP/CLI/Skill 提供 Agent 可读路径，否则 Agent 只能依赖猜测或人工口述。
- 构建类型系统、快速测试和 Linter 组成的验证闭环，让 Agent 能自检工作成果，避免‘看起来对、跑起来错’。
- AGENTS.md 应聚焦项目特有架构、命名约定和团队规则，而非重复模型已知常识，定期用 Agent 探路检验文档有效性。
结构提纲
按章节快速跳转。
- §引言
Lee Robinson 分享了四条构建 Agent 友好型代码库的核心原则，旨在降低 Agent 的认知与验证成本。
内容要么在代码中，要么通过 MCP/CLI/Skill 让 Agent 能读取，避免抽象层导致 Agent 无法访问真实数据。
通过类型系统、快速测试和 Linter 构建反馈闭环，使 Agent 能独立判断修改是否正确。
AGENTS.md 应补充代码中未体现的上下文，如架构决策、命名约定和团队规则，而非重复通用知识。
通过安全审查、漏洞扫描、依赖更新等自动化流程，让代码库在后台持续自我优化。
可读真相 → 可验证 → 补充上下文 → 自动化放大，形成代码库持续变好的闭环。
思维导图
用一张图看清主题之间的关系。
查看大纲文本（无障碍 / 无 JS 友好）
- Agent 友好型代码库四原则
- 源码即真相或可编程路径
- 内容在代码中
- 通过 MCP/CLI/Skill 访问
- Agent 自检验证机制
- 类型系统
- 快速测试
- Linter
- 精简有效的 AGENTS.md
- 项目特有架构
- 命名约定
- 团队规则
- 自动化巡检与改进
- 安全审查
- 漏洞扫描
- 依赖更新
金句 / Highlights
值得收藏与分享的关键句。
若保留 CMS 或数据库，必须为 Agent 补一条可编程访问路径（MCP 读内容、CLI 导出、Skill 描述工作流），否则 Agent 只能猜，或依赖你口述。
类型系统、快而好的测试、配置完善的 Linter 是 Agent 的感官系统，让机器能独立判断‘改对了没有’。
AGENTS.md 不是百科全书，而是人类给 Agent 的压缩上下文，应写项目特有的架构决策、命名约定和禁区。
自动化如 PR 安全评论、Vuln Hunter、Anybump 等，可在不替代人工 Code Review 的前提下，补足规模扩大后的覆盖率和一致性。
一、源码必须是真相，或有一条 Agent 能走通的路径 内容要么在代码里，要么通过 MCP / CLI / Skill 让 Agent 能读到。
@leerob 用 Cursor 官网从 CMS 迁回 Markdown + https://t.co/hhDqnw9Jjy" / X
Lee Robinson 分享了四条「Agent 友好型代码库」原则：把信息放进代码、让 Agent 能自检、能查文档、能自动化巡检 一、源码必须是真相，或有一条 Agent 能走通的路径 内容要么在代码里，要么通过 MCP / CLI / Skill 让 Agent 能读到。
用 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 和人力花在产品价值上，而不是和抽象层搏斗。
Quote
Lee Robinson
@leerob
5h
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