Engineering Agent Practice

Codex / Claude Code 类 Agent 实战

从基础概念、工作原理、5W1H 分析到第一性原理落地：把 AI 编程助手升级为企业级生产力系统。

Agent 基础 CLI 工作流 5W1H 第一性原理 企业落地 
$ agent "修复订单导出失败，先读代码再给计划"
Inspecting repository...
Finding tests and runtime paths...
Plan ready: 3 files, 2 tests, low-risk patch

$ npm test -- orders/export
✓ targeted suite passed

Human review:
业务语义、权限边界、发布窗口、回滚方案
核心问题：怎样让 coding agent 稳定进入企业交付流程01 / 14
Concept

什么是 Codex / Claude Code 类 Agent？

它不是单纯的聊天机器人，而是运行在工程环境里的“目标驱动执行体”：能理解任务、读取上下文、调用工具、修改文件、运行验证，并在关键节点请求人类判断。

大模型负责理解自然语言、推理方案、生成代码和解释风险。
上下文来自仓库、日志、文档、测试、历史约定和用户约束。
工具包括 shell、编辑器、搜索、测试框架、浏览器、CI、工单系统。
循环观察、计划、行动、验证、汇报，直到达到停止条件。
Agent = 模型能力 + 工具权限 + 上下文管理 + 执行循环02 / 14
Landscape

它和普通 AI 助手、IDE 补全有什么不同？

类型
主要能力
适合场景
关键限制
聊天助手
解释概念、生成片段、讨论方案
学习、头脑风暴、轻量咨询
不直接接触真实仓库和验证环境
IDE 补全
根据当前文件补代码、补注释
局部编码、样板代码、快速输入
跨模块任务和验证能力有限
Coding Agent
读仓库、改文件、跑命令、反馈结果
缺陷修复、测试补齐、迁移、重构辅助
需要权限治理、任务边界和人类审查
自动化脚本
按固定规则重复执行
稳定、确定、重复的流程
面对模糊任务和新情况时适应性弱
Coding agent 的价值在于把“建议”推进到“可验证的工程动作”03 / 14
Architecture

一个工程 Agent 的基础架构

1

任务与约束

目标、范围、验收标准、权限边界、停止条件。输入不清楚时先澄清。

→
2

上下文与工具

读取代码、运行搜索、调用测试、查看日志，把推理建立在证据上。

→
3

行动与验证

小步修改、局部验证、汇报差异、暴露风险，最后交给人类审查。

Observe → Plan → Act → Verify → Report
每一轮都要回答：证据是什么？改了什么？验证了什么？还剩什么风险？
企业使用 agent，首先要管理的是执行循环，而不是提示词技巧04 / 14
Capabilities

Codex / Claude Code 类 CLI 通常能做什么？

理解代码库扫描目录、查找调用链、解释模块职责、提炼隐含约定。
制定计划把模糊任务拆成文件范围、验证路径、风险点和执行顺序。
编辑文件生成补丁、补测试、改配置、写脚本，并保持可审查的变更粒度。
运行命令执行测试、类型检查、lint、构建、脚本和局部复现命令。
跨工具协作结合浏览器、数据库、日志平台、Issue、PR 和文档系统。
沉淀知识把有效工作流写成模板、命令、规范、检查清单和案例库。
能力越强，越需要边界、验证和审计05 / 14
Boundaries

它擅长什么，不擅长什么？

Agent 最适合“有上下文、有验证、有明确边界”的工程任务；最危险的是“高权限、低证据、难回滚”的任务。

适合读代码、补测试、修小缺陷、生成脚本、文档同步、迁移辅助、重复性排查。
谨慎架构大改、跨团队接口变更、性能调优、复杂数据修复、权限系统改动。
不该放手生产密钥、资金链路、删除性操作、法律合规判断、无法验证的业务语义。
人类责任明确目标、裁决权衡、评估风险、承担合并和发布责任。
不要把 agent 当成替代责任的机制，它只能放大已有工程纪律06 / 14
5W1H

用 5W1H 定义企业级使用场景

Why为什么引入缩短交付周期、减少知识等待、降低重复劳动和交接损耗。
Who谁来使用开发、测试、SRE、数据、平台、技术产品；按角色配置权限。
What解决什么任务代码理解、缺陷定位、测试补齐、脚本生成、迁移辅助、文档同步。
When何时介入需求澄清后、编码前、调试时、PR 前、发布前、事故复盘后。
Where在哪里运行开发机、受控沙箱、CI、内网知识库；敏感系统需要隔离。
How如何形成闭环任务模板、最小授权、自动验证、人审门禁、日志审计和指标复盘。
5W1H 把“工具热情”转成“可治理的应用边界”07 / 14
First Principles

