1 个人，0 行手写代码：我是这样复刻 OpenAI 工程框架的

大家好！我是瓜哥。前互联网技术副总裁，现在带队死磕 AI 编程。

3 名工程师，5 个月，约一百万行代码，1,500 个 Pull Request，人工编写的代码：0 行。

这是 OpenAI 工程师 Ryan Lopopolo 今年公开的一个实验数据。我第一次看到这组数字时，愣了几秒。不是因为震撼，而是因为一种熟悉感，这不就是我在本地一直在做的事吗？

说得更准确一点：我一直保持一个习惯，在项目里始终坚持 先规划再生成。在正式让AI生成代码之前，我会将项目强相关的 PRD-产品需求文档、tech-技术架构设计、UI/UX - 项目视觉定义都先定义和确认好，再开始生成代码。

在读了 OpenAI 关于「Harness Engineering」的理念，我发现它把这一套约束 AI，提升 AI 输出的体系，建设的非常完整和闭环。

于是，我把这套东西搬进了我自己的独立项目里实践。

项目背景先交代一下。

我在做一个叫 TypeFlow AI 的 AI 写作引擎，全栈 Next.js，用 Prisma 对接数据库，对接多个大模型供应商。开发节奏是我一个人使用 Codex 做规划，Antigravity（Google 的 AI 编程助手）做执行，目前已推进完成了 58 个开发任务，4万 多行代码。

产品首页

工作台页

这篇文章是我的实践记录，说说哪些地方真的管用，哪些坑我踩了之后才明白为什么要那样设计。

01 | 为什么 AI 老是在同一个地方栽跟头

① AI 看不到的东西，对它来说就不存在

这是 Harness Engineering 最核心的一句话，也是我在实践中体感最深的一条。

AI 在运行时能访问到的信息，只有代码仓库里真实存在的文件。你昨天在聊天框里跟它解释了半个小时的架构决策？它下次运行的时候完全不记得。

你在 Notion 里写的文档？它看不到。你脑子里默认的约束？更不用说了。

OpenAI 团队在文章里画了一张图，大意是：Slack 消息、Google Docs、人脑里的知识，对 AI 来说等于不存在。把这些信息固化成仓库里的 Markdown 文件，才算真正进入它的视野。

在这之前踩的很多坑，原因我现在才对上了号。

② 一个大 AGENTS.md 不是解法，是更大的问题

很多人的第一反应是：那我把所有规则都写进 AGENTS.md 不就行了？

OpenAI 团队也试过，失败了。上下文是稀缺资源，一个塞满规则的大文件会把任务、代码和真正重要的约束全部挤出去。

AI 最终的表现不是「严格遵守所有规则」，而是「随机在某些规则上做局部模式匹配」，而且你根本不知道它在哪条规则上走了神。

更糟的是，大文件会快速腐化。三个月后，你不知道哪条规则还有效，哪条已经过期，AI 也不知道。它变成了一个看起来有效的麻烦源头。

02 | 照着这套理念，我在真实项目里干了一遍

读完 OpenAI 的文章，我对照了一下自己项目里已经在做的事，框架上高度吻合。

不是巧合，因为这也是我反复实践跟AI协作，当前能搭出来最好的架子。

具体是怎么落地的，拆开说。

① GEMINI.md + index.md：宪法和地图分开放

我的项目里，GEMINI.md 充当的角色等价于 OpenAI 体系里的 AGENTS.md——但它只有 39 行，全是不可妥协的底线规则：禁止越权调用数据库、事实与意图必须分离、每次发现缺陷必须先更新文档再修 Bug。

与它配套的是 index.md，这是全项目的内容导航大纲。它不写规则，只写地图：ARCHITECTURE.md 在哪，QUALITY_SCORE.md 管什么，遇到安全问题去哪找约束。AI 每次执行任务的第一步，是强制读取 index.md，然后按图索骥找到对应的专题文档。

这和 OpenAI 的「目录地图」理念完全对应。

区别是我把两个职责拆成了两个文件：宪法管底线，地图管导航，互不干扰。

实践下来这个拆法比合在一起更干净，AI 的行为也更可预测。

② arch.test.ts 静态分层检查：把约定变成会报错的代码

我的系统有严格的单向依赖分层：Types → Config → DB → Repo → Service → API → UI。每一层只能向下依赖，不能越级。这条规则如果只写在文档里，AI 迟早会违反。

不是因为它不懂，而是因为它在解决某个具体问题时很容易局部最优，把规则忘在脑后。

解法是把这条规则写进了 __tests__/arch.test.ts。任何违反分层的导入语句都会直接让测试失败，跑 npm run verify 时自动阻断。

规则从「文档里的一句话」变成了「会报错的代码」。

OpenAI 团队用的是自定义 linter，思路一样：与其依靠约定，不如让工具帮你强制执行。

③ 知识库版本控制：不写进仓库的决策，当它不存在

项目走到 Phase 58，我有一套文档体系在支撑：ARCHITECTURE.md 记录架构决策，QUALITY_SCORE.md 是代码质量规范，RELIABILITY.md 防稳定性踩坑，SECURITY.md 管安全红线。

