Agent Coding 实战案例：从需求到归档的全流程工作实践

2301_80117363

481人浏览 · 2026-07-14 20:55:18

2301_80117363 · 2026-07-14 20:55:18 发布

Agent Coding 实战案例：从需求到归档的全流程工作实践

流程大家都会了，但执行质量差在哪？这篇文章用一个真实的功能优化案例，展示我在 Harness 架构下怎么通过管理上下文来保证 AI 输出质量——从需求理解到归档沉淀，每步都配实际用的提示词。

一、背景：大家的流程都差不多了

这段时间做 Agent Coding，发现大部分人都有差不多的开发流程了：读约束、描述需求、和 AI 一块探讨、找到执行方案、spec/task/plan、去执行 task、开发过程中用 AI 做 TDD、结束自动测试（交给 AI）、自己验证、归档、沉淀复用内容。

这些流程大家都会，所以不展开细讲标准流程了。

我这里要讲的是：在这些流程的执行过程中，怎么通过管理上下文来保证 AI 生成的高质量内容。 侧重点在开发过程中，怎么管理上下文来保证整个需求到闭环是清晰的一个流程。

我认为把整个功能开发的主方向放在会话里，不仅 AI 方便处理开发流程，更能帮助我在开发的时候理清思路，保证开发的节奏和质量。

二、为什么是管理上下文，而不是压缩

各种约束文档、各种 skill、各种描述——这些在我们刚罗列好准备执行 Task 的时候，窗口可能就到了 40%-50%。
在这里插入图片描述
我早期使用 /compact 去压缩，发现一个很直接的问题：失去智商。需求不理解，bug 改不明白，越改越混乱。

原因是什么？压缩是依靠模型来做的，模型有注意力机制的限制，压缩后总会丢失一些信息。这些丢失的信息，可能就是你之前讨论过的关键决策、踩过的坑、达成的共识。模型对上下文的开头和结尾注意力最强，中间部分天然失焦——这在研究中叫 Lost-in-the-Middle。你把对话压缩成一份摘要放在中间，模型大概率不会认真读它。

所以我的策略变成了：不压缩，靠管理上下文来保证连贯性。 保证连贯性靠的是提示词缓存这些机制，我们不需要深入研究缓存的原理，只需要知道：管理上下文而不是压缩，就能保证连贯性和稳定的开发质量。

下面用一个实战案例，一步步说明我的工作流。

三、案例引入：一个真实的功能优化

就拿我要优化的一个功能来说明我的工作流。

功能描述：模拟器试验管理下，目试验构型配置里面，选择架次构型有实际构型和试验构型。导出差异报告的时候，Excel 的差异列应该显示出不同版本间当时加的版本描述的差异，而不是单纯的版本号差异。

当前的情况（问题：只显示版本号，没有显示版本说明）：

序号  构型项    构型需求  实际构型  构型差异
1     test     v1.0.1   v1.0.0   版本差异（需求:v1.0.1 实际:v1.0.0）

构型差异 只显示了版本号对比，没有告诉使用者这两个版本之间到底改了什么。

我想要的效果：显示版本间的变更描述。比如从 v1.0 到 v3.0，中间经历了哪些版本、每个版本加了什么功能，都列出来：

设备：飞控计算机
├── v1.0: "初始版本，包含基本飞行控制功能"
├── v1.5: "优化燃油效率控制算法，降低油耗5%"
├── v2.0: "增加自动驾驶功能，支持编队飞行"  ← 技术变更
└── v3.0: "增加抗干扰能力，优化雷达数据处理"

查询 v1.0 到 v3.0 之间的所有版本
返回: v2.0的readme + v3.0的readme
→ "v2.0: 增加自动驾驶; v3.0: 增加抗干扰"

零件设备的版本变化结构长这样：

设备：飞控计算机
├── v1.0
│   └── readme: "初始版本，包含基本飞行控制功能"
│
├── v1.5
│   └── readme: "优化燃油效率控制算法，降低油耗5%"
│
├── v2.0
│   └── readme: "增加自动驾驶功能，支持编队飞行"
│
└── v3.0
    └── readme: "增加抗干扰能力，优化雷达数据处理"

这是我对于功能优化的理解。理解后呢，先不着急去实现功能。

为什么不急？因为需求理解阶段是最便宜的纠错时机。你在纸上改一行描述，比你在代码里改一个模块轻松得多。理解到位了再动手，后面返工的概率会大幅降低。

这也是我为什么在这个阶段选择用 openspec 而不是 brainstorming 的原因——

