01 / PLAN
规划
- 研究问题与理解代码库
- 编写需求、架构与约束
- 拆成可执行计划并质询假设
AI Engineering Skills Map · Coding Agents
使用 Coding Agent：从写代码，转向驾驭可验证的工程闭环
Coding Agent 的价值不止是生成代码。真正的杠杆在于：让智能体参与需求澄清、方案设计、实现、测试、上线和运行改进，同时保留人对目标、风险和质量的最终判断。
一句话结论：代码的边际成本正在下降，工程师的核心价值上移到定义问题、约束系统、分配自主权、验证结果与驱动迭代。没有规格与验证的“快速生成”，只是在更快地积累不确定性。
从 Implementation 到 Steering：工程师不再只完成一个实现，而是设计一套让 Agent 可以安全地产出、证明并持续改进实现的工作系统。
这不是“少写代码”的口号。对 API、数据、测试、性能、安全与架构的理解仍是判断基础；差别在于，知识被用于设定边界和识别错误，而不只是手工敲出每一行代码。
01
工程闭环：规划 → 执行 → 部署与监控
三阶段不是瀑布流程；任何后续证据都可以把工作带回前一阶段。
原帖给出的高层工作流沿用了软件工程的基本骨架，但重心发生了变化：人和 Agent 花更少时间逐行实现，更多时间在系统性地消除“做错事、以错方式做、无法证明做对”的风险。
02 / EXECUTE
执行与验证
- 按风险授予 Agent 自主权
- 实现、测试、检查变更
- 以自动化与人工证据验收
03 / OPERATE
部署与监控
- 通过 CI/CD 与发布门禁
- 观察日志、指标与用户信号
- 将故障转化为改进任务
反馈不是异常：测试失败、成本超标、线上告警和用户反馈，都是重新校正规格与计划的输入。
| 阶段 | 人的高价值职责 | Agent 的高杠杆职责 | 必须留下的证据 |
|---|---|---|---|
| 规划 | 确认问题、权衡边界、接受风险 | 检索代码库、提出方案、发现依赖与矛盾 | 规格、架构决策、任务计划 |
| 执行 | 授予权限、处理分歧、审查关键变更 | 编码、重构、编写测试、运行工具 | Diff、测试结果、评审说明 |
| 运行 | 决定发布策略、定义 SLO、处理升级 | 汇总遥测、定位候选原因、准备修复 | 发布记录、仪表盘、复盘与改进项 |
02
规划：把模糊意图变成可执行约束
Agent 能补全代码，却不能可靠地替你决定“什么才算完成”。
为什么规划反而更重要
模型可以很快给出貌似合理的实现；当目标、边界和验收口径含糊时，它同样会很快放大偏差。规格不是文档负担，而是压缩后的决策：让 Agent、评审者和未来的维护者共享同一套事实。
规格的三个层次
结果：用户得到什么变化；
约束：不可破坏的兼容性、安全、性能与成本边界；
证据：用哪些自动化或人工检查来证明结果成立。
先做问题发现，再写实现指令
让 Agent 梳理现状、入口、依赖、数据流和未知点；对不可逆决策先做小实验。把“我认为”与“仓库事实”分开记录。
写出可证伪的规格
每条需求都要能判断对错。避免“性能更好”“体验友好”这类无量纲表述，改成目标延迟、错误率、响应状态、可访问性或用户路径。
把计划拆到可回滚的增量
每一步都声明输入、修改范围、检查方式与回滚点。这样 Agent 可并行处理低耦合任务，人也能在风险升高前停止或改变方向。
可交给 Agent 的最小规格模板
## 目标 为 <用户/系统> 提供 <能力>，解决 <可观察问题>。 ## 范围与边界 - 包含：... - 不包含：... - 兼容性 / 权限 / 数据约束：... ## 验收标准（可验证） - [ ] 输入 A 时，系统返回 B，状态码为 200 - [ ] 异常 C 时，返回 D，且不写入数据 - [ ] P95 延迟不高于 ...；日志中包含 correlation id ## 实施约束 - 允许修改：... - 禁止修改：... - 必须复用的模块 / 接口：... ## 交付证据 - 单元 / 集成 / E2E 测试：... - 迁移与回滚方案：... - 需要人工确认的决策：...
实践判断：绿地原型可以用一段短 Prompt 承载规格；已有用户、历史数据和多团队依赖的棕地系统，则必须用更完整的架构、迁移与验证约束。规格的长度应随变更的不可逆性和影响范围增长，而不是随项目名称增长。
03
执行：校准自主性，而不是二选一地“放手”或“盯住”
自主性应由任务风险、可验证性和可逆性决定。
高效使用 Coding Agent 的关键不是给出越长的提示词，而是给出恰当的行动空间。行动范围越广，越要配套权限、检查与升级规则；否则 Agent 的速度会直接转化为更大范围的返工。
L0
问答与探索
问答与探索
只读检索、解释代码、列出选项；不写文件、不执行改变外部状态的命令。
无需审批
L1
局部变更
局部变更
单模块缺陷修复、测试补全、文档更新；改动边界清晰且可通过本地检查验证。
Diff + 自动测试
L2
功能增量
功能增量
跨文件实现、数据库迁移草案、受控重构；需要完整计划和质量门禁。
计划确认 + CI
L3
高影响动作
高影响动作
生产配置、权限策略、支付与数据删除；即使 Agent 能执行，也必须显式人工授权。
人工批准 + 回滚
上下文规格、仓库规则、事实与约束
行动读取、修改、运行测试与工具
证据日志、Diff、测试、评估结果
门禁自动规则或人工确认
反馈更新规格、提示词与环境
给 Agent 的上下文，不是背景故事
优先提供会影响决策的内容：代码库规范、接口契约、数据模型、允许访问的工具、测试命令、已知风险以及“遇到什么情况必须停下”。长篇但无关的描述会稀释约束并占用上下文窗口。
让 Agent 先交付计划，再交付改动
对于 L2/L3 任务，先要求输出文件清单、数据流影响、测试策略和未决问题。计划是低成本的观察点；在 Agent 修改数十个文件之前发现误解，比事后回滚要便宜得多。
任务指令的控制面示例
你是该仓库的实现代理。先执行“只读理解”阶段： 1. 读取 AGENTS.md、相关模块与现有测试；不得修改文件。 2. 输出：影响的文件、拟采用方案、风险、测试计划、需要我决定的问题。 3. 等待确认后，才进入修改阶段。 修改阶段约束： - 只修改确认过的范围；发现范围外依赖时立即停止并说明。 - 每完成一个子任务运行指定检查，保留结果摘要。 - 不执行生产发布、数据删除、权限提升或外部写操作。 - 最终交付：变更摘要、关键 Diff 解释、测试证据、剩余风险与回滚方式。
04
验证：用证据替代“看起来没问题”
Agent 输出的是候选实现；通过验证后，才成为可合并的工程变更。
由于模型输出具有不确定性，验证是 Agentic Coding 的核心环节，而非交付前的附加步骤。一个健康的验证体系要覆盖行为、集成、非功能约束和变更风险，并将可自动化的部分固化为持续门禁。
| 验证层 | 回答的问题 | 典型机制 | 最适合拦截的风险 |
|---|---|---|---|
| 静态检查 | 代码是否满足基本约束？ | 格式化、类型、Lint、依赖与密钥扫描 | 语法、风格、明显安全问题 |
| 单元测试 | 局部逻辑是否正确？ | 边界输入、异常分支、属性测试 | 回归、条件遗漏 |
| 集成 / 合约 | 组件能否按约定协作？ | API 合约、数据库、消息队列、Mock 边界 | 接口漂移、序列化与事务问题 |
| 端到端 / 评估 | 用户目标是否被真正完成？ | 关键路径、Golden Set、Agent 轨迹评估 | 流程断裂、模型输出劣化 |
| 人工审查 | 权衡是否正确且可维护？ | Diff 审查、威胁建模、架构检查 | 错误抽象、权限和产品偏差 |
评审时优先看什么
先看规格差：是否做对目标；
再看风险差：是否引入新权限、数据或成本风险；
最后看代码差：边界是否清楚、失败是否可观测、未来是否容易修改。
验证要可追溯
把每项验收标准映射到检查项，例如“防止重复扣款”映射为幂等键集成测试和失败重试测试。这样 Agent 无法通过只提高代码覆盖率来绕开真正的业务要求。
重要区分：“Agent 自己运行了测试”不等于“变更被验证”。关键在于测试是否覆盖正确的风险、环境是否可信、结果是否与规格关联，以及谁拥有最终的合并责任。
05
部署与监控：把生产环境变成下一轮改进的传感器
编码完成不是终点；真实运行数据决定系统是否值得继续信任。
发布门禁
把已验证的构件经过 CI/CD、变更审批、特性开关与灰度策略推向生产。高风险变更应默认具备回滚路径。
可观测性
关联请求 ID、版本、模型/工具调用、延迟、成本、错误与业务结果。对 Agent 系统，还要记录关键决策和工具轨迹。
改进闭环
让 Agent 汇总日志、聚类异常、生成候选修复与回归用例；人决定优先级、是否发布以及是否修改系统边界。
SLO / Error Budget
定义服务可靠性与可容忍失败量，避免只盯“功能是否上线”。
Release Record
记录版本、变更范围、门禁证据、负责人、灰度指标与回滚开关。
Trace & Log
在请求、模型调用、工具动作之间建立关联，让故障从“猜测”变为可定位证据。
Incident → Eval
每个有代表性的线上失效，都应沉淀为回归样例、规则或测试，而不是只修一次。
06
五类核心能力：Coding Agent 的真正使用门槛
工具会不断变化，下面五类判断能力会留在工作流中。
01
指挥工作流
选择从探索、规划、实现还是排障开始；把大目标拆成能验证、能回滚的子任务；知道何时让后续反馈回流到规格。
产出：有顺序、有门禁的执行计划
02
赋能 Agent 自主性
基于风险配置工具权限、上下文、检查和停止条件。让低风险工作快速自动化，让高风险动作保留人工控制点。
产出：权限与自主性分级
03
审查工作
不只读代码风格，更检查是否满足规格、是否忽略边界、是否引入安全与可运维风险，并判断验证证据是否充分。
产出：基于风险的评审结论
04
定制 Agent 与环境
将仓库规则、工具说明、测试命令、常见陷阱、上下文检索与评估集做成稳定的工作环境，而非每次临时口述。
产出：可复用 Harness 与项目记忆
05
掌握 Agent 基础
理解模型能力边界、上下文窗口、工具调用、权限、成本、失败模式与评估。基础决定你能否识别“很像对的错”。
产出：正确的架构与工具取舍
×
共同底座：领域判断
所有能力都需要业务与工程常识支撑。Agent 可以生成方案，但“这个问题值不值得做、可承担什么风险”仍是人的不可外包职责。
产出：正确的问题与优先级
07
团队工件系统：把个人技巧沉淀成组织能力
好的 Harness 让正确路径比临时发挥更容易发生。
当 Coding Agent 成为日常工作者，团队要管理的不只是一套代码库，也是一套可让智能体稳定工作的“控制面”。把反复说明的规则、验收和运行经验固化为机器可读取、人员可审查的工件。
AGENTS.md
仓库入口规则：模块地图、构建命令、代码约定、允许/禁止操作、提交前检查、升级联系人。
spec/*.md
需求、边界、架构决策、验收标准和未知项；是 Agent 规划与评审的共同依据。
plans/*.md
任务拆分、依赖顺序、每一步验证、回滚点。长期任务可据此恢复上下文。
evals/
关键路径的测试样例、评分标准和线上故障回归集；既评估模型输出，也评估 Agent 的完整轨迹。
.ci/
把格式、类型、测试、安全扫描、发布门禁自动化，减少依赖“评审时恰好发现”。
runbooks/
发布、告警、排障、降级和回滚步骤，让 Agent 可协助诊断但不会越权处置。
工程原则：不要把关键上下文只放在聊天记录中。能决定 Agent 行为的长期规则，应进入版本控制并与代码一起演化；这样每次运行都可复现、可评审、可改进。
08
一个功能的 Agentic Coding 执行清单
适用于已有代码库中的中等风险功能增量。
定义业务结果与不可触碰边界
补齐用户路径、异常路径、接口契约、数据与权限限制，并将每一项验收要求写成可检查条件。
让 Agent 只读探索并输出计划
要求引用实际文件与测试，不接受脱离仓库的“通用方案”；逐条确认风险与未知项。
按可验证增量实施
每一批改动尽量独立、可编译、可测试。Agent 完成一个子任务后先给出证据，再进入下一个。
执行分层验证与人工风险审查
先自动检查，再审核规格覆盖、失败处理、数据迁移、安全与运维影响；必要时要求 Agent 解释它没有采用的方案。
受控发布并观察真实信号
用特性开关或灰度控制影响；提前定义成功指标与回滚阈值。线上异常沉淀为回归案例，更新规格和 Harness。
09
30 天训练路径：从“会用工具”到“能带 Agent 做工程”
目标不是熟练某一个产品，而是建立跨 Agent 的控制与验证能力。
第 1 周 · 可观察
建立基线与项目上下文
选一个真实但低风险的 Java 或服务端小功能。补齐 AGENTS.md、构建/测试命令和模块地图；记录 Agent 首次探索中出现的误解。
第 2 周 · 可规划
把三项需求写成可证伪规格
每项都要求 Agent 先做只读分析、提出执行计划；比较计划与最终 Diff 的偏差，找出信息不足的地方并更新模板。
第 3 周 · 可验证
为 Agent 变更建立质量门
将类型检查、单测、接口合约、关键路径测试和安全扫描接入统一命令；至少复盘一次“测试通过但设计不对”的案例。
第 4 周 · 可运行
完成一次受控上线闭环
为功能增加日志、指标、发布开关与回滚步骤。用生产或预发布数据构造一个失败案例，沉淀到 evals/ 与运行手册。
10
常见失效模式与修正动作
Agent 的产能越高，错误控制越不能靠感觉。
“直接实现，不用先问”
结果常是合理但错误的方案，尤其在棕地系统中会绕过既有约束。
修正：先探索、再计划；对缺失的业务规则显式提问。
“测试绿了，所以可以合并”
测试可能没有覆盖规格或真实依赖，Agent 也可能只补最容易通过的路径。
修正：验收标准与测试一一映射，再加差异和风险审查。
“给足权限，效率最高”
未经约束的高权限 Agent 会将偶然误解放大为外部状态变更。
修正：最小权限、分级自主性、敏感动作双重门禁和可验证回滚。
“每次重新写一段 Prompt”
团队经验停留在个人记忆，输出随人和会话波动。
修正：把稳定规则写进仓库工件，以版本控制维护 Harness。