AI Coding 工程实践：成为「循环之上」的工程师

记录在实际项目中使用 Claude Code 的实践，回答：对于研发工程师，"在循环之上"具体意味着什么，怎么做到？

目录

章节	说明
引言：你在循环的哪个位置	三种人机协作姿态
一、认知框架	影响半径、上下文工程、SDD
二、工程实践：构建驾驭系统	前馈控制、反馈控制、跨会话记忆
三、典型场景实践	功能开发、技术债、问题排查、知识沉淀
四、反模式手册	6 个常见陷阱与改法
五、感想	隐性知识显性化、规范是杠杆
六、上手路径	三阶段行动计划

引言：你在循环的哪个位置

Kief Morris 在《软件工程循环中的人类与 Agent》中提出：当 AI 越来越能干，人类应该站在哪里？

他给出了三个答案：

• 在循环之外（Vibe Coding）：人类只管"要什么"，把"怎么做"全交给 Agent
• 在循环之中（逐行审查）：人类紧盯每一行 AI 生成的代码，自己成为瓶颈
• 在循环之上（Harness Engineering）：人类构建和维护让 Agent 持续产出好结果的"驾驭系统"

大多数人目前处于前两种状态——要么过度信任 AI 导致质量失控，要么过度审查导致效率倒退。"在循环之上"才是正确姿态，但它需要一套方法论支撑。

一、认知框架：重新理解 AI 编程工具

1.1 AI 能做什么，不能做什么

Birgitta Böckeler 在《开发者技能在 Agent 编码中的角色》中，将 AI 的失误按影响半径分为三类：

影响半径	典型失误	反馈周期
提交时间	代码无法运行、问题误诊	分钟级，最容易发现
团队迭代流	过多前期工作、暴力修复而非根因分析	天级，需要代码审查才能发现
长期可维护性	冗余测试、缺乏复用、过度复杂	月级，最隐蔽、代价最高

核心结论：AI 在"提交时间"这个半径内的失误很容易被发现，但对"长期可维护性"的破坏是静默的。这正是需要有经验的工程师"在循环之上"的原因——不是去逐行审查，而是建立让 AI 不犯这类错误的系统机制。

1.2 上下文工程：AI 质量的真正杠杆

"上下文工程是精心策划模型所见内容，以获得更好的结果。" —— Birgitta Böckeler

Claude Code 的上下文体系分为四层：

CLAUDE.md / constitution.md   ← 全局规范（每次会话都加载）
Rules（规则文件）              ← 按语言/目录限定的规范（按需加载）
Skills（技能）                 ← 工作流指令（LLM 按需加载，或人工触发）
Hooks（钩子）                  ← 确定性触发的自动化动作

关键认知：提示词技巧是战术，上下文工程是战略。一次好的提示词只影响一次对话；一份好的 CLAUDE.md 影响所有对话。

1.3 规格驱动开发（SDD）：代码之前先写规格

Birgitta Böckeler 在《理解规格驱动开发》中定义了 SDD 的三个层级：

层级	说明
规格优先（Spec-first）	先写规格，再用 AI 实现，规格是当前任务的输入
规格锚定（Spec-anchored）	规格在功能完成后继续保留，用于后续演进
规格即源（Spec-as-source）	规格是主要产物，代码由规格生成（探索阶段）

在实践中采用的是"规格锚定"层级：每个功能都有 spec.md + design.md，提交到 git，作为后续迭代的上下文。

二、工程实践：构建你的"驾驭系统"

"在循环之上"的具体工作，就是构建和持续改进驾驭（Harness）。驾驭由两部分组成：

• 引导（Guides，前馈控制）：在 Agent 行动前预判并引导行为
• 传感器（Sensors，反馈控制）：在 Agent 行动后验证结果，触发自我纠错

2.1 前馈控制：让 AI 在开始前就知道边界

constitution.md（项目章程）

这是驾驭的核心。它不是"提示词"，而是不可变的工程原则。以一个基于 DDD 的 Java 项目为例，constitution.md 可包含：

- DDD 分层约束：OHS → Application → Domain ← Infrastructure（不得跨层调用）
- 测试纪律：集成测试必须使用真实数据库，不得 Mock
- 禁止过度设计：不实现用户未要求的功能（YAGNI 原则）
- 代码质量红线：函数 < 50 行，文件 < 800 行，嵌套 ≤ 4 层

关键设计原则：constitution.md 写的是"为什么不能这样做"，而不只是"要怎么做"。有了 Why，AI 在遇到边界情况时才能做出正确判断，而不是机械执行规则。

Skills（技能文件）

Skills 是"懒加载的工作流"——只在相关任务时才加载到上下文，避免污染全局：

Skill	触发场景	作用
speckit.specify	新功能开始时	将需求转化为结构化 spec.md
speckit.plan	spec 完成后	生成技术方案 design.md
speckit.implement	实现阶段	TDD 驱动的任务执行
systematic-debugging	遇到 bug 时	结构化排查流程
wiki-writer	需要写知识库文档时	知识库 CLI 操作规范