brainstorming 适合「我大概知道要做个东西，但还不确定具体怎么做」的阶段，它会帮你发散思路、探索方案。但到了这一步，我已经理解了需求，需要的不是发散，而是结构化的执行方案。openspec 会直接输出 spec + plan + task，是一份可以交给 AI 执行的「施工图纸」。

简单说：头脑风暴解决「做什么」，openspec 解决「怎么做」。 需求理解清楚了，就该进计划模式。

四、Harness 架构：项目的「规矩」

我最近在尝试 Harness 架构下的 Agent Coding 工作实践。Harness 架构中有很多文档，对应着不同的执行标准、决策和约束。

在这里插入图片描述

这是我项目下的 CLAUDE.md 关键结构：

# ops-mgmt-platform
模拟器运行管理平台
AI 协作入口：先读本文档，再按需下钻。

## 知识地图
- 架构约束（模块依赖、技术限制）→ docs/architecture/
- 改动护栏（红区/灰区/安全区）→ docs/GUARDRAILS.md
- 跨模块契约（API 格式、认证、数据约定）→ docs/contracts/
- 完成标准 → docs/DONE.md
- 决策记录 → docs/decisions/
- 领域术语 → docs/GLOSSARY.md
- 构建/运行/验证 → docs/BUILD.md
- 业务流程 → docs/flows/

## 编码前必读
1. docs/GUARDRAILS.md — 确认改动安全等级（红区/灰区/绿区）
2. docs/architecture/service-map.md — 确认涉及模块
3. docs/DONE.md — 了解完成标准

## 编码约定
- 后端：Java 8 + Spring Boot 2.5 + MyBatis-Plus 3.5
- 前端：Vue 3.5 + Element Plus + Pinia 3
- 分页用 PageHelper，不用 IPage
- 接口返回统一用 AjaxResult / TableDataInfo

## 禁止事项
- 不得直接修改框架代码
- 不得硬编码密钥/密码
- 不得绕过认证

这些文档的作用就一个：让 AI 从「猜」变成「读」。 不读规矩的 AI 只能靠猜，猜不准是常态。读了规矩的 AI 知道项目的边界在哪、接口怎么写、什么能动什么不能动。

好，准备工作做完了，开始走完整的工作流。

五、完整工作流：一步步走过来

下面用这个案例走一遍完整的 9 步工作流：

Step 1：读 GUARDRAILS，确定影响范围

在这里插入图片描述

下面是计划模式和头脑风暴对同一提示词对比

在这里插入图片描述
这个计划模式定位是对的

在这里插入图片描述
这里头脑风暴定位错了,但是提示所有无关大雅,后续补充内容

这里是计划模式和superpower头脑风暴的结果对比,这里superpower给出的定位代码就是错误的,需要手动调整。
补充,这里简单展示,还有一些需求沟通
在这里插入图片描述

读一下 GUARDRAILS 确定影响范围

这步是整个流程的起点。GUARDRAILS 把改动区域分为三级：

区域	含义	后续操作
red 区	核心模块，改动影响面大	必须详细分析影响面，可能需要团队评审
gray 区	灰色地带，需要判断	写清影响面说明，确认不影响其他模块
green 区	安全区域，改动局部	正常开发流程

这步决定了后续所有操作的谨慎程度。如果 AI 判断错了区域，后面的操作节奏就全乱了。

读完 GUARDRAILS 后，要口头确认属于哪个区域再开始编码。这是 CLAUDE.md 里写死的规则——不确认就不动手。听起来多此一举，但这一步强制你和 AI 达成共识，避免后续「我以为是 green 区放心大胆地改，结果是 red 区影响了一堆模块」的情况。

Step 2：读相关文档（架构、契约、业务流程）

确定区域后，让 AI 读相关的文档——服务地图、契约、业务流程。

在这里插入图片描述

这些文档让 AI 理解改动的上下文：涉及哪些模块、接口约定是什么、业务流程怎么走。AI 带着这些上下文去分析需求，比「裸聊」要准确得多。

Step 3：用 openspec / brainstorming 生成提案

在这里插入图片描述

用 Superpower 的 openspec 和 brainstorming skill 生成提案。提案会包含 spec（规格说明）、plan（执行计划）、task（任务拆分）。这一步是 AI 基于前面读到的所有上下文，输出结构化的执行方案。

为什么这里用 openspec 而不是 brainstorming？前面说过，brainstorming 是发散思维用的——「我有个模糊的想法，帮我理清楚」。但到了这一步，需求已经理解清楚了，约束文档也读过了，需要的是一份结构化的执行方案，不是更多的创意。openspec 直接输出 spec（我要做什么）+ plan（分几步做）+ task（每步的具体任务），是一份可以直接执行的「施工图纸」。

