AI Coding

AI Coding 的目标是让模型在真实仓库中产生可运行、可验证、可审查的改动。一次完整任务通常会经过读取、定位、编辑、测试和差异审查，具体工具能力和授权方式则因产品而异。

下文用“修复用户登录后被错误重定向的 Bug”作为贯穿案例。

AI Coding 适合什么任务

最容易取得稳定结果的任务，通常有明确范围和可执行验收，例如修复能复现的 Bug、增加小功能、补测试、重复性重构和文档同步。

以下任务需要更密集的人工判断：成功标准尚不清楚的架构决策，缺少测试的大范围改写，以及会影响生产数据、账号、权限或对外服务的操作。可验证性越低，任务就越应该被拆小。

准备一个可验证的小任务

任务开始前，先写一份短契约：

目标：修复登录入口写入 session['return_to']、回调误读 session['next_path'] 的问题。
复现：访问 /login?returnTo=/settings，登录后被跳转到首页。
完成标准：新增 /settings 回跳测试和外部 URL 拒绝测试，相关测试通过，没有无关差异。
允许范围：登录路由、回调逻辑和对应测试。
禁区：不更新依赖，不改数据库，不部署。
验证：运行指定测试、全量测试和构建命令。

“帮我修一下登录”会把问题范围、正确行为和验收方式都留给模型猜测。任务契约不需要很长，但应让开发者和 Agent 可以用同一标准判断是否完成。

让 Agent 先理解仓库

编辑前先读取与任务相关的项目说明、目录结构、测试和现有实现。仓库可以在 AGENTS.md、CLAUDE.md 或自有规则文件中记录：

• 项目结构和模块边界。
• 安装、测试、构建和格式化命令。
• 命名、代码风格和文档约定。
• 不可更改的生成物、数据和外部资源。
• 完成前必须通过的质量门。

规则文件只保留跨任务稳定的约定。当前 Bug 的临时细节放在任务描述中，大日志和大文件按需读取，避免一次把整个仓库塞进上下文。详见上下文工程。

小步修改并持续验证

一次可审查的循环是：

复现故障 → 定位最小原因 → 修改少量文件
      → 运行相关测试 → 检查差异 → 决定下一步

先在旧代码上运行回归测试，确认它因为任务契约中的预期差异而失败，而非环境、夹具或错误断言。修复后让同一测试通过，二者结合才能说明测试覆盖了目标故障。局部结果通过后，再运行任务契约要求的更广检查。

当故障原因与新证据冲突时，先更新判断，再继续编辑。长计划只是当前假设，不应在报错已经证明它失效后继续照做。

用差异、测试和运行结果验收

验收时至少检查四类证据：

• 需求证据：重现步骤已经得到预期行为。
• 代码证据：差异只包含任务所需改动，没有覆盖用户的其他修改。
• 自动验证：相关测试、静态检查和构建按任务契约通过。
• 运行证据：界面、API 或完整流程在真实环境中表现正常。

工具退出成功只能证明那次调用满足了工具契约，任务完成仍要回到最初的验收标准。测试覆盖不足时，“全部通过”也可能是假成功。

前端任务需要可执行的设计上下文

“做得好看一点”没有稳定验收标准。前端任务应说明对应的设计系统、目标视口、交互状态和视觉参考，并要求截图或自动化浏览器验证。

可执行的设计文件优先记录语义映射：主文字、辅助文字、背景和边框分别使用什么 token；组内、模块和页面区块使用什么间距；按钮、输入框和弹窗有哪些状态；文案、焦点、键盘导航和动效的边界是什么。规则越接近代码中的可执行选择，多次迭代越容易保持一致。

高风险操作必须暂停

模型输出只是行动请求。删除或覆盖大量文件、安装未审查依赖、读取密钥、修改数据库、部署生产、推送代码和发送外部消息，都要根据仓库政策进行独立授权。完整控制循环见 Agent 架构基础，更系统的工作区约束见 Harness 工程。

任务失败时，保留已有工作，记录完整错误和当前差异，然后区分输入错误、环境失败、方案错误和权限拒绝。只重试暂时错误；方案已被证据否定时，缩小任务或重新规划。

把重复经验写回项目

一次纠正只解决当前任务，反复出现的问题应转成自动检查或简短规则。例如：命令总是跑错，就修正项目文档；同类回归反复出现，就补测试或 lint 规则；一个复杂流程多次验证有效，再将它沉淀为 Skill。

只写入已验证、跨任务稳定的经验。临时报错、未确认猜测和一次性偏好留在任务轨迹中，避免让项目规则随着每次对话不断膨胀。