第一性原理：软件交付到底由哪些基本动作组成？

理解目标、约束、验收、业务语义。
定位代码、数据、依赖、运行路径。
修改最小变更、可读补丁、可回滚设计。
验证测试、构建、日志、复现、灰度。
交接PR、文档、风险说明、后续动作。

Agent 的生产力来自压缩这些基本动作中的等待、搜索、重复和手工验证。不是每一步都自动化，而是每一步都更快进入有证据的状态。

先分解基本动作，再决定哪些动作适合交给 agent08 / 14
Workflow

推荐实战流程：从任务到可合并变更

1. 任务合同背景、目标、范围、验收、不可做事项先写清楚。
2. 仓库侦察让 agent 先读目录、测试、历史模式，再输出计划。
3. 小步执行限定文件范围，要求最小可审查补丁，避免顺手重构。
4. 自动验证跑相关测试、类型检查、lint、局部构建，记录证据。
5. 人审合并人看业务语义、权限、发布窗口、回滚和长期维护。
$ agent "按现有模式补齐退款接口集成测试；只改 tests/refund/*"
Plan: inspect payment tests → add refund cases → run targeted suite
好的流程一定是计划可见、改动可控、验证可追溯09 / 14
Task Contract

提示词不要像聊天，要像任务合同

企业场景里的提示词要把范围、证据、验证和退出条件写清楚，让 agent 的自由度集中在解决问题，而不是猜边界。

任务：修复导出 CSV 乱码。
范围：只允许改 export 模块和相关测试。
约束：不改变接口入参；保持旧文件名规则。
要求：
1. 先说明会读哪些文件。
2. 给出最小修改计划。
3. 修改后运行相关测试。
4. 最后列出风险和未覆盖项。
停止条件：需要生产凭据或高风险操作时先暂停。
任务合同是把个人经验复制到团队的最低成本方式10 / 14
Use Cases

最值得优先落地的 6 类场景

新成员上手解释模块边界、启动流程、关键表、调用链和常见问题。
Bug 定位根据日志、报错、复现步骤追代码路径，生成验证方案。
测试补齐按现有测试风格补边界用例、回归用例和快照更新。
遗留系统改造先画依赖图，再做小范围迁移，保留行为等价测试。
重复脚本生成批量数据检查、迁移、报表、巡检脚本，但必须可回滚。
文档同步从代码差异提炼接口变更、运行手册、FAQ 和 release note。
优先选择高频、低风险、验收清楚、验证自动化程度高的任务11 / 14
Governance

企业落地的护栏：权限、数据、质量、责任

维度
低风险默认
中风险审批
高风险禁止或隔离
权限
只读仓库、局部写入、限定命令白名单
跨模块修改、依赖升级、批量脚本
生产凭据、资金链路、删除性操作
数据
脱敏日志、公开文档、测试数据
内部接口、客户字段样例
密钥、隐私原文、未脱敏生产数据
质量
必须跑局部测试并记录输出
需要 reviewer 二次确认
无验证、不可回滚、不可解释的改动
责任
AI 生成建议，人提交和负责
明确 owner、灰度和回滚人
把事故责任转嫁给工具
越是要规模化使用，越不能跳过治理设计12 / 14
Measurement

怎么证明它真的提高了生产力？

不要只看“生成了多少代码”。要看周期、质量、知识复用和工程体验是否改善。

交付周期从任务领取到 PR、从 PR 到合并、从缺陷发现到修复。
质量信号回归缺陷率、测试覆盖变化、代码审查返工次数。
知识复用模板复用次数、文档更新率、新人独立完成任务时间。
开发体验上下文切换减少、重复劳动减少、阻塞等待减少。
衡量指标要服务业务，不要变成工具 KPI13 / 14
Roadmap

三阶段推进路线

第 1 阶段：个人试点选择 3 个高频低风险场景，沉淀任务模板和验证命令。目标是找到真实收益点。
第 2 阶段：团队规范建立权限边界、提示词库、PR 检查清单、失败案例库。目标是可复制。
第 3 阶段：平台化接入知识库、CI、工单、审计和指标看板。目标是把能力变成组织基础设施。

把 Codex / Claude Code 类 agent 用好，不是让 AI 多写几行代码，而是重新设计人、工具、流程、验证之间的分工。5W1H 帮我们定义边界；第一性原理帮我们拆解交付动作；工程化护栏让生产力提升可以被组织吸收。

Q&A14 / 14