如果你的需求还不明确、不确定方案该怎么选，那应该先用 brainstorming 探索。但一旦方向确定了，就该切到计划模式，用 openspec 把方案固化下来。

核心检测这几个文档的内容.

Step 4：审核提案，拆分 Task

提案生成完会有 spec、plan、task。审核一下关键点，特别是前面提到的影响范围对应的点是否符合预期，是否会影响到其他模块的正常运行。

在这里插入图片描述

审核通过后，发以下提示词拆 task：

审核通过。帮我拆 task，要求：

每个 task 标注 GUARDRAILS 区域

每个 task 先写测试再写实现（TDD）

每个 task 可独立验证

如果涉及 docs/contracts/ 里定义的契约，要注明

这部分也可以在提案中说明让子 agent 并行去处理，你可以分析一下任务类型由自己决定。

补充说明：多 Agent 子 Agent 节省窗口大小的原理

子 Agent 有自己独立的上下文窗口，不占用主窗口的空间。主窗口只接收子 Agent 返回的结果摘要，不接收完整的推理过程。打个比方：你是项目经理，子 Agent 是执行人员——你只看报告结果，不需要看他的全部工作日志。这样主窗口的上下文始终保持简洁，不会被子 Agent 的详细推理过程撑爆。

核心原则：保证主对话窗口保持简洁，避免信息过载，专注于核心内容。

Step 5：TDD 实现

你认为可以了再发：

拆分没问题。按 task 顺序 TDD 实现，从 Task 1 开始。
遵守 docs/architecture/constraints.md 的编码约束：

分页用 PageHelper 不用 IPage

接口返回 AjaxResult / TableDataInfo

字段命名遵循 docs/contracts/data.md 的约定

或者你项目的编码规范、约束要求。把具体的编码约束写清楚，AI 就不会自己造轮子。

Step 6：处理问题——/branch 和 /fork

如果实现完成、测试通过后，你发现效果和预期的不同，该如何处理？

先不要着急去修改代码。 用 /branch 和 /fork 去处理。

补充说明：/branch 和 /fork 的区别

/fork 是 /branch 的别名（alias）。在 v2.1.77 版本中，/fork 被正式更名为 /branch，此后 /fork 作为别名继续存在。功能上完全没有区别。

使用建议：

需求实现有大方向问题 → 用 /branch，在分支上处理，结束后回到主分支

小 BUG → 用 /fork。原因是 /fork 后接任务描述，我们还在主对话中，分支结束后内容会直接补充进主对话，使用更便捷

本质是同一个命令，选哪个取决于你的使用习惯。我习惯小问题用 /fork，大改动用 /branch。

用这种方式都是为了维护我们的对话窗口，避免信息过载，专注于核心内容。

Step 7：手动验证

经过改需求或修 BUG 后，再回到主分支，继续处理下一个任务。

我们去手动验证有没有问题。如果有，再继续用 /branch 或 /fork 处理。没有问题后，进入下一步。

Step 8：Code Review

没有问题后，发以下提示词：

手动验证通过。按 docs/DONE.md 逐条自查，然后跑 code-review。
重点检查：

GUARDRAILS 灰区的改动有没有说明影响面

测试是否通过

代码注释是否完整

有没有违反 docs/contracts/ 的约定

有没有硬编码的密钥/密码

如果有代码修改也要告诉 AI 修改了哪些文件，让它去检查一下再跑一下测试别漏掉了。如果没有，就直接跑 code-review。

⚠️ Tip：code review 的 skill 和项目的 code review skill 容易混淆，使用时要明确指定是哪个，不然容易触发到别的 skill。还有很多 skill 是连着触发的——你让它做 A，它自动触发了 B，B 又触发了 C。描述的时候尽量告诉 AI 得到你当前想要的东西就停下来，不要让它自己去触发其他 skill。描述要详细、准确、具体、明确。

结束后把 CR 报告里面有问题的，用 /branch 或 /fork 去处理。

Step 9：归档沉淀

通过后发以下提示词，进行沉淀归档：

跑 openspec verify，对照 proposal 里的验收标准逐条检查。
同时检查是否符合 docs/contracts/ 的约定。
验收通过。判断这次改动有没有需要回写 harness 的：

新的技术决策？→ 写 docs/decisions/

新的业务术语？→ 写 docs/GLOSSARY.md

新的跨模块契约？→ 写 docs/contracts/

GUARDRAILS 需要调整？
然后归档。

⚠️ 注意：归档的 skill 会后续自动触发提交代码，我们最好明确在归档完成后，确认一下是否需要提交代码。不要让它自动提交了你还没准备好的东西。

