源起
最近一直在忙着调试五线谱练习与实时演唱评测的 Flutter App + Node 后端。合唱谱子的播放，不同于一般的谱子，除了各种特殊情况需要处理，比如 tie group、tuplet、legato 等等，还得考虑各个声部的识别准确率和控制、时钟的准确和稳定等等，真是不同于一般的 App。
在整个项目的 AI 编程实践中，我自己也逐渐形成了一套workflow 来约束 AI，同时也方便我切换 AI，比如我从 Codex 切换到 Antigravity，也都能表现的比较稳定。
前几期，写了好多和 AI 编程、Harness、软件工程范式改变等等一系列文章，今天终于把我实际使用的 AI 工作流整理分享出来。
我的 Harness，就是用来约束 AI 行为的控制系统，也是一套工作流，又上下文、执行约束、验证闭环 组成的回路，基于 OpenSpec + SuperPowers。
硬性约束与治理：START_HERE.md 与 AGENTS.md 的分工
要让 AI 在工程中可靠地写代码，必须首先定义明确的规范与界限。通过核心文档，为 AI 建立上下文与硬性约束。
在实际执行中，AI 会话启动的唯一入口是 AGENTS.md（或 CLAUDE.md，不同 Coding Agent 的文件不同，但是都能相互读取迁移）。所有开发活动均由此文件展开，并引导至静态规格定义。
我的项目的树状结构与分工：
看到这里，肯定很多人就会疑问，为啥不是一个 AGENTS.md 就够了，还有什么 START_HERE.md，实际是上这两个文档分工明确，不能合二为一。也都采用渐进式披露的方式。
1. AGENTS.md（或 CLAUDE.md）：Agent 的会话运行时指南
这是专为 AI 编写的"行动指南"。它直接挂载在 AI 每次会话的运行内存中，约束 AI 的动态开发逻辑，一般也就 100-200 行，不会太长：
- 规定 AI 启动时的阅读顺序（先看本入口，再看能力规格）。
- 强制推行工程纪律，如 TDD 的编写步骤、日志规范与异常捕捉规则。
- 规定 OpenSpec 工作流的闭环流程与子代理评审门禁。
2. START_HERE.md：系统规格与架构知识图谱
该文档是整个项目的唯一入口与静态架构真源。它由 AGENTS.md 引导 AI 查阅。它不包含具体的执行步骤，而是以目录和规则的形式定义了系统的"静态物理边界"。它指向以下底层规范文档：
architecture_ssot.md：定义项目核心的六层架构边界（从 L1 语义输入到 L6 评测层）以及三个唯一真源（语义/播放/几何坐标）。这是整个Flutter 端的架构约束和唯一真源，是经过 1.5 轮重构之后才形成这样的架构，否则代码由 AI 乱堆的话，乱的几乎不可维护，就会完全失控了。interface_contracts.md：规范分层接口的类型契约与边界逻辑。每一层的契约，必须严格按照这个约定，如果代码中要增加新字段，必须文档先增加，代码才能添加，主要是为了防止 AI 随意发挥、自作聪明。Code Review 时候也会严格遵循。musicxml_playback_omr_capability_ssot.md：记录语义解析与播放表现的联动规则。
这些文档共同定义了"系统是什么"以及"绝对禁止做什么"。修改代码时，如果触碰这些静态边界，AI 必须停止并与人类确认。
为什么不能合二为一？
将两者合并会导致严重的"上下文膨胀"与 AI "注意力偏移"。
静态的架构定义与接口契约数据量庞大，而 AI 会话的上下文窗口与注意力聚焦度有限。如果将系统规格与行动指南混写在一个文件里，庞杂的底层代码细节会污染 AI 的工作内存，导致 AI 在执行任务时产生指令漂移，遗忘关键 of TDD 守则或评审门禁。说人话，就是渐进式披露和省 Token 、以及减少上下文窗口。
因此，两者的分工是：AGENTS.md 负责会话入口，告诉 AI "如何行动并自我纠偏"；而 START_HERE.md 则是 AI 在行动过程中随时按需查阅的"系统法典"。这种设计保持了 AI 工作上下文的纯净。
另外，Google Stitch 制定的 DESIGN.md 则属于 UI 与交互的垂直法典，它规定了颜色 Token、深色工作台与暖色谱纸的对比规范，并锁定了用户界面"去引擎化"的命名原则。这是 Google Stitch 设计工具最新的规范，我也使用了起来，因为涉及到 UI，由 DESING.md 单独定义 整个项目的 UI 规范和约束。
实战演练：从脑暴到三阶段交付
按照完整的使用路径，来走一遍。
1. 使用 SuperPowers 脑暴 PRD
开发伊始，对话框中输入 /brainstorm 指令，激活 SuperPowers 的 Brainstorming 工具链。AI 结合已有的 DESIGN.md 设计规范与曲谱渲染交互原型，比如我要实现循环播放和评测能力，通过多轮对齐，讨论并输出了完整的混音器主功能 PRD。
2. 三阶段路线图规划
为了降低交付风险，我一般将大的 PRD 拆分为三个渐进阶段：
- Alpha 阶段（核心模型与时钟）：实现时钟控制器与播放状态的统一流分发，内部的每个 Stage 都是一个 OpenSpec Change。
- Beta 阶段（曲谱交互与循环）：实现小节点击选中、A-B 循环与视觉高亮同步，内部的每个 Stage 都是一个 OpenSpec Change。
- Release 阶段（演唱评测与反馈）：集成麦克风音频分析、演唱音高评测投影覆盖层及打分卡片，内部的每个 Stage 都是一个 OpenSpec Change。
每个阶段的每个具体任务，都严格映射为一个独立的 OpenSpec Change。
3. OpenSpec 变更三部曲
每个 OpenSpec 变更的 tasks.md 中，除具体的代码编写任务外，尾部必须包含三道质量门禁：
- 第一步：Implementation Report（实现报告）：AI 回填完整的实现文档，记录代码 Diff 摘要、修改的文件、执行的测试命令与凭证，并明确指出被延期的非本变更范围事项。
- 第二步：Subagent 循环式 Code Review（子代理评审循环） ：AI 启动一个独立的、无上下文污染的 Subagent，基于项目架构规范对代码变更进行严格审查。子代理必须给出明确结论。一旦发现不合规项（如在 UI 层直接调用播放器 API 或遗漏异常日志），子代理输出拒绝结论，AI 必须修改代码并重新发起评审，直到最终取得
PASS结论。这里其实是一个类似 /goal 效果的设定，让主 agent 必须拿到 subagent pass 的结论，才算完成实现，否则就一直 subagent review、主 agent 修改的过程。 - 第三步：Human Review Gate（人类验收门禁） ：代码通过子代理评审后，AI 将任务移交给人类（就是我自己）。AI 会根据变更的特征，提示人类需要重点人工测试的体验指标（如"请戴耳机听下切歌时的爆音情况"或"核对原稿模式下高亮遮罩的对齐精度"）。人类输入
APPROVED后，该变更方可归档。
极简体验：一句指令驱动的开发回路
我在和 AI 脑暴完之后，形成了主 PRD，拆分 Alpha、Beta、Release 以及各个 Stage 的 Change 之后，真正实现每个 Change 的时候，我就不希望再输入一大段话，哪怕多一个字我都不想输入了。所以，我，人类，只需要在对话框中输入一句指令：
"实现 openspec change
perf-runtime-01-model-foundation"即可。我不喜欢多写字，也不习惯语音输入。
AI 将独立完成剩下的工程自循环。
自动化开发流程图
然后，就是 AI 主 Agent 各种忙活了，内部各种调用的序列图如下：
在这个自循环流水线中，人类不再需要跟踪零散的文件修改，也无需手动拷贝测试日志。AI 凭借本地工程环境中的测试套件与独立的子代理评审机制，在提交前完成了质量过滤。人类确认归档后，AI 申请执行 git commit 与 git push 进行代码入库。
后续的客户端 CI、CD（各平台编译、构建、分发上架fastlane 接入等），会后续继续完善。
这个方案我实践了一段时间之后，AI 的幻觉率和漂移，是大大减少了。也让我省事了很多，但是很多调试不是一次性完成，一些复杂的效果，有多个方面的因素，还是得不停的修改和迭代。不过，这比最早期的时候，让我几乎推翻和大量重构，已经好了太多太多，现在的改动都能局限在一定范围内，不担心把整个架构给我搞乱。
是的，这个方案的自动化程度很高，你没看错，有个很大的缺点：费 Token！