夜雨聆风上周有个朋友在群里抱怨：Claude Code 写个工具函数又快又准，但让它重构一个 5000 行的旧模块，改了三遍都有 bug，最后只能自己上手重写。另一个朋友回复说试试 Copilot Agent Mode 或者换个更强的模型。问题就出在这里。
大多数人遇到 AI 编程工具在复杂场景下表现不佳时，第一反应是换工具、换模型、换 prompt。但真正的问题可能根本不在这三个选项里。
流行观点：选对工具就够了
打开任何一个 AI 编程工具的讨论区，最高频的问题是：Claude Code 和 Cursor 哪个更强？GPT-5.6 和 Claude Opus 5 谁的代码能力更好？要不要升级到最新版？
这种讨论隐含一个假设：工具足够强的时候，什么代码库都能改好。
但 Claude Code 最近的几个版本更新暴露了另一个方向。v2.1.187 新增了 sandbox.credentials 配置，阻止沙盒内命令读取凭证文件和秘密环境变量；同时增加了 org-configured model restrictions，允许组织级限制模型选择。v2.1.181 新增了 /config 语法从 prompt 直接设置任何配置项，以及 sandbox.allowAppleEvents 沙盒选项。GitHub Copilot 也推出了 Agent Mode，允许 AI 自主执行跨文件的多步编辑。
这些不是"模型更强了"的更新。它们是"工具开始处理真实项目的复杂性和安全风险"的更新。
当工具厂商开始花精力做凭证隔离、组织级策略、跨文件自主编辑时，说明他们已经把 AI 编程工具当成 Agent 在做了——一个能在你的代码库里自主导航、理解依赖、执行修改的代理。而 Agent 要能在一个代码库里安全工作，对代码库本身是有要求的。
大多数代码库不是给 Agent 设计的
我们写代码的习惯，是在"人类逐行阅读和修改"的前提下形成的。人类能容忍什么？
模糊的模块边界。看到一个函数不知道它依赖什么，人可以去翻调用链，可以读上下文，可以凭经验猜。
没有测试的遗留代码。人改完之后手动点一遍核心路径，大概验证一下。
隐含的接口契约。人可以通过阅读文档、看 git log、甚至直接问同事来理解一个模块的预期行为。
Agent 不行。它需要清晰的模块边界才能确定修改的影响范围，需要自动化测试才能验证修改没有破坏现有功能，需要显式的接口契约才能理解模块之间的协作规则。
没有这些的代码库，对 Agent 来说就像一个没有路标、没有地图、没有交通规则的城市——你可以走，但大概率会走错。
Agent-ready 代码库的 6 个标准
判断你的代码库能不能让 AI Agent 高效工作，不看用了什么工具，看这 6 件事：
标准一：每个模块有明确的输入输出契约
你的模块（无论是函数、类还是服务）是否有明确的类型标注、参数说明和返回值定义？没有类型标注的 Python 函数，Agent 无法确定该传什么参数、会返回什么类型。没有接口定义的 Go 结构体，Agent 不确定这个模块对外暴露了什么。
失败场景：让 Agent 修改一个没有类型标注的 Python 函数，它不知道调用方传的是 str 还是 int，改完后类型不兼容，运行时才发现。
验收方法：运行类型检查工具（mypy、pyright、tsc --noEmit），零 error 通过。
标准二：关键路径有自动化测试覆盖
Agent 修改代码后需要一种自动化的方式确认"没改坏东西"。这就是测试的作用。没有测试的代码库，Agent 每次修改都是盲改——它不知道自己破坏了什么。
失败场景：Agent 修改了一个被 20 个地方调用的核心函数，没有测试覆盖，改完后上线才发现有 3 个调用方的行为被意外改变。
验收方法：对要交给 Agent 修改的模块，关键业务逻辑的测试覆盖率（行覆盖或分支覆盖）不低于 80%，且测试能在 30 秒内跑完。
标准三：依赖关系可追溯
Agent 需要知道改一个文件会影响哪些其他文件。这意味着依赖关系应该是显式的：import 语句、依赖注入、模块间的接口定义。如果依赖是隐式的（全局变量、运行时动态加载、配置驱动的分支），Agent 无法安全地评估修改影响。
失败场景：一个模块通过全局配置对象隐式依赖另一个模块的状态，Agent 修改配置结构时不知道会影响谁，测试也没覆盖这个隐式依赖。
验收方法：用依赖分析工具（如 pydeps、madge）生成依赖图，确认每个模块的依赖都是显式声明的 import，不存在隐式的全局状态共享。
标准四：代码库有可执行的上下文文档
Agent 读代码的速度很快，但它不知道"这个项目的惯例是什么"。命名规范？错误处理方式？日志格式？这些人类通过阅读大量代码能慢慢掌握的上下文，如果有一份简短的可执行文档说明，Agent 的输出质量会大幅提升。
失败场景：Agent 在一个用 pytest 的项目里写了 unittest 风格的测试，或者在一个用 async/await 的项目里写了同步代码——不是它不会，是它不知道项目的惯例。
验收方法：项目根目录下有一份 CLAUDE.md 或 .cursorrules 或 AGENTS.md 文件，包含项目的技术栈、代码风格、测试框架、常用命令。新建文件时 Agent 能正确遵循项目惯例。
标准五：变更影响范围可预估
好的代码库能让修改者（包括 Agent）在动手之前就知道这次改动的影响范围。这要求模块之间有清晰的职责划分，每个模块只做一件事，模块间的交互通过明确的接口。
失败场景：让 Agent "把这个函数改成分页查询"，结果这个函数被 15 个调用方使用，每个调用方都有不同的上下文，Agent 需要同时改 16 个文件才能完成——这不是 Agent 的错，是模块职责不清晰的错。
验收方法：任意单个函数的直接调用方不超过 5 个；任意单个模块的直接依赖模块不超过 8 个。
标准六：有安全的执行沙盒
这是 Claude Code v2.1.187 新增 sandbox.credentials 的意义所在。Agent 在你的代码库里执行命令时，不应该能读到你的 AWS 密钥、数据库密码、API Token。好的代码库应该配合工具的安全沙盒——敏感配置通过环境变量或专门的 secrets 管理工具注入，而不是写在代码或配置文件中。
失败场景：Agent 在沙盒中执行 npm install，不小心读到了 .env 文件里的数据库密码，然后在生成的代码里把它硬编码了进去。
验收方法：敏感凭证不存储在代码库中（不在 .gitignore 之外的文件里出现密钥、Token）；启用工具的沙盒模式（如 Claude Code 的 sandbox）；沙盒模式下执行一组常规任务，确认无法读取敏感环境变量和配置文件。
验收标准：怎么知道代码库真的 Agent-ready 了
把上面 6 个标准变成一个 checklist，逐项验收：
类型检查零 error 通过 → 标准一过关
关键路径测试覆盖率 80%+ 且 30 秒内跑完 → 标准二过关
依赖图无隐式依赖 → 标准三过关
项目根目录有 Agent 上下文文件且新建文件能遵循惯例 → 标准四过关
单函数调用方 ≤5，单模块依赖 ≤8 → 标准五过关
沙盒模式下常规任务不泄露凭证 → 标准六过关
6 项全部过关，你的代码库就达到了 Agent-ready 的基线。这时候再把 Claude Code 或 Copilot Agent Mode 请进来，它改代码的准确率会有肉眼可见的提升。
边界：不是所有代码都值得 Agent-ready
有些场景不值得做这些准备。一次性脚本、原型验证、个人学习笔记——这些代码的生命周期可能只有几天，花几个小时写类型标注和测试不划算。Agent-ready 的投入适合那些需要长期维护、有多人协作、会反复被修改的代码库。
反过来，如果你的代码库已经有上述 6 项中的一部分（比如已经有类型标注和测试），那补齐剩下的几项可能只需要一两天。这不是一次性的重构，而是让代码库适配下一代编程方式的必要升级。
AI 编程工具已经从 autocomplete 走到了 agent。下一步不是等更强的模型，而是让你的代码库准备好被 agent 安全地理解和修改。