实践案例：通过 speckit 流程，将一个模糊的"表单字段缺失"问题，逐步澄清为：3 个用户故事 → 若干条功能需求 → 明确的技术方案（不新增接口、仅扩展 DTO）→ 可独立执行的任务列表。整个过程中，AI 在每个阶段都有清晰的"规格"作为输入，而不是在模糊指令下自由发挥。

2.2 反馈控制：让 AI 知道自己做错了

ArchUnit 架构约束测试

这是最重要的"传感器"。ArchUnit 在每次构建时自动验证 DDD 分层约束，一旦 AI 生成了跨层调用的代码，CI 立即失败。这是一个确定性的反馈机制，不依赖人工审查。

// ArchitectureTest.java 示例
@ArchTest
static final ArchRule domainShouldNotDependOnInfrastructure =
    noClasses().that().resideInAPackage("..domain..")
        .should().dependOnClassesThat()
        .resideInAPackage("..infrastructure..");

TDD + 全量测试门禁

在项目中，每次 push 前必须通过全量单元测试。这不只是"验证功能"，更是对 AI 行为的约束——AI 知道它生成的代码必须让现有测试通过，这个约束会引导它做出更保守、更兼容的实现选择。

Hooks（钩子）

Hooks 是确定性触发的自动化动作。例如：每次编辑 Java 文件后自动运行格式化；每次会话结束时自动保存上下文摘要到 claude-mem。这些是"不需要 AI 决策"的传感器，保证某些行为一定发生。

2.3 跨会话记忆：让驾驭随时间进化

"在循环之上"的另一个维度是时间轴。单次会话的驾驭是静态的；跨会话积累的驾驭才是动态进化的。

claude-mem 的三类记忆：

类型	内容	示例
feedback	工作方式的正负反馈	"集成测试不得 Mock 数据库（历史事故）"
project	当前项目状态和待办	"T-12 已完成，T-16 转化为规格文档"
reference	外部资源位置	"AI 编程研究报告的文档 ID 是 XXX"

关键实践：上下文恢复时查 claude-mem 历史会话，而非查任务管理系统工作项。任务管理系统记录的是"计划做什么"，claude-mem 记录的是"实际做了什么、为什么这样做"——两者差距往往很大。

三、典型场景实践

3.1 功能开发：speckit 全流程

适用场景：有明确需求、需要规范化实现的功能

流程：

speckit.specify → spec.md（用户故事 + 验收标准）
speckit.plan   → design.md（技术方案 + 数据模型 + API 契约）
speckit.tasks  → tasks.md（可独立执行的任务列表）
speckit.implement → TDD 实现每个任务
全量测试验证

"在循环之上"的体现：不是在逐行审查 AI 写的代码，而是在每个阶段审查中间产物（spec/design/tasks）。发现问题在规格阶段比在代码阶段便宜 10 倍。

3.2 技术债清理：有决策的清理，而非机械执行

案例：硬编码密码清理

表面上是"安全问题"，但实际决策是：这些密码是测试环境密码，本身无安全风险；安全扫描告警是真实问题（会卡 CI），但清理 Git 历史成本高且无必要；因此只清理当前代码文件，不追溯历史提交。

这是"在循环之上"的典型思维：不是让 AI 机械执行"清理所有密码"，而是先做风险评估，确定最小必要范围，再执行。

3.3 问题排查：可观测性优先

案例：某 CI 任务指标突然归零

根因是构建命令执行失败，但原有日志完全掩盖了这一事实。修复过程：

1. 先补充诊断日志（构建工具版本、机器环境、执行耗时）——这是改进"传感器"
2. 再定位根因、修复问题
3. 最后将"增加诊断日志"这个实践沉淀为规范——这是改进"引导"

"在循环之上"的体现：不是每次出问题都去排查，而是把每次排查的经验转化为更好的传感器，让下一次同类问题能自动暴露。

3.4 知识沉淀：自动化流水线

案例：Martin Fowler 生成式 AI 系列文章翻译（共 14 篇）

手工流程：找到文章 → 复制正文 → 翻译 → 上传知识库 → 处理图片

自动化流程：

提供 URL → curl 抓取 HTML（.paperBody 选择器）
→ Python 解析正文 → Claude 翻译
→ CLI 创建知识库文档 → 上传图片

这条流水线消除了所有人工操作节点。核心认知：自动化的价值不是"快"，而是消除人工干预点——每个人工干预点都是一个潜在的遗漏、错误或规范偏差的来源。

四、反模式手册

反模式 1：把 AI 当搜索引擎

现象：每次对话都从零开始，问完就关，没有上下文积累。

根因：没有意识到"驾驭"的存在——每次对话质量取决于当次输入，而非积累的系统能力。

改法：建立 CLAUDE.md + constitution.md + claude-mem 三层上下文体系，让 AI 在每次对话中都站在已有认知的基础上工作。

反模式 2：直接实现，跳过规格

现象：收到需求后直接让 AI 写代码，没有 specify → plan 阶段。

