工程化引入 Agentic Workflow：一些关于质量与协作转型的观察 ::

背景#

最近几个月我翻了几份团队内部和合作方写的「AI 辅助开发流程」文档，也在不同项目里反复用了 Claude Code、Codex CLI、Cursor。到目前为止，一个让我印象比较深的现象是：在我接触到的不少团队里，「AI 辅助」仍然更接近 2024 年常见的"对话框 + 复制粘贴"模式——人手动把 PRD、Tech Design 模板、代码上下文一次次拷进 Prompt 框，AI 输出一段文本，人再贴回 Confluence 或 IDE。

而同期一些更早公开分享这类实践的团队，做法已经不太一样：

Anthropic 的公开文章展示了多个团队如何把 Claude Code 用到 code review、排障、代码导航等具体场景里（原文）。
Rakuten 的案例文章给出了一组公开数据：TTM 从 24 个工作日降到 5 天，最长一次连续自主编码 7 小时；这些数字来自其官方案例分享，更适合当作参考样本，而不是直接当成通用基线（原文）。
Bessemer Atlas 对 Shopify 工程负责人的采访提到，Shopify 允许 Claude Code、Copilot、Cursor、Codex、Gemini 等工具并存，并用自建 LLM Proxy 做统一接入与治理；这更像一次访谈里的组织实践样本，而不是完整方法论（原文）。

我理解这两种使用方式之间的差距，未必只在于"AI 用得熟不熟"，更像是软件开发流程的工程化程度——前者很多时候还得靠人脑当编排引擎，后者则开始把一部分编排交给 agent，把一部分规则交给 ArchUnit / Hooks / GitHub App。

这篇文章不打算给一份"最佳实践"。模型能力、工具协议、商业模式都在快速演化（Claude 4.x、MCP、AGENTS.md、Spec Kit 都是 2024 下半年到 2026 年初才逐步稳定的），太早收敛到"标准答案"反而可能束缚团队。我更想做的是：把现实项目里的困惑和当下能看到的公开实践对齐，整理一份自己后续继续学习和落地时会反复回看的方向清单。

后续落地的细节会另起一篇，先把方向理清。

Agentic 与「贴 Prompt」的真实差距#

「AI 辅助开发」是一个被严重过载的词。要把后面的讨论建立在共同语境上，先把两种使用模式区分清楚。

至少在我现在的理解里，两种模式的差异不主要在于「用了什么模型」，而在于模型有没有被赋予可验证的动作能力。前者更多只能输出文字，所有跨系统的动作都靠人代劳；后者则可以通过工具调用直接读写、迭代、自检。

更具体地放进一张对照表：

维度	贴 Prompt 模式	Agentic 模式
上下文获取	人复制粘贴	MCP / 工具调用直接读
上下文规模	受窗口限制，反复消耗 token	prompt caching 能显著降低稳定前缀的重复成本
任务边界	单次问答	多轮 act/observe/reflect 循环
验证	人事后检查	agent 自己跑测试、读编译报错并修复
触发	人主动开会话	webhook / CI / 定时任务自动触发
输出	自由文本，靠人解析	结构化 JSON，CI 可直接消费
失败模式	上下文窗口爆 / 一次性输出错了重来	工具调用错 / Loop 不收敛，但有迹可循

现实团队通常会长期处在混合阶段，不会一天之内从一侧跳到另一侧。但如果目标是提升 agent 的自主完成度，后面这些讨论大多默认：团队会逐步把重心从"贴 Prompt"挪向更工程化的 Agentic 工作流。

引入 Agentic Workflow 的前提条件#

agentic 不是一个开关，它更像是一组工程能力的合奏。如果这些前提明显缺位，仓促引入往往只会把原有问题提前暴露出来。下面几条是我目前从公开案例和自己实践里归纳出来的自检项：