每份文档都有明确的 触发时机，什么情况下 AI 必须读它。

我在早期吃过没有这个的亏。

有次架构讨论在聊天里达成了一个共识，没有落地到文档里。

几天后 AI 处理相关功能时，把那个共识完全无视，按自己判断走了另一条路。等我发现的时候，已经有三个 Phase 的代码建立在错误的前提上。

03 | 我们做得不一样的地方

基本框架之上，项目的具体业务逼着你做出自己的取舍。我在 TypeFlow AI 里就遇到了三个 OpenAI 文章里没有直接覆盖的问题。

① 事实与意图严格分离：Research Pack vs Content Brief

TypeFlow AI 的核心链路是帮用户生成文章，所以有一个专门的架构决策：Research Pack 只放事实，Content Brief 只放意图，两者严格隔离，不能混放在同一个数据结构里。

Research Pack 存的是外部检索到的证据：标题、链接、摘要、发布时间、检索时间。Content Brief 存的是写作决策：角度、目标读者、风格、篇幅。

AI 在生成文章时特别容易把「我检索到的事实」和「我要怎么写」混在一起。一旦混了，历史记录就无法准确回放，模型在引用事实时也会出现幻觉。

OpenAI 文章里也提到了同样的事，不过我们是把它落到了数据库 Schema 和 Service 层的约束上。

② 数据库安全护栏写进仓库，不靠口头约定

Prisma 有几个命令是破坏性的：migrate reset、db push --accept-data-loss。如果 AI 在执行某个任务时不小心跑了这些命令，主库数据可能直接没了。

我的做法是封装了一个 prisma-safe.mjs 脚本，把安全规则写进 AGENTS.md 和 GEMINI.md。AI 执行任何 Prisma 相关操作，只能走这个脚本，不能裸跑 CLI 命令。规则是硬编码进仓库的，不是每次提醒它「你要小心」。

把安全护栏写进仓库之后，这类问题从「偶发风险」变成了「系统不允许」。

③ 工程纪律文件是活文档，不是装饰品

最难做到的一条：每次发现 Bug 或者做重构，必须先更新对应的约束文档，再修代码。

我在 GEMINI.md 里明确写了这条规则，叫「消除熵增」。每次重构或发现系统缺陷，首要动作是更新规范文档，不是默默修完 Bug 假装无事发生。

文档腐化的速度比代码还快。如果你只修了代码、没有同步文档，下次 AI 拿着过时规则做判断，会产生更多问题。

Phase 制的执行节奏也是为了这个：每个阶段都有完整的执行计划和收口记录，提交到仓库，版本控制，供后续追溯。

04 | 这套东西到底值不值得你花时间建

① 对独立开发者来说，这是乘法，不是成本

OpenAI 团队说，早期进展慢，不是因为 AI 能力不够，而是因为「环境的规范不够明确」。

这句话精确描述了我在没有规范时的状态。

AI 每次开始任务，我都要重新解释架构、重新声明约束、重新澄清边界。等它搞清楚背景，已经消耗了大量 token，剩下的上下文窗口全用来填那些「解释过一百遍」的基础规则。

建完框架之后，这个问题消失了。

从感受上，每次任务大概节省 5-10 分钟重复沟通。

② 什么阶段开始建最合适

反直觉的答案：越早越好，不是等项目大了再建。

OpenAI 团队从第一次提交就开始搭架子，连指导 AI 工作的 AGENTS.md 都是 AI 自己写的。

我在自己项目里的做法类似：Phase 1 的时候就建了 GEMINI.md 和 index.md，哪怕当时系统只有 3 个 API、2 个页面。

最小可行版本不复杂：

• 一个宪法文件（底线规则，40 行以内）

• 一个导航地图（文件 → 职责的映射）

• 三条强制执行的分层规则

大概一个下午搭好，之后每个 Phase 都会受益。

③ 人类的角色变了，但没有变少

建完这套框架之后，我花在「定义规则」和「验收结果」上的时间比以前多了，花在「写代码」上的时间降到接近零。

工程师的工作没有变少，层级变了。

你不再是代码生产者，而是约束设计者和验收者。这件事做好了，AI 的输出质量会稳定提升；做不好，AI 会越来越随机，每次跑出来的结果你都摸不准。

OpenAI 团队，用一句话描述了这个转变：人类掌舵，智能体执行。

我觉得到目前为止，没有比这更准确的概括了。

05 | 写在最后

这篇文章里的实践，全都来自 TypeFlow AI 这个真实项目走过的路，包括踩坑、重构和重新建约束的过程。

有一件事我现在可以比较确定地说：在 AI 辅助开发里，框架的质量决定了 AI 输出的质量上限。

代码生成能力的提升是 AI 厂商的事，框架设计是你的事，两件事不能互相代替。

如果你也在用 AI 做独立项目，或者在团队里推 AI 辅助开发，欢迎来聊聊你的框架是怎么搭的。