根因：把"快"理解为"立刻开始写代码"，忽视了需求理解偏差在实现阶段才暴露的高返工成本。

改法：先写 spec（要做什么、为什么），再写 plan（怎么做），再实现。spec 阶段的投入通常能节省 3-5 倍的实现阶段返工。

反模式 3：只记错误，不记正确做法

现象：claude-mem 里只有"不要这样做"的 feedback，没有正向确认。

根因：纠错是显性的（AI 做错了会被指出），认可是隐性的（AI 做对了默默接受）。

后果：AI 越来越保守，在有效方案上也会犹豫，因为它只记住了"踩过的坑"，没有记住"走通的路"。

改法：当某个方案被接受且效果好时，显式写入 feedback 记忆（正向确认）。

反模式 4：修复后不验证就提交

现象：AI 修改了代码，单测通过，直接 commit。

根因：混淆了"代码路径覆盖"和"用户操作路径验证"。单测验证的是代码逻辑，不是用户体验。

改法：涉及 HTTP 层的修改必须有集成测试或 E2E 验证。修复后先报告结果，等确认，再 commit。修复验证是"传感器"的一部分，不是可选步骤。

反模式 5：上下文工程过度膨胀

现象：CLAUDE.md 越写越长，塞入所有能想到的规则。

根因：把"规则越多 = 约束越强"当成直觉，但上下文过多会降低 AI 的有效性，且增加成本。

改法：CLAUDE.md 只放"每次会话都需要"的核心规范；其他规范按语言/目录拆分到 Rules 文件（按需加载）；工作流指令放到 Skills（懒加载）。上下文是有成本的，要精心策划，而非堆砌。

反模式 6：把规格当文档写，而非当合约写

现象：spec.md 写的是"这个功能大概做什么"，充满模糊表述。

根因：把规格理解为"说明文档"，而非"人类和 AI 的共同事实来源"。

改法：spec.md 中的每条需求必须有明确的验收标准（"给定……当……则……"格式）。模糊的规格会导致 AI 自由发挥，产生你不想要的实现。

五、感想：从"使用工具"到"工程化能力"

5.1 隐性知识的显性化

写 constitution.md 时，你必须把"我们的架构原则是什么"说清楚；写 spec.md 时，你必须把"这个需求到底要解决什么问题"说清楚；写 feedback 记忆时，你必须把"为什么不能这样做"说清楚。

这些"说清楚"的过程，本质上是在做知识管理——把存在于个人脑子里的经验、判断、约束，转化成可以被团队共享、被 AI 理解、被未来的自己复用的结构化信息。

5.2 规范是杠杆，记忆是复利

一条"集成测试不得 Mock 数据库"的规范，写入 constitution.md 只需要一行，但它能避免 AI 在每次生成测试代码时重蹈历史覆辙。一次 CI 指标归零的排查经验，沉淀为"诊断日志规范"后，让下一次同类问题的定位时间从两天变成十分钟。

规范的价值不在于约束当下，而在于消除未来的重复成本。 越早开始积累，复利效应越大。

5.3 "在循环之上"是一种工程师成长路径

从"逐行审查 AI 代码"（在循环之中）到"构建让 AI 产出好代码的系统"（在循环之上），这不只是效率的提升，更是工程师角色的转变：从执行者到系统设计者。

这个转变对经验丰富的工程师更有利——你的价值不再是"写代码比 AI 快"（这场比赛你已经输了），而是"你知道什么样的代码在三年后不会成为技术债"（这场比赛 AI 还差得远）。

六、上手路径

第一阶段：建立基础驾驭（1-2 周）

1. 为你的主要项目创建 CLAUDE.md，写入：技术栈约束、命令规范、分支命名规范
2. 创建 constitution.md，写入：架构原则（3-5 条）、测试要求、禁止事项
3. 开始使用 claude-mem 记录每次重要决策和 feedback

验收标准：新会话开始时，AI 无需重复解释项目背景即可开始工作。

第二阶段：引入规格流程（2-4 周）

1. 为下一个功能尝试 speckit 流程：specify → plan → implement
2. 将 spec.md 和 design.md 提交到 git，作为功能的决策记录
3. 在 CI 中加入架构约束测试（ArchUnit 或类似工具）

验收标准：功能开发的返工率明显下降；新人接手功能时有文档可读。

第三阶段：系统化驾驭工程（持续）

1. 为常用工作流创建 Skills（代码审查、问题排查、文档发布等）
2. 配置 Hooks 实现自动化（格式化、lint、上下文保存）
3. 定期回顾 claude-mem 记录，将有价值的 feedback 升级为 constitution 原则

验收标准：你的驾驭系统在你不在时也能让 AI 产出符合团队标准的代码。

参考资料

• 关联文档：软件工程循环中的人类与 Agent
• 关联文档：为 AI 编程 Agent 用户构建驾驭工程（Harness Engineering）
• 关联文档：开发者技能在 Agent 编码中的角色
• 关联文档：编程 Agent 的上下文工程
• 关联文档：../01 SDD/05 理解规格驱动开发：Kiro、spec-kit 与 Tessl