仓库内可机读的需求与设计。哪怕只是简单的 specs/<feat>/spec.md + openapi.yaml。如果需求和设计的"唯一真源"长期留在 Confluence 里，agent 往往会落后于最新状态。GitHub 的 Spec Kit 给出了一种轻量结构，值得借鉴，但不一定要照抄。
可复现的本地构建与测试。./mvnw verify 一条命令能从干净 checkout 到全测试绿，通常才有空间让 agent"自己跑测试、自己修正"。Anthropic Best Practices 反复强调 “Give Claude a way to verify its work”（原文）；如果 verify 不存在或不可靠，agent 的自检空间通常会很小。
静态可判规则已经落到工具。"@Transactional 不能放私有方法"、“controller 不能直接调 repository”、“Kafka send 不能在事务内”——这些规则更适合进 ArchUnit / SpotBugs / Semgrep / OpenRewrite。至少在我看来，继续只靠 prompt 提醒模型"不要…“更像 advisory，而不是 deterministic 约束。
至少一条鉴权可控的 LLM 入口。团队规模上来，或者同时用多家工具时，自建 LLM Proxy（类似 Shopify 访谈里提到的模式）往往会从"可选项"变成需要认真评估的选项——计费、配额、PII 脱敏、模型切换都可能落到这一层。开源参考：litellm。
团队对「测试是质量第一手段」有共识。AI 写代码常见的问题不一定是"一眼能看出的业务逻辑错误”，而是"测试 mock 太多，看上去全绿，结论却不可靠"。如果团队过去的 PR 习惯就是"先合再说"，agentic 很可能只会把这个问题放大。

这些项未必需要一次补齐，但如果完全绕开，“我们直接上 agent"的尝试通常还是会卡在其中一两条上。

各阶段如何保障高质量交付#

接下来按软件交付生命周期看：每个阶段在 agentic 模式下，质量保障的重心可能会从"人审"迁移到什么地方。这些不是步骤，更像是一些改进方向。

需求与设计阶段#

重心从"写文档"迁移到"写可被机器消费的契约”。

对需要被 agent 反复读取的需求和设计，我更倾向放到 git；Confluence 更适合作为组织流程入口或补充说明。GitHub Spec Kit 的目录约定 .specify/{memory, specs, templates, scripts} 提供了一种现成结构。
API 用 OpenAPI 3.1 描述，事件用 AsyncAPI 3.0 描述，会比手填 endpoint 表格更适合被工具消费：openapi-generator 可以直出 controller 框架，oasdiff 可以在 CI 上自动检测 breaking change。
决策落 ADR（Architecture Decision Records）。AI 第二次迭代时不会"记得"为什么之前选了 outbox 而不是 AFTER_COMMIT listener，但它能读 ADR。
如果 agent 能通过 MCP 直接读取 Jira / Confluence / GitHub，很多人工转述就能少一层。Atlassian 已发布 Remote MCP Server，GitHub 官方 MCP server 也已经正式可用。对我来说，/spec FORT-1234 这类入口会比"请把 PRD 内容粘到这里"更自然一些。

实现阶段#

重心可能会从"只盯写代码"迁移到"写测试 + 编排 agent"。

如果团队已经接受 TDD，我会优先让 agent 先把关键 logic flow 翻译成红色测试，再去补最少实现。Kent Beck 与 Anthropic 在 tidyfirst 上写过一套相近思路（原文）。
subagent 分工也值得尝试。开源参考 piomin/claude-ai-spring-boot 提供了 8 个 agent + 9 个 skill 的目录结构（包含 code-reviewer、spring-boot-engineer、test-automator 等）。Anthropic Best Practices 也推荐过 “Writer/Reviewer 双 session 模式”——独立 context 互审，减少一个 agent 自评时的偏差。
长上下文里相对稳定的前缀，值得配合 prompt caching 使用。CLAUDE.md + 项目 SKILL 这类内容如果每次都完整重算，PoC 的成本感知通常会更强。
并行方面，我更偏向用 git worktree 给每个 feature 一个独立工作区，多个终端各跑一个会话。Rakuten 文章里提到过更激进的并行 session 用法；但对大多数团队来说，先把 3–5 个 worktree 用稳，可能更现实。

