从代码补全到读仓库、改文件、跑测试、开 PR 和长期维护：理解编码 Agent 怎样进入真实软件工程
| 阶段 | Agent 要做什么 | 工程难点 | 人类应关注 |
|---|---|---|---|
| 任务理解 | 把自然语言需求转成可改动的范围、约束和验收标准 | 需求歧义、隐含背景、业务规则缺失 | 是否明确目标、非目标、风险和完成标准 |
| 仓库理解 | 阅读入口、依赖、测试、局部调用链和已有模式 | 上下文窗口有限，容易只看局部 | 是否找到真正相关文件，而不是按名字猜 |
| 计划与编辑 | 生成补丁、重构、迁移或测试 | 跨文件一致性、边界条件、风格契合 | 改动是否足够小、是否符合项目习惯 |
| 本地验证 | 运行测试、构建、类型检查、lint、最小复现 | 测试慢、依赖缺失、环境差异 | 失败是否被解释和修复，而不是跳过 |
| 代码评审 | 解释 diff、发现回归、补充测试、回应评论 | 模型容易为自己辩护，忽略深层设计风险 | 优先看行为变化、数据迁移、安全和可维护性 |
| 交付回流 | 记录经验、更新文档、沉淀任务模式 | 上下文容易丢，知识沉淀不稳定 | 哪些模式应写进文档、测试或工具 |
| 形态 | 核心能力 | 适合任务 | 边界 |
|---|---|---|---|
| 代码补全 | 在当前文件和光标附近补片段 | 样板代码、局部实现、API 调用 | 不理解完整仓库和需求上下文 |
| 聊天式助手 | 解释代码、生成方案、回答问题 | 学习、排障、方案讨论 | 容易停留在建议，不直接形成可验证改动 |
| IDE Agent | 读多文件、改代码、运行局部命令 | 中小功能、bug 修复、测试补齐 | 权限、上下文和验证范围要控制 |
| 仓库级 Agent | 理解项目结构、跨文件修改、维护任务状态 | 迁移、重构、跨模块功能 | 更需要计划、检查点、回滚和审查 |
| 团队级 Agent | 接 issue、开分支、跑 CI、回应 review、更新文档 | 半自动交付、维护性工作、批量修复 | 必须接入权限、审计、分支策略和人工闸门 |
| 验证层 | 能证明什么 | 不能证明什么 | 适合怎么用 |
|---|---|---|---|
| 单元测试 | 局部逻辑和边界条件 | 系统集成和真实用户流程 | 修 bug、改算法、补回归样本 |
| 类型检查 / 编译 | 接口、类型和语法层不破 | 业务行为正确 | 作为快速闸门，不应替代测试 |
| 集成测试 | 模块协作、数据库、外部接口 | 所有生产数据分布 | 跨模块改动必须优先跑 |
| E2E / Playwright | 真实用户路径和界面行为 | 所有浏览器和数据组合 | 前端交互、流程改动、回归验证 |
| 代码评审 | 设计、风险、可维护性、安全 | 机器可穷尽执行正确性 | 人机共同评审，重点看隐含假设 |
| CI / Release Gate | 统一环境下的可合入状态 | 上线后一切稳定 | 作为合入闸门，并配合灰度和回滚 |
编码 Agent 的上限不只取决于模型会不会写代码，而取决于它能否形成“改动 - 验证 - 解释 - 修正”的闭环。没有验证，它只是更快地产生未知质量的补丁。
| 任务类型 | 适合程度 | 原因 | 注意事项 |
|---|---|---|---|
| 测试补齐 / 回归样本 | 高 | 目标明确，可运行验证，风险可控 | 人类要确认测试是否真的覆盖行为 |
| 小型 bug 修复 | 高 | 有错误日志、复现和验收标准时效果好 | 避免只修表象，要保留失败用例 |
| 机械迁移 / API 替换 | 中高 | 规则明确，适合批量修改 | 需要抽样审查和全量测试 |
| 新功能开发 | 中 | 可以完成局部实现，但需求澄清仍重要 | 先写规格和任务拆解，再让 Agent 执行 |
| 大型架构重构 | 中低 | 影响范围广，隐含权衡多 | Agent 可做切片和辅助验证，不宜完全自治 |
| 安全敏感改动 | 低到中 | 需要威胁建模、权限判断和审计责任 | 必须人工评审和专项测试 |
一次编码 Agent run 不只是一次聊天或一次补丁，而是一组可审计 artifact：任务契约、上下文快照、工具调用、文件 diff、测试结果、评审决定、合入版本和回滚锚点。字段口径要能接入 AI 证据包索引、请求 Trace、Artifact Registry 和 发布 / 回滚。
| 证据节点 | 应该记录什么 | 用来回答的问题 |
|---|---|---|
| agent_run_id | request_id、thread_id、model_id、tool_policy、workspace_id、actor、time_window | 这次代码改动由哪个 Agent run 产生，使用了哪些权限和工具？ |
| task_id | 需求、验收标准、非目标、风险假设、用户确认点、handoff_reason | Agent 到底被要求解决什么，哪些边界不能碰，什么时候应该转人工？ |
| context_snapshot_id | 读取的文件、检索命中、日志、测试输出、AGENTS / README 规则、上下文裁剪原因 | Agent 做判断时看到了什么，是否漏读了关键约束或旧实现？ |
| diff_id | 改动范围、关键文件、行为变化说明、未改动边界、diff_hash、migration_flag | 这次补丁为什么这样改，影响面有多大，是否涉及迁移或兼容风险？ |
| tool_call_id | shell / test / browser / file edit / git 操作、参数摘要、权限裁决、退出码、重试次数 | Agent 执行了哪些动作，有没有越权、重复执行或跳过失败？ |
| test_run_id | 运行的测试、选择理由、失败修复、未能执行的检查及原因、coverage_delta、flaky_signal | 质量证据来自哪里，哪些风险仍未覆盖，失败是否被诚实保留？ |
| review_id | 人类批准点、评论处理、设计风险、安全风险、可维护性判断、accepted_risk | 谁认可了哪些行为变化，哪些问题被接受、修正或留作后续？ |
| release_id | 合入版本、CI run、灰度状态、回滚方式、数据兼容性、事故定位锚点、fixed_version | 上线后出问题时，能否快速定位、回退和复盘？ |
| 事故现象 | 要反查的证据 | 修复产物 |
|---|---|---|
| Agent 改了不该改的文件 | agent_run_id、task_id、context_snapshot_id、diff_id、path_scope_policy | 收紧写入边界，补路径白名单和 review checklist |
| 测试没跑或失败被跳过 | test_run_id、command_exit_code、failure_log、skipped_reason、user_visible_note | 把未执行检查显式暴露，补 CI gate 或最小回归测试 |
| 代码看似修好但线上回归 | diff_hash、release_id、ci_run_id、runtime_trace_id、incident_id | 生成 regression_case_id，回接发布闸门和回滚版本 |
| Agent 引入安全或权限风险 | tool_policy、secret_scan_result、permission_change、review_id、risk_tier | 补安全测试、权限审查、敏感文件保护和人工审批 |
| 大 diff 难以评审和回滚 | changed_files_count、diff_size、module_boundary、migration_flag、rollback_target | 拆小任务，生成分阶段 PR 和回滚计划 |
| Agent 误读项目规则 | rules_read、AGENTS_version、README_version、context_truncation_reason、review_comment_id | 更新项目规则、补上下文检索策略和 Agent 任务模板 |
复盘要能回答：它被要求做什么、看到了什么、改了哪里、跑了什么、谁批准了、怎么上线、怎么回滚。否则团队只能凭印象争论“AI 写代码靠不靠谱”，而不能把坏例变成可执行的工程治理改进。
| 原工作流 | 加入 Agent 后的变化 | 新的管理重点 |
|---|---|---|
| 需求拆解 | 需求要更可执行，验收标准要更清楚 | 把模糊想法压成任务契约 |
| 编码实现 | 人类从逐行书写转向审查方案、约束范围和验收结果 | 减少无意义细活，增加边界判断 |
| 测试与回归 | 测试成为 Agent 的反馈通道，而不只是最后闸门 | 维护快速、可靠、覆盖关键路径的测试体系 |
| 代码评审 | 评审重点从“这段代码谁写的”转向“行为和风险是否可接受” | 审查 diff、测试证据、迁移影响和安全边界 |
| 知识沉淀 | 项目规则和经验需要写给人也写给 Agent | 保持 README、AGENTS、运行手册和架构记录不过期 |
AI 编程 Agent 的真正价值，不是替人多写几行代码，而是把需求理解、仓库理解、补丁生成、测试验证、代码评审、发布回滚和证据回放连成可控协作系统。