CodeBuddy 的 AI Agent 模式适合处理跨文件的改动：你描述目标，它自己读代码、定位相关文件、给出修改方案再动手执行，不必你逐个文件搬运上下文。用好的关键不在功能本身，而在四个环节的把控：怎么交代任务、怎么确认计划、怎么分步执行、怎么验证结果。把这四步做实，大改动也能稳稳落地。
Agent 模式与一问一答的差异
普通对话模式里，模型给建议、给代码片段，动手的人是你：复制、粘贴、找文件、自己判断改哪里。Agent 模式把这一串动作交给了 AI：接到任务后它先检索代码库定位相关文件，再给出执行计划，确认后直接修改文件，并可以运行测试自查。差异的本质是「决策权的分配」：一问一答里你是执行者，Agent 模式里你是审批者。这个差异决定了使用方式的不同——你给它的不再是一段段具体指令，而是一个目标加一组边界；你收回来的不再是一段段代码，而是一次次需要你审阅的改动。权限越大，越需要流程管着，这正是后面几节的内容。
任务描述要交代的三件事
Agent 模式的产出质量，直接取决于任务描述的完整度。三件事必须交代：目标（要达成什么效果，尽量带可验证的标准，比如「所有相关单测通过」）；范围约束（允许动哪些模块、哪些文件不能碰、保持哪些接口不变，这一条决定改动的爆炸半径）；背景信息（相关业务逻辑、已知坑、团队规范，模型读代码能看懂结构，看不懂你的业务约定）。反面做法是只贴一段报错让它「修好」——没有范围约束时，Agent 可能顺手动它认为相关的所有文件，改完功能对了，架构却伤了一圈。宁可多花两分钟写全描述，也省掉后面大量回滚。
改动计划的确认环节
Agent 模式通常会在动手前给出计划：要读哪些文件、改哪些位置、按什么顺序。这个环节是整个流程里最重要的安全闸，值得认真对待。审计划看三点：文件清单是否越界——计划里出现你认为不该动的文件，立即追问原因；修改顺序是否合理——先改接口再改实现、先加测试再改逻辑，顺序错会中途不可运行；是否有不理解的术语或路径——不懂就让它解释，别带着疑问放行。确认后也别当甩手掌柜，让它每完成一个文件停下来报告，而不是一口气改完十处再给你看。计划确认多花的三五分钟，换来的是对改动全局的掌握，这笔账划算。
大范围重构的分步策略
跨十几个文件的重构，不要用一个任务让 Agent 一口气完成。把大改动切成层：第一批只改数据层，跑通测试后用版本控制提交一个节点；第二批改服务层，再提交；第三批改调用方。每批任务里把「上一批已完成的内容」告诉它，避免重复处理。每批之间跑一遍完整测试，出问题回滚只回滚一小步。切分的依据可以让 Agent 自己出——先让它只读代码、输出一份改动方案与分批建议，你审核调整后按批执行。这样即便某一批出了问题，损失也局限在那一批内，定位与恢复都容易。
改完之后的验证动作
Agent 自查不等于验收，改完必须走三道人工确认：看 diff——逐个文件过一遍改动，重点看有没有越界修改（顺手改了不相干的代码、动了格式、加了没要求的依赖），diff 里任何一处说不清来由的改动都要追问；跑测试——单元测试、集成测试按项目常规跑全，只跑改动相关的测试不够，跨文件改动的波及面经常超出预期；抽查行为——实际运行一遍核心路径，确认功能真实可用而不是「测试通过但跑不起来」。全部通过后再提交，提交信息里注明「Agent 辅助修改」与改动范围，团队其他人 review 时心里有数。
Agent 模式改跨文件代码怎么控制风险？
- Agent 改坏了已有的功能怎么办？：用版本控制回滚到改动前的节点，把出错的部分单独拆成小任务重新交给它，并在描述里补充上次出错的原因作为约束。
- 什么任务不适合交给 Agent 模式？：涉及架构决策、性能调优这类需要权衡取舍的改动，先自己做决策再让它执行；需求本身没想清楚的任务，先想清楚再上。
- 怎么写提示让 Agent 少走弯路？：目标、范围、背景三要素写全，附上相关文件路径与测试命令，把「不要做什么」和「要做什么」写一样清楚。