评审阶段#

重心从"人逐行审"迁移到"机器先筛、人审主观项"。

能静态判定的规则全部进 ArchUnit / SpotBugs / Error Prone / Semgrep / CodeQL。"@Transactional 私有方法"、"@Autowired 字段注入"、"kafkaTemplate.send() 出现在 @Transactional 方法体内"这类规则都属于此。
半客观规则（如 “FK 字段必须有索引”）用 Hibernate Statistics 或 OpenRewrite recipe 在测试期断言。
主观规则（如 “outbox vs AFTER_COMMIT 的取舍是否合理”）落到 Claude Skill 按需加载，不塞进每次 prompt。Anthropic Agent Skills 与 GitHub 的 copilot-instructions.md 是同一思路的两个落地。
自动触发。Anthropic Code Review GitHub App（截至 2026-03 仍是 Team / Enterprise plan 的 research preview）给出过一组自报数据：大 PR ≥1000 行时，84% 收到发现、平均 7.5 个 issue/PR；不到 1% 的发现被标 incorrect；接入前 16% PR 有实质评审、接入后 54%；单次评审成本区间约 $15–$25。对我来说，这更像早期公开信号，而不是通用基准。CodeRabbit、Greptile 是社区替代。
关键模块跑双审。Codex CLI 二审 Claude 主写的输出，是我觉得成本不高的一类对抗性验证。

测试阶段#

重心从"覆盖率指标"迁移到"行为正确性 + 真依赖"。

覆盖率不能当 KPI。Goodhart 法则在这里生效：把"100% Service 层覆盖"变成考核会逼出大量"调方法不 assert"的空壳测试。Martin Fowler 的 TestCoverage 与 Google Testing Blog 的 Code Coverage Best Practices 都明确反对单纯覆盖率目标。
如果团队愿意多付一点测试时长，mutation testing（如 Pitest）通常比 line coverage 更容易暴露假绿测试。
能起真依赖时，我更倾向用 Testcontainers 起真 PostgreSQL / Redis / Kafka，而不是一路 mock 到底。Spring Boot 3.1+ 已经把 Testcontainers 做成 first-class 支持（官方文档）。
契约测试。在微服务协作里，Pact 或 Spring Cloud Contract 往往比"deploy 完跑一遍 Postman"更适合作为兼容性护栏。
兼容性 gate 接 CI：oasdiff --fail-on-diff 让破坏性 API 变更必须显式声明。

部署与运维阶段#

重心从"AI 直接动生产"迁移到"AI 改 declarative artifact，平台执行变更"。

对大多数团队，我更建议默认不要让 AI 直接 kubectl apply、直接 psql、直接 terraform apply。更稳妥的做法通常是：它只生成 / 修改 Helm chart / Kustomize / Terraform HCL，由 Argo CD / Atlantis 同步；把直接操作生产当成极少数 break-glass 场景。
渐进发布是我目前最看重的安全网之一。trunk-based development + feature flag（OpenFeature / LaunchDarkly）让 AI 写的代码先 1% → 10% → 100%，回滚也更容易落到 git revert 或翻开关这类熟悉动作上。Martin Fowler 的 Feature Toggles 是经典依据，DORA 多年研究也支持这类小步发布思路。
可观测性这块，我目前更认同 OpenTelemetry + W3C Trace Context 这类 trace-first 路线，而不是默认一切都靠日志兜底。每方法 5 行强制日志在很多系统里会变成噪音（可参考 Honeycomb CTO Charity Majors 的 Observability Manifesto）；span 自动采集 + 异常路径补日志，在不少系统里会更均衡。
AI 工作流本身也值得有一点可观测性。比如每次 agent 会话记录命令、产出、token、耗时；再按周复盘哪些任务反复返工，并把高频问题沉淀到 CLAUDE.md 或 ArchUnit 规则里。对我来说，这类闭环比"先多跑几次再说"更容易持续改进。

