Coding Agent 怎样进入一个真实项目
一句话收获：AI 先理解项目契约，再生成可审查的修改计划。
这个场景在解决什么问题
这个场景讲的是 Coding Agent（能写代码、改项目的 AI）第一次被放进一个真实项目时，它应该先干什么、再干什么。目标（goal）是展示一条完整的入口链路：先读规则、再定位代码、再形成计划、最后等人确认。观察点（observation）很关键：Coding Agent 一开始只做"只读"的理解动作，不碰任何文件。
为什么值得单独学？因为大多数人一上来就让 AI "直接改"，结果 AI 在不了解项目契约的情况下乱改一通。这个场景告诉你：真正安全的入口，是把"理解"和"动手"严格分开，中间必须隔一道人工确认。
先理清这条判断链（文字版）
这个场景的四步是严格的先后顺序，本质是"先看规则 → 再看代码 → 再写计划 → 最后才动手"：
- 先读项目的规则文件（AGENTS.md、Spec、运行命令、禁止范围），搞清楚"这个项目里什么能做、什么不能做、怎么验证"。
- 再只读地搜索相关模块、接口、状态和测试，摸清"我要改的东西到底牵动哪里"，但一个文件都不改。
- 接着生成一份修改计划，讲清楚"改什么、不改什么、有什么风险、怎么验证、怎么回滚"。
- 最后把计划交给人来确认目标、事实、边界和验收，确认通过后 Coding Agent 才开始真的修改。
这条链的核心逻辑是：理解必须完整、计划必须可审查、动手必须等人点头。
逐层详解
第 1 步：读取项目规则
原文：Coding Agent 读取 AGENTS.md、任务 Spec、运行命令和禁止范围。
白话：Coding Agent 进项目的第一件事不是急着写代码，而是把项目里那些"规矩文件"读进来——AGENTS.md（项目给 AI 定的协作规范）、任务 Spec（这次要干什么的规格说明）、怎么运行验证的命令、以及哪些事明确不能碰。先搞清楚边界，再谈干活。
类比：这就像新员工入职第一天，先领一份《员工手册》和《岗位说明书》——不先读手册就上手操作，很容易踩到公司红线。
举例：比如一个电商后台项目，AGENTS.md 里写着"禁止直接操作生产数据库、所有改动必须先跑单测"，Spec 里写着"本次只给订单列表加一个按状态筛选的只读接口"，运行命令是 npm test。Coding Agent 要先把这三样读全，才知道自己能干什么、怎么验证。
为什么重要：项目规则提供当前工作的稳定入口。也就是说，规则是那个"不管项目多乱，AI 都能站得住的第一块基石"——没有它，AI 只能瞎猜。
怎么验证（证据点）：
- 规则已读取：能明确说出读了哪些规则文件。
- 允许范围明确：能说清"这次能做/不能做"的边界。
- 验证命令明确：知道改完以后用什么命令来验证。
别踩的坑（边界）：规则写入上下文仍不是后端硬约束。意思是，规则被读进上下文、AI 也"答应遵守"了，但这只是文字层面的约束，不等于系统真的会拦住 AI 去违规——真正的硬约束还得靠权限和沙箱。
落地检查：真正边界还需权限、沙箱和测试。落地时不能只靠"AI 读懂了规则"就放心，要确认权限体系、沙箱隔离、测试这些"硬约束"真的存在。
第 2 步：只读定位
原文：AI 搜索相关模块、接口、状态与测试，不修改文件。
白话：读完规则后，AI 开始"只读地"摸清代码——搜出和这次任务相关的模块、函数接口、状态字段、还有现有测试，但一个文件都不改。这一步的目标是搞清"改这里会牵动哪里"。
类比：像装修前先"看房"——拿着户型图（规则）去现场量尺寸、看承重墙（相关模块和接口），但这时候绝不会动手砸墙，只是把影响范围摸清楚。
举例：继续上面的订单项目，AI 要加"按状态筛选"，就先去搜订单列表接口、订单状态枚举、现有的查询测试，搞清楚这个只读能力加在哪一层、会不会影响到别的接口，但全程不写代码。
为什么重要：先建立影响范围可以减少盲目重构。也就是"先看清楚再动手"，能避免那种"改一个地方带崩一片"的低级事故。
怎么验证（证据点）：
- 相关文件清单：列出了要改、要看的文件。
- 调用关系：讲清了谁调用谁。
- 现有测试：找到了和这块相关的已有测试。
别踩的坑（边界）：搜索命中不证明已经理解业务语义。意思是，AI 搜到"状态"两个字出现在 30 个文件里，不代表它真的懂了订单状态在业务上意味着什么——搜索命中 ≠ 理解业务。
落地检查：计划要引用实际代码与契约。也就是说，AI 后面写的计划不能只靠"我搜过了"这种空话，必须引用真实存在的文件、函数、接口契约来支撑。
第 3 步：生成修改计划
原文：计划说明改什么、不改什么、风险、验证和回滚。
白话：AI 基于前面摸清的情况，产出一份"修改计划"。这份计划必须说清楚四件事：改什么、不改什么、有什么风险、怎么验证以及怎么回滚。计划是给人看的，不是给机器直接执行的。
类比：像医生做手术前给家属的方案说明——"我准备动这里、不动那里、有哪些风险、术后怎么复查、出了问题怎么补救"，家属点头了才进手术室。
举例：AI 的计划写成："只新增一个订单状态筛选参数，不改现有列表的分页逻辑；风险是可能影响旧接口的返回结构，已有测试兜底；验证方式是用冻结的单测 + 一个最小冒烟请求；回滚方式是撤销本次 diff。" 人一看就知道影响范围有多宽。
为什么重要：人审查的是影响范围和成立条件，不是逐行代写。也就是说，人不需要（也不应该）逐行 review AI 的代码，人真正要审的是"这件事影响多大、前提是否成立"。
怎么验证（证据点）：
- 目标对应：计划里的每一步都能对上任务目标。
- 范围受控：改与不改的边界写得清清楚楚。
- 验收可执行：验证方式具体、能落地。
别踩的坑（边界）：计划语言专业不代表影响范围完整。意思是，计划写得很漂亮、术语很专业，不代表它把该考虑的影响都考虑全了——专业措辞可能掩盖遗漏。
落地检查：任何扩大范围都要单独说明。也就是说，如果 AI 在计划里发现"顺便要改一个架构问题"，绝不能顺手带过，必须单独拎出来讲清楚为什么扩大范围。
第 4 步：确认后进入修改
原文：人确认目标、事实、边界和验收，Coding Agent 才开始修改。
白话：计划摆出来后，由人来确认四件事：目标对不对、事实准不准、边界合不合理、验收标准可不可行。都确认了，Coding Agent 才被允许真正动手改代码。确认是动手前的最后一道闸。
类比：像开工前甲方在施工单上签字——图纸（计划）、现场情况（事实）、施工范围（边界）、验收标准都过目了，签了字，施工队（Coding Agent）才开工。
举例：人来审这份订单计划，确认"目标就是加只读筛选、事实是现有接口确实长这样、边界就是不碰分页、验收就是单测过 + 冒烟通过"，然后说"可以改"。这时 Coding Agent 才开始写代码。
为什么重要：确认发生在可判断信息齐全之后。也就是说，确认不是走过场，而是要等到"目标、事实、边界、验收"这些判断材料都齐了才做，缺一块就不该确认。
怎么验证（证据点）：
- 计划已确认：人明确点了头。
- 冻结测试存在：有"冻结住"的测试用来防止回归。
- 回滚点已记录：记录了从哪一步能回退。
别踩的坑（边界）：确认计划不代表最终产物通过。意思是，人同意了计划，不等于改出来的东西就一定对——计划通过只是"可以开始干"，最终能不能通过还得靠后面的验证。
落地检查：后续仍需 diff、测试和运行证据。也就是说，确认之后不能撒手不管，还得继续盯 diff（代码差异）、测试结果、运行证据这三样，才能说最终产物合格。
落地可行性小结
本场景涉及的技术栈和落地要点：AGENTS.md（项目协作规则文件）、Spec（规格说明）、Coding Agent（写代码的 AI）、diff（代码差异）、冻结测试、回滚点。
真实落地时要注意：规则文件要真的存在且被工具读取，而不是"口头约定"；"只读定位"要能靠工具真的做到只读，不能有写权限；修改计划要有固定的结构（目标/范围/风险/验证/回滚），方便人和机器都能对照检查。常见坑是：把"AI 读了规则"当成"AI 会遵守规则"，忽略了权限和沙箱这道硬约束；以及确认环节被架空，变成走个形式。
回顾
- 入口的核心是"先理解、再计划、后动手"，理解阶段全程只读。
- 规则（AGENTS.md、Spec）是稳定入口，但只是软约束，硬约束还得靠权限、沙箱和测试。
- 计划的价值在于"影响范围和成立条件"可审查，而不是逐行代写。
- 人工确认是动手前的最后一道闸，缺材料不能确认。
- 确认通过只是"可以开始"，最终还得靠 diff、测试和运行证据来验收。