🐴 给 AI 套缰绳：一个前端项目的 AI Harness 实战记录
用了半年 AI 编程助手，从"生成的代码一半要改"到"基本能直接用"，靠的不是换模型，而是花了几天时间写了一堆给 AI 看的文档。
背景
不管你用的是 Copilot、Cursor、Windsurf 还是 Cline，大概率都遇到过这个问题：AI 写的代码语法没错但规矩全不对。
它不知道你项目里该用哪个请求封装，不知道你的国际化流程是什么样的，不知道加一个页面需要改哪几个文件，不知道哪些目录的代码已经废弃了不能参考。
这不是哪个工具的问题，是所有 AI 编程助手的共性问题------它们的训练数据里没有你的项目规范。
于是我开始做一件事：把这些规矩写成 AI 能读懂的文档。
现在主流的 AI 编程工具都支持某种形式的"项目级上下文注入"------Copilot 有 AGENTS.md 和 custom instructions，Cursor 有 .cursorrules，Windsurf 有 .windsurfrules。叫法不同，思路一样：给 AI 提供项目专属的知识，让它按你的规矩写代码。
我做了什么
整体就三层东西：一个入口文件、一组 SOP 文档、几个领域 Skill。
第一层：根目录放一个项目级指令文件
这是 AI 进入项目后第一个读到的文件（在 Copilot 生态里叫 AGENTS.md，在 Cursor 里叫 .cursorrules，本质一样）。我在里面放了四块内容：
1）核心原则------两段话，告诉 AI "先读代码再改代码"和"不确定就问别猜"。这两条直接改变了 AI 的行为模式。没加这个之前，它会参考训练数据里的通用写法直接输出；加了之后，它会先去读项目里的现有实现，再按现有模式写。
2）技术栈声明------一张表格，列清楚每个层面用了什么库。这是最基本的约束：声明了状态管理用什么、请求用什么、UI 库用什么，AI 就不会生成你不想看到的技术选型。
3）目录结构------每个目录的用途写一行注释。重点是标注了废弃目录"不要参考"------这条省了无数返工，因为 AI 搜索代码时很喜欢参考已有代码，如果参考到废弃模块就全完了。
4）文档索引------指向详细规范文档的表格。这是给 AI 的导航：用户说"加个页面"，AI 看到索引就知道该去读哪份 SOP。
第二层：写了一组高频操作的 SOP
每份对应一类高频操作。我挑的都是AI 最容易做错的事------不是因为难，而是因为涉及项目特有的约定。
新增页面 SOP：注册路由枚举 → 建目录 → 注册路由 → 写菜单配置 → 加国际化。5 个步骤，每步给了代码模板。重点写了两个坑：菜单配置必须是函数不能是常量（因为国际化是运行时加载的），以及布局组件怎么选。
API 对接 SOP ：定义类型 → 写 service hook → 组件消费。把三层结构固定下来。AI 之前最爱用 useEffect + useState 手动管请求状态，有了这份文档就会统一用项目约定的请求模式。
国际化 SOP：项目的翻译数据存在后端，前端运行时加载------这个流程比较特殊，AI 的训练数据里不可能有。SOP 里写清了从编写翻译到上传到验证的完整链路。
库引用规范：一张表列了每类用途该用什么库、禁止用什么库。这是最"暴力"但最有效的一份------AI 不再纠结选什么库，查表就行。
权限控制规范：不同场景对应不同的权限组件和写法，做成选型表。AI 之前要么不加权限，要么用错方式，现在查表对号入座。
代码规范：命名约定、框架最佳实践、样式选择。重点是用 🔴/🟢 对比标注了常见反模式------这种格式 AI 的理解率非常高。
安全规范：列了几条"碰了就炸"的禁止项------裸插 HTML、URL 注入、Token 放 URL 等。
第三层：写了几个领域 Skill
Skill 和 SOP 的区别：SOP 是通用流程，Skill 是某个特定领域的深度知识。
我写了这么几个：
管理页面开发 Skill：覆盖了表格组件选型、表单载体选择（几个字段用 Modal、几个用 Drawer）、CRUD 操作的完整交互模式（用什么确认组件、成功后刷不刷列表、Loading 状态怎么管）。本质上是把一个"做过很多管理页面的前端"的 pattern 认知全部结构化了。
复杂业务组件 Skill：项目里有个业务复杂度很高的可编辑表格组件。把组件位置、核心概念、对外 API、关键业务规则都写进去了。没有这份 Skill，AI 根本不可能正确修改这个组件。
DevOps 自动化 Skill：封装了常用的 CI/CD 操作命令。
文档同步 Skill：一个完整的自动化工作流------AI 读取代码变更 → 调脚本读现有文档 → 生成新内容 → 调脚本推送。用户说一句话就能自动跑完整个流程。
写这些文档时的几个心得
1. 文档是给 AI 看的，不是给人看的
给人看的文档重在解释"为什么"，给 AI 看的文档重在说清"怎么做"。
我的做法：步骤编号 + 代码模板 + 选型表格 + 反模式对比。长段落叙述尽量少，结构化信息尽量多。
2. 反模式标注比正确示例更重要
AI 最需要知道的不是"怎么做是对的"------它有一万种写法。它需要知道的是"你这个项目里哪些做法是错的"。
🔴/🟢 对比格式效果极好，AI 对这种 pattern 的识别率非常高。
3. 不用面面俱到，从"AI 最容易做错的事"开始
我是按这个优先级排的：
- AI 几乎一定做错 → 写详细 SOP
- AI 有时做错 → 写一句约束
- AI 本来就能做对 → 不用写
比如写一个简单的组件不用教，但"加一个页面涉及多个文件的联动注册"一定会错------这就需要 SOP。
4. "不要参考"比"请参考"更有用
明确标注废弃代码、过时写法，比推荐最佳实践更能减少返工。
5. Skill 的触发条件要写好
Skill 的描述决定了什么时候被加载。写得太宽泛会导致不相关的请求也加载（浪费上下文窗口），写得太窄又容易触发不了。我的做法是列几个具体的触发关键词。
6. 文档和代码一样需要维护
代码改了 SOP 没更新，AI 按过时文档生成代码------比没有文档更糟。改了流程性代码时，同步检查相关 SOP 是否需要更新。
投入产出
实际花的时间：
- 项目级指令文件：半小时
- SOP 文档：陆续写了约一周（每份 1-2 小时，不是一口气写完的）
- Skills：按需写的，碰到 AI 反复做错的领域就写一个
效果：
- AI 生成代码的"首次可用率"明显提升，体感从 40% 到 80%+
- Code Review 中"规范类问题"大幅减少
- 新成员让 AI 帮忙写代码，产出质量和熟手接近
最大的收益其实是：这些文档同时也是给人看的规范------写完发现新人 onboarding 也方便了。
最后
AI Harness 说白了就是一句话：把你希望 AI 遵守的规矩，用它能处理的格式写下来。
不需要什么框架和工具，就是 Markdown 文件。放对位置，写对格式，任何 AI 编程助手都能读懂。
越早开始越好------每多花一小时写文档，后面就少花十小时改 AI 生成的代码。