团队协作的转型#

工程能力之外，agentic workflow 对人的要求会发生明确的位移。这部分讨论的是角色，不是工具。

管理层（EM / Director / VP）#

衡量重心要从"产出量"更多地挪向**“产出质量与稳定性”**。AI 写得快不等于团队走得稳；在 Bessemer Atlas 对 Shopify 的采访里，“PR 数量上升、reversion rate 保持稳定"这类信号更让我信服。建议跟踪：

reversion rate：合并后 N 天内被 revert 的比例；
lead time for changes（DORA 标准指标）；
change failure rate（同上）；
AI 参与度分布：人写、AI 起草人改、AI 主写，三档各占多少；
PR 第一次过 review 的比例。

我不建议把"每人每周 AI 使用时长"当核心指标——这很容易变成 Goodhart 反模式的下一个候选。

要投入的基础设施：LLM Proxy、MCP server 部署、GitHub App 订阅、CI 资源、Testcontainers 运行所需的并发额度。这些通常不是一次性折腾完就结束，而是后续还要持续维护。

要主动管的风险：comprehension debt。Shopify 在上面的采访里明确提醒过，工程师仍然需要理解自己工作层之下两三层的东西。AI 写得快但团队不理解的代码，很可能只是技术债换了个入口；至少在岗位要求里，“理解 AI 产出的代码"应该被写清楚。

Tech Lead / 架构师#

核心动作：把脑子里的隐性规则迁到工具里。

