前言：上一篇聊了 # superpowers：agentic skills框架，vibe coding中的软件工程！ 如何用 Skill 约束 AI 的单任务流程。但用久了我发现，流程约束只解决了一半问题——AI 在单个任务里走对了流程，放到整个项目里还是会犯重复错误。这篇文章聊聊我怎么从"约束 AI 的行为"升级到"约束 AI 的环境"，以及在 MuseMVP 和 SVeditor 里踩过的几个真实坑。
上一篇的superpowers聊到哪了
之前写过一篇关于 superpowers 的文章，核心观点是：Vibe Coding 不能只靠感觉，得给 AI 套上流程——先问需求，再写计划，用 TDD 驱动实现，完成前跑验证。
这套东西我一直在用，确实有效。
但用了一段时间之后，我发现了一个新问题：superpowers 解决的是"单个任务怎么做对"，但没解决"为什么同一个错误会反复出现"。
举个例子。我在 SVeditor 里加一个编辑器工具栏功能，AI 走了完整的 brainstorm → plan → TDD 流程，单次执行没问题。但下次我让它改另一个工具栏组件，它又把状态管理逻辑放错了位置。
问题不在流程——流程走对了。问题在于：它不知道我的项目里，哪些逻辑该放 UI 层，哪些该放 Service 层。
这就好比一个新员工，你给他培训了标准工作流程（先确认需求、再写方案、最后测试），但他对公司内部的部门分工和历史决策一无所知。流程再好，还是会犯组织层面的错误。
所以我开始想：除了流程约束，是不是还需要一层环境约束？
流程约束 vs 环境约束
我把 AI 编程的约束体系分成两层：
流程约束是 superpowers 干的事——对单个任务的执行步骤做强制规范。比如"修 bug 必须先复现再定位再修复"，"完成前必须跑验证"。这一层解决的是"AI 怎么干活"。
环境约束是另一层——对项目本身的结构、规范、记忆系统做设计。让 AI 一进入项目，就能读懂上下文，知道什么该做什么不该做。这一层解决的是"AI 在哪干活、为谁干活"。
两层缺一不可。
只有流程约束没有环境约束，AI 单次任务执行得很好，但跨任务的知识不会积累，同一个坑会反复踩。
只有环境约束没有流程约束，AI 知道项目的规则，但执行时可能跳过关键步骤——需求没确认就开始写，测试没跑就说完成。
流程约束管的是"步骤"，环境约束管的是"上下文"。两者叠加，AI 才能在你的项目里稳定工作。
我在项目里实际做了哪些环境约束
说几个我在 MuseMVP 和 SVeditor 里落地的具体做法。
AGENTS.md：给 AI 写的项目宪法
这个东西我上一篇没提，但现在已经是我每个项目的标配。
AGENTS.md 放在项目根目录，不是给同事看的文档，是给 AI 看的操作手册。内容很简单，500 字左右：
- 目录结构各层是干什么的（
ui-components/放展示组件，business-hooks/放业务逻辑） - 命名约定（组件用 PascalCase，工具函数用 camelCase，API 路由用 kebab-case）
- 绝对不能做的事（不能直接改
schema.prisma，不能在 UI 层写数据库查询）
我第一版写了 2000 多字，把每个模块都介绍了一遍。结果发现 AI 根本不看——上下文太长，关键信息被淹没了。砍到 500 字之后效果反而好了。
AGENTS.md 不是越详细越好。写太多等于没写——AI 的注意力也会被稀释。只写最核心的分层规则和禁区，500 字够了。
DECISIONS.md：项目的决策记忆
AI 每次跑任务都是"临时工"，没有历史记忆。上一个 PR 里为什么选了 Zustand 而不是 Redux？为什么认证用的是 session 而不是 JWT？这些决策如果不记录，AI 下次接活就会重新做一遍——大概率做出不同的选择。
所以我现在维护一个 DECISIONS.md。每次做完一个功能，花两分钟把当时的决策逻辑记下来。不需要写很长，格式就是：
## 2026-05-15 编辑器状态管理方案
- 选了 Zustand，没选 Redux
- 原因：编辑器状态更新频率高，Redux 的 dispatch 流程太重
- 如果未来需要时间旅行调试，再考虑切 Redux
AI 下次接相关任务时，会读这个文件，不会再做重复的决策。
目录语义化：让 AI 自己认路
这是我踩坑最多的地方。
早期项目里有个 utils/ 文件夹，里面塞了 UI 工具函数、数据处理逻辑、常量定义，什么都往里放。AI 看到这个目录名，根本分不清该往哪放新代码。
后来我做了拆分：ui-helpers/ 放 UI 相关工具，data-transforms/ 放数据处理，constants/ 放常量。目录名本身就是语义化的——AI 看到名字就知道该往哪走。
效果很明显。之前反复出现的"代码放错层"问题，拆完目录之后基本消失了。
测试即验收标准：TDD 2.0
以前写测试是给自己看的，现在写测试是给 Agent 看的。
区别在哪？人能容忍模糊的测试描述——"组件应该正确渲染"，人知道什么意思。AI 不行，它需要精确的断言："输入为空时显示 placeholder，有值时显示值，超过 100 字符时截断"。
我现在在 Agent 动手之前，先写好 E2E 测试用例。不是为了"测试驱动开发"那个教条，而是给 AI 一个客观的验收标准：跑不过测试就不能提交。 用法治代替人治。
测试在 Harness Engineering 时代的作用变了：它不再只是质量保障工具，它是 Agent 能否自主运行的基础设施。没有测试，就没有反馈循环；没有反馈循环，Agent 就无法自校验。
现在个人写任何代码，TDD驱动开发已经是必备的一个流程了，它保证了代码质量的健壮性，能够杜绝开发一个功能另一个已有的功能出bug。
实际工作流SOP
把这些东西串起来，我现在的日常开发流程大概是这样的：
- 接到一个需求，我先在 prompt 里调用 superpowers 的
brainstorming，让 AI 先问清楚边界 - AI 读取 AGENTS.md，了解项目结构和规范，知道当前任务在哪个上下文里
- AI 读取 DECISIONS.md，了解历史决策，避免做重复选择
- AI 写实现计划，调用
writing-plans，我审一遍（结合superpowers） - AI 开始实现，因为目录是语义化的，它自己知道代码该放哪
- AI 跑测试，测试就是验收标准，跑不过就自己改
- AI 调用
verification-before-completion，用真实证据（测试、构建、浏览器）确认完成 - 审 PR，合并后把关键决策写进 DECISIONS.md，这里我一般交给claude模型或者codex模型，让这些高级模型审查pr，把最后的关。
推荐Cursor的pr-review-canvas，这个pr审核特别细致并且可视化极高
踩过的几个坑
听起来很美好，但落地过程坑不少。
坑一：环境约束写成了一次性文档。 AGENTS.md 和 DECISIONS.md 不是写完就放那的。项目在变，这些文档也得跟着更新。我现在给自己定了一个规则：每次 PR 合并，花两分钟检查一下这两个文件需不需要同步更新。
坑二：上下文裁剪没做好。 项目大了以后，把整个仓库丢给 AI 是不行的。我写了一个脚本，每次只提取当前任务相关的 Types、Schema 和相邻文件。这个裁剪动作本身花了我一个周末，但效果值得——AI 的输出质量明显提升，因为它不再被无关信息干扰。
坑三：过度约束导致 AI 变"笨"。 一开始我给 AGENTS.md 加了太多规则，结果 AI 变得畏手畏脚，简单的事情也要反复确认。后来我砍掉了大部分规则，只保留最核心的几条。约束是让 AI 更准，不是让 AI 更慢。
环境约束的设计原则：精确、可执行、适量。宁可少写几条关键规则，也不要写一堆 AI 会忽略的废话。
回到那个更大的问题
上一篇聊 superpowers 时，我说"Vibe Coding 不能只靠感觉，最后还是要回到软件工程"。
现在我想把这句话补完：
软件工程本身也在变。
以前我们说软件工程，指的是 spec、plan、TDD、code review、CI/CD 这些流程。这些流程是给人设计的——人来执行，人来检查。
现在 AI 能执行这些流程了，但它需要的"工程"跟人需要的不一样。人能理解模糊的需求、能靠经验做判断、能记住上周的技术决策。AI 不行。AI 需要精确的规则、明确的上下文、可执行的验收标准。
所以我在做的，本质上是为 AI 重新设计软件工程的基础设施。superpowers 管流程，AGENTS.md 管上下文，DECISIONS.md 管记忆，自动化测试管验收。每一层都在回答同一个问题：怎么让 AI 在我的项目里稳定地、可预期地工作。
有人把这套东西叫 Harness Engineering。
如果你现在就想开始
从三件事做起，一个下午能搞定：
- 写一份 AGENTS.md。 500 字，只写目录结构含义、命名约定、禁区。别写多。
- 跑通一套自动化检查。 lint + type-check + test，一键跑完。这是 Agent 的第一个治具。
- 在上一篇的基础上，把 superpowers 的流程约束和环境约束串起来。 流程管步骤，环境管上下文，两层叠加效果最好。
最小实践：AGENTS.md（环境约束）+ superpowers skills（流程约束）+ 自动化测试（验收标准）= Agent 在你项目里稳定工作的最小可行配置。
这两篇文章加在一起，基本就是我目前在 AI 编程上的完整方法论。上一篇管"AI 怎么干活"，这一篇管"AI 在哪干活"。两层都做好了，AI 才能真正从"偶尔好用的搭档"变成"稳定输出的工人"。