六、发现的问题和思考

走完整个流程，有几个问题一直在脑子里转。

Skill 的触发混乱

不同版本、不同人使用的 skill，有很多相似的。怎么去找到最适合的 skill？比如 code review，项目有自己的 review skill，插件也有 review skill，还有很多其他来源的 review skill——你输入「帮我 review 一下」，它触发的是哪个？你可能根本不知道。

还有就是 skill 连着触发的问题。你让它做 A，它自动触发了 B，B 又触发了 C。这种连锁反应不仅浪费上下文窗口的空间，还可能偏离你的原始意图。我现在的做法是：在描述里明确告诉 AI「做完这一步就停下来，不要自动触发其他 skill」。但这终究是个 workaround，不是根本解法。

Harness 架构的设计约束

什么样的算是危险影响范围，什么样的算是安全影响范围？GUARDRAILS 把改动分成了 red/gray/green 三个区域，但仅靠这个分区，AI 判断出来的危险影响范围和安全影响范围是否准确？

举个例子：你在 gray 区改了一个接口的返回字段，看起来是个小改动。但这个接口被三个其他模块调用，其中一个模块对这个字段有硬编码的依赖——这种跨模块的影响面，AI 能不能判断出来？

这是需要持续校准的问题。你不能完全信任 AI 的判断，但也不能每次都人工审查所有改动。找到一个平衡点，可能是后续 harness 设计的一个方向。

决策和文档的沉淀

什么样的决策可以沉淀？沉淀在哪？是由团队管理还是个人？你反复用的决策和沉淀的内容是否一致？

更深层的问题是文档的熵增。文档不断积累，总会出现一些问题：

文档的重复：同一个决策在不同文件里写了两遍，改了一个忘了另一个
文档的冲突：两个文件对同一个约定的描述不一致，AI 不知道该信哪个
文档的过期：代码改了，文档没跟着更新，AI 读了过时的文档自信地写出错误的代码

代码量小的时候，这些问题不明显。但代码量大了，文档管理的问题就越来越突出。知识腐化是我认为后续需要重点考虑的问题——当你的 harness 文档和实际代码之间的差距越来越大，文档不但不能帮助 AI，反而会误导它。

七、未来优化方向

基于这次实践，我看到几个可以优化的方向：

Skill 管理：标准化 skill 的版本控制和质量评估。不同来源的相似 skill 需要有一个筛选机制，不能让 AI 自己猜该用哪个。Skill 的触发链也需要控制——哪些 skill 可以自动联动，哪些应该隔离。

Harness 设计：探索影响范围的自动化判断。不能完全依赖 GUARDRAILS 的静态分区，需要结合代码依赖分析、调用链追踪来动态评估改动的影响面。

文档治理：建立防熵增机制。定期审查文档的准确性和时效性，检测文档之间的冲突和重复，清理过期内容。这可能需要一个专门的文档健康度检查流程。

上下文管理：进一步探索 Prompt Caching 和挂载策略，把约束文档的固定开销压到更低。目标是在开始改代码前，把上下文占用率从 40%-50% 压到 15% 以下。

回顾

回到最开始的问题：为什么管理上下文而不是压缩？

因为压缩是被动的——等窗口满了再压缩，信息已经丢了。管理是主动的——从第一步开始就控制什么进入上下文、什么留在外面。

9 步工作流的核心，每步一句话：

读 GUARDRAILS → 确定区域，决定谨慎程度
读文档 → 让 AI 理解上下文，从「猜」变「读」
openspec → 基于上下文生成结构化提案
审核 + 拆 task → 标注区域和约束，可交子 agent
TDD 实现 → 遵守编码约定，不自己造轮子
有问题 → /branch 或 /fork，不污染主窗口
手动验证 → 人确认，不能全信 AI
Code Review → 明确指定 skill，避免连锁触发
归档 → 回写 harness，确认后再提交

上下文是有限的，但好的工作流能把有限的上下文花在刀刃上。

AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

深入理解 AI Agent · AGENT #02：Agent 的四大核心机制，拆开来看每个都在干什么

AI Agent技术社区

MCP协议开发实战：从零搭建AI Agent工具链

本文介绍了MCP协议在AI工具链中的应用与实践。MCP协议旨在解决异构工具集成难题，为AI模型提供标准化、安全的工具调用接口。文章详细解析了MCP的核心架构，包括Server、Client、Transport等组件，以及通信流程与安全模型。通过实战示例，指导读者开发计算器和文件系统工具Server，并集成到Claude等AI客户端中。进阶部分展示了如何构建复杂工具链，包括API集成、数据库查询和多