把团队过去几年沉淀的"老人才知道"的规则一条条码到 architecture/*Test.java 里，通常会比继续靠口口相传或只写 wiki 更划算。
维护 CLAUDE.md / AGENTS.md / Skills，在我看来已经不是"纯文档工作”，而是影响 agent 可信度的交付物。它们腐化得越快，agent 的输出越容易漂移。
ADR 既是给人看的，也是给 agent 看的。每条架构决策都让 agent 能在第二次迭代里读到"为什么”。
主动设计对抗性验证：Writer/Reviewer 双 session、Claude 主写 + Codex 二审、关键模块强制人审。不要相信单一 agent 的输出。

IC（个人贡献者）#

身份可能会从"代码作者"部分迁到"agent 的编排者 + 验证者"。这是很多工程师感受最深的变化之一，也是争议最大的地方。

要主动培养的能力：

在 agent 参与度较高的链路里，先把测试写明往往比急着补实现更重要。在 TDD-first 模式下，测试是 spec 的可执行版本，agent 的对错很大程度上由测试判定。
读懂 stack trace、读懂 mutation report、读懂 ArchUnit 报告。不是读懂 agent 的解释，而是读懂底层信号。
写 SKILL.md / subagent 的能力。把自己反复教 agent 的话沉淀成可复用资产。Anthropic Skills 和 GitHub copilot-instructions.md 都是入口很低的格式。
trust-but-verify 的肌肉记忆。Anthropic Best Practices 原话：“Always provide verification (tests, scripts, screenshots). If you can’t verify it, don’t ship it.” 这话给 IC 也成立。
批判性技能：识别 AI 常见的模式化错误（IDOR、N+1、Kafka in TX、mock 一切），知道哪些场景模型通常不可靠。

会逐渐淡化的事：

手工 boilerplate（CRUD、DTO、controller stub）；
反复贴上下文给 AI；
写超长 prompt 试图让 AI"记得"规则。

跨角色共识#

无论身份是什么，下面这几条更像是团队需要尽早对齐的共识；如果长期对不齐，agentic 很可能会逆向破坏原本的交付质量：

不能只依赖 prompt 让 AI"记规则"。LLM 迟早会偶尔违反，确定性约束还是更适合落到 Hook + ArchUnit + CI。
AI 写得越多，理解债通常越值得警惕。要有意识地分配时间做"读 AI 代码"而不只是"评审 PR"。
测试是 agent 的锚点。删测试、跳测试、@Disabled 测试这些行为，在 agentic 团队里我会视为高风险，因为这通常等于主动削弱反馈回路。
机密不要进入 prompt。MCP 写权限严控，secret scan 前置 hook，PII 脱敏在 LLM Proxy 层。OWASP LLM Top 10 把 prompt injection 列为首要风险之一，比较适合按默认存在来防。
成本透明。每次 PR / 每个 feature 的 AI 成本应当能查到，否则讨论"值不值"是无源之水。

不是最佳实践，而是改进方向#

写到这里要诚实承认几点不确定性，避免把这篇文章读成"标准答案"：

模型能力还在快速演化。Claude 4.x、GPT-5、Gemini 2.5 在过去 6 个月里对 agentic 行为的支持差异不小；今天看起来有用的技巧，半年后可能被模型本身吸收。
公开数据点仍然偏稀疏。能拿到第一方数据的样本主要是 Anthropic、Rakuten、Shopify 和少数开源项目；中型团队的实证数据仍然有限。直接套用大公司经验前，最好先校准到自己的团队规模。
团队尺度的实证 case 还不多。很多公开博客是"明星工程师 / 试点小组"的经验，整团队推开后的协作摩擦、培训成本、组织阻力记录得并不充分。
工具/协议还会继续洗牌。MCP 目前看起来在趋于稳定，但 AGENTS.md 跨厂商规范还很新、Skills 生态也还在早期、Code Review GitHub App 仍是 preview——这些变化都可能让现在顺手的实现方式再调整一次。

所以我更愿意把这篇文章看成一份自检清单，而不是"照着 copy 的流程"：

我们现在卡在哪一个前提条件没满足？
我们打算先把哪个阶段的"重心迁移"做出来？
我们打算用什么指标证明 agentic 引入是有效的（而不是只让管理层"感觉很 AI"）？
我们会被哪一类风险（comprehension debt / 假绿测试 / 成本失控 / prompt injection）烧到？
我们打算在多大程度上把过去的「文档 + 人审」遗产迁到「git + 工具」？

每个团队的答案都会不一样。但如果团队持续回头问这五个问题，至少更不容易在热闹里失焦。后续我也会继续写，尽量结合一个具体的 Java/Spring Boot 项目，把上面提到的方向逐项落到 CLAUDE.md / .claude/skills/ / ArchUnit 规则 / GitHub Action 这些可执行产物上。

小结#

按我目前的理解，agentic 与"贴 Prompt"更像两种工作模式；如果团队想往前走，通常得先补仓库内 spec、可复现 verify、静态规则工具化、统一 LLM 入口、测试质量共识这些前提。
高质量交付的重心在每个阶段都可能发生位移：需求/设计更强调可机读契约；实现更依赖测试与 agent 编排；评审更适合机器先筛、人补主观判断；测试更看重行为正确性和真依赖；部署更适合 declarative artifact、渐进发布、可观测性。
团队转型上，我更倾向让管理层关注 reversion rate / DORA 指标并正视 comprehension debt；让 Tech Lead 把隐性规则沉淀进 ArchUnit 与 ADR；让 IC 把更多精力放到 agent 编排与验证上。
整套迁移没有标准答案；模型、协议、工具都还在快速演化。这篇文章更像学习笔记和方向梳理，不是落地手册——具体落地还需要结合团队现状继续试。

参考资料#

第一方公开实践：

协议与开源参考：

API / 测试 / 可观测性：

观点与方法论：

工程化引入 Agentic Workflow：一些关于质量与协作转型的观察

目录

背景#