⁶⁰

¹⁶

⁹⁹⁺

如何从0到1 Vibe Coding 一个项目，并长期维护

吃遍全国汉堡

2026-07-17 13:59

阅读6541

吃遍全国汉堡

2026-07-17 13:59

阅读 6541

我是汉堡。上篇文章《我的第一个 Vibe Coding 项目正式上线，Notus——原生 AI 笔记应用，且完全开源》结尾我说过，要写一篇关于如何持续 Vibe Coding 可长期维护项目的文章。这篇就是。

以下内容来自我自己的血泪教训和成功经验，希望能帮到正在 Vibe Coding 或准备入坑的人。

一、我的 AI 博客项目是怎么死的

去年夏天，我买了 Trae 的会员版，打算自己开发一个 AI 博客功能，包含博客摘要、知识库、SEO 这些。刚开发的时候兴奋得很，看着功能一个一个被实现，越做越有干劲，周末好几次熬到凌晨三四点，差点熬穿了。甚至还幻想靠这个赚钱。

但很可惜，这个项目夭折了。

那会儿刚接触 Vibe Coding，对工程管理和 harness 相关的知识极度欠缺。每次都是想一个功能就让 AI 实现一个，AI 的上下文约等于没有。导致：

改完 A，B 出问题
改完 B，C 又出问题了
改完 C，A 又挂了

无限循环，最后心态崩了，维护不过来就放弃了。

二、Vibe Coding 的本质困境

Vibe Coding 有一个很形象的比喻——抽卡游戏。

刚开始开发的时候，看着自己的想法一个个被实现，就像抽卡前期中奖概率高得很，爽感拉满。但越到后面越难"中奖"：

上下文膨胀：代码量越大，AI 越难理解全貌，每次改动都是盲人摸象
耦合蔓延：组件之间相互依赖，改一处牵一发而动全身
意图退化：没有文档记录，几轮对话之后你自己都忘了当初为什么这么设计
红利消失：前期快速出功能的爽感过去后，维护成本指数级上升

以上所有问题指向同一个根源：缺乏工程化管理。

这个问题可以解决。下面就是我沉淀下来的方案。

三、工欲善其事，必先利其器

工程化管理之前，先聊工具和模型的选择。

Vibe Coding 的效果，首先取决于你用的 Coding Agent 和 AI 模型。我个人推荐这几个 Agent 工具：

Codex（我的主力）/ OpenCode：启动时自动注入项目级别和全局的 AGENTS.md，Agent 啥也不用说就知道项目的一切
Cursor：适合轻量级改动和代码补全
Claude Code：Agent 能力强，适合复杂任务

模型方面，推荐 GPT 5.6 Terra High、GLM 5.2、Claude 5 等一线模型。

使用策略上，用最强的模型做规划和设计，用中高模型做编码。 比如用 Claude Opus 或 GPT 5.6 Sol High 来写项目的需求文档、总技术文档和各功能模块的实现文档——这些"地基"级别的产出，必须交给最强的脑子。具体的编码实现，交给中高模型来执行。

工具和模型选好了，下面聊工程化管理。

四、规划永远比写代码重要一万倍

相信绝大多数人在没 AI 写代码时都喜欢先写后端，再写前端，包括我自己也是如此。但规划和写代码，到底哪个放在前面？

盖房子最重要的是地基，地基打好了房子才能稳。求职市场里，架构师的工资永远比程序员高。规划和设计的份量，不用多说了。

在让 AI 写一行代码之前，先用最强模型把需求文档、技术方案和各功能模块的实现文档写清楚。 这些文档就是你的"地基"。

不一定每处都需要规划得那么细致。文档写得过于事无巨细，反而会让中等模型在执行时缺少自主性和发散性思维，变成了纯粹的"翻译机"。把握好粒度，关键路径细化，边缘逻辑给 AI 留发挥空间。

五、合理的数据库表设计

在没有 AI 写代码的时代，数据库设计是顶要紧的步骤。你对业务的理解会直接体现在数据库设计上，而数据库设计的好坏会影响项目业务的复杂程度，进一步影响代码的可读性和可维护性。

用 AI 出方案时，一定要 review 表的设计。能用一个表解决的，就不要用多个表。 如果 AI 给出的方案不合理，果断和它沟通，选择较优的方案。

同时还要考虑系统后续的拓展功能，防止数据表频繁增删字段，甚至被迫重构表设计。同理，整体方案设计也要把后续拓展的可能性考虑进去——这和规划优先的思路是一脉相承的。

六、写代码的先后顺序

在没有 AI 的时候，我习惯先写后端，再写前端，相信大多数人也是这样。但用 AI 写代码，先写前端，再写后端。

具体做法：

把项目的完整需求文档发给 AI，沟通需要多少个页面，每个页面有哪些详细功能。把沟通出的内容补充到需求文档中。
出原型图。 将需求文档发给 GPT 或 Claude 产出原型图。我个人强烈推荐 Claude Design——审美确实好，原型图不会偏离需求文档要求；而且产出的是 React 代码，可以直接用 Claude 或 GLM 5.2 搭建前端工程跑起来看到页面。如果用 GPT，则用 GPT Image 2 生成设计图，再通过 Codex 像素级还原，但需要注意设计图可能会偏离需求文档的功能。
模拟数据，验证动态页面。 根据数据库表 DDL 在前端模拟一些数据，测试页面是否全是动态渲染的。

到了这一步，你对 Vibe Coding 上瘾了。

先写后端的时候，大片代码不停输出却看不到任何视觉成果，难免有些失落和不安，总感觉 AI 没有遵循文档的要求。先写前端让你在最短时间内看到产品长什么样。 那种即时的成就感和掌控感，完全不一样。反正我自己是这么觉得的，哈哈哈哈。

七、好的上下文与文档管理

经过 AI 博客项目的失败，我在开发 Notus 和后续项目的过程中，逐渐沉淀了一套 Harness 体系——给 AI 配一个"项目管理大脑"。

7.1 AGENTS.md

模型都是有上下文限制的，虽然现在普遍一百万的上下文窗口，但放到一个庞大的项目中，根本不够看，特别是 GPT 这种 300k+ 的上下文更是难受。一般我自己一个对话最多实现 3~4 个需求，防止 Agent 频繁压缩上下文导致准确度丢失。

控制对话长度之外，让 AI 在每次对话开始时就能理解项目的一切，这才是关键。

AGENTS.md 就是干这个的。每次开始一个新项目或维护旧项目时，我都会手写一个 AGENTS.md。对于 Codex/OpenCode 来讲，启动时会自动将项目级别和全局的 AGENTS.md 注入当前对话上下文——你啥也不用说，Agent 就知道关于项目的一切。

下面是一个脱敏后的 AGENTS.md 示例，思路供参考：

▼
plaintext
复制代码
[AGENTS.md](http://AGENTS.md)

本文件只规定 AI 编码 Agent 在项目仓库中的行为。产品需求、技术方案、数据库表和实施细节由项目文档维护，本文件不重复抄写。

**1. 基本行为**

- 始终使用中文回复；代码、标识符、API、数据库字段和提交信息使用英文。

- 先查项目文档、现有代码和测试，再决定如何实现。文档已有答案时，不重复询问用户。

- 只修改当前任务涉及的内容，不顺手做无关重构，不为尚未发生的需求提前建设复杂抽象。

- 不能在当前任务中完成的部分要明确说明，不承诺后台交付。

**2. 权威文档**

- 优先读取 `docs/` 中的 Markdown 版本：PRD（做什么）、技术设计文档（怎么设计）、实施文档（怎么推进）、进度文档（现在做到哪里）。

- 冲突优先级：AGENTS.md → 用户本次明确要求 → PRD → 技术设计 → 实施文档 → 进度文档 → 现有代码。

- 发现代码与文档不一致时，不得静默猜测，按高优先级文档确认目标，说明差异并同步修正。

**3. 开始任务前必须自主查询**

- 查看进度文档，确认当前阶段、下一任务、前置依赖和阻塞。

- 在 PRD 中搜索相关页面、功能名和验收标准。

- 在技术设计中搜索相关模块、表、API、外部依赖和约束。

- 检查受影响代码、迁移和测试，沿用仓库已有模式。

**4. Vibe Coding 工作流**

- 每个任务按最小纵向切片完成：文档定位 → 数据模型/迁移 → 后端服务 → API → UI → 测试 → 文档与进度。

- 数据库变化先写迁移和约束，再改 ORM、服务和 API。

- 需要改变产品范围、架构、表结构或实施顺序时，先更新对应文档，再编码。

- 一次优先交付一个可验证闭环，不并行铺开大量半成品。

**5. 代码结构与依赖方向**

- domain/ 不导入具体框架或 SDK。

- API 不直接写 SQL，也不直接调用第三方数据源。

- 配置统一加载，不在业务代码中散读环境变量。

**6. 完成标准**

- 相关测试通过；数据库迁移可从空库执行也能从上一版本升级。

- 外部 Provider 的失败、超时、空数据和过期状态已处理。

- 完成后必须更新进度文档的状态、证据、遗留问题和下一任务。

- "代码能运行"不等于完成；测试、文档和进度没有同步时，任务仍未完成。

**7. Git 与文档同步**

- 未经用户明确授权，不推送远程、不发布版本。

- 提交只包含当前任务相关修改，不混入无关格式化或重构。

- 不提交 .env*、密钥、数据库、备份、日志、依赖目录和构建产物。

- AGENTS.md 只维护 Agent 行为和代码边界，不复制项目文档的细节。

AGENTS.md 干的事情就一件：让 AI 知道你的编码哲学和项目规范，不用每次都重复交代。

7.2 文档治理

文档治理是 harness 体系的核心模块。在让 AI 写代码之前，先让它把需求写清楚。

我采用的文档分类体系：

文档类型	命名格式	用途
REQ 需求文档	`REQ-YYYYMMDD-XX-*.md`	新功能或大范围改造前必写，明确范围、验收标准
PROG 进度日志	`PROG-YYYYMMDD.md`	每天一日志，记录完成了什么、遇到了什么问题
BUG 缺陷记录	`BUG-YYYYMMDD-XX-*.md`	发现 bug 立即记录，关联来源 REQ
BIZ 业务决策	`BIZ-YYYYMMDD-XX-*.md`	业务流程或实现策略的确认和调整
DEV 技术方案	`DEV-YYYYMMDD-XX-*.md`	复杂模块拆解、阶段实施方案

关联规则：

PROG 必须引用相关 REQ/BUG，保证进度可追溯
BUG 必须引用来源 REQ，知道这个 bug 是从哪个需求引入的
BIZ 必须引用对应 REQ，业务决策不能悬空

这套体系的作用：

上下文外挂：AI 每次对话前先读相关文档，就不会丢失上下文
可追溯：三个月后回来，你还能知道当初为什么这么设计
可交接：换一个 AI 模型或工具，读一遍文档就能接手

7.3 控制 Vibe Coding 的边界

Vibe Coding 的一个诱惑也是陷阱："顺手加一个功能"。

你以为只是"顺手"，但 AI 的上下文是有限的。每多一个功能点，就会引入新的耦合、新的边界情况、新的 bug 风险。

范围冻结就是在一开始把 v1 要做什么、不做什么写死。比如 RepoRadar 项目：

纳入 v1 的：GitHub Search 抓取、规则过滤、去重入库、Agent 分析、仓库列表、配置中心、飞书推送...

明确不进 v1 的：增速监控、批量提交、导出 CSV/Markdown、语义去重、多数据源接入...

一旦范围冻结，后续开发中 AI 想"顺手"加功能时，你就可以说："不在 v1 范围，先记 REQ，下个版本再说。"

7.4 分阶段推进：Phase 0 → Phase N

大项目一口气让 AI 实现 = 灾难。必须拆阶段，每个阶段有明确的 DoD（Definition of Done）。

一套典型的阶段划分：

阶段	内容	DoD
Phase 0	文档体系初始化	AGENTS.md、README.md、docs/ 结构就绪
Phase 1	后端骨架	服务可启动、配置可读、数据库可初始化
Phase 2	核心链路 1	端到端链路跑通
Phase 3	核心链路 2	同上
Phase 4	业务 API	接口字段对齐、错误响应统一
Phase 5	前端工程化	拆页拆组件、接入真实 API
Phase 6	通知与配置	链路闭环、热重载
Phase 7	打包上线	Dockerfile、持久化、基础回归

每个 Phase 结束必须达到 DoD 才能进入下一阶段。这个纪律不能破。

八、实战项目 Notus

下面是我怎么用这套体系把 Notus 从 0 到 1 做出来的。

8.1 项目背景

Notus 是一个本地 AI 原生笔记应用，核心功能是文档编辑、知识库和 AI 创作。对标的其实是 notebookLM 和 YouMind，但完全开源、免费、数据本地存储。开发周期大约 20 天（非全职）。

8.2 怎么用 Harness 体系

文档先行。 在写第一行代码之前，我先写了 PRD（产品需求文档），明确了 v1 范围、核心功能、技术选型。

AGENTS.md 就位。 项目初始化时就写好 AGENTS.md，让 AI 每次对话都先理解项目结构和规范。内容包括项目采用 Tauri + React 架构、前端组件目录结构、代码风格要求，以及禁止的行为（比如不要擅自改架构）。

分模块推进。 不是一口气让 AI 写整个应用，而是按模块来：先搭编辑器核心（Markdown 解析与渲染），再建知识库（文档索引 + 语义检索），最后做 Agent 创作（多文件改写 + 风格学习）。

8.3 上下文管理

这是 Notus 开发中踩得最深的一个坑。

当项目代码量上去之后，AI 的上下文窗口根本塞不下全部文件。我的做法是：

按需加载：只把当前任务相关的文件喂给 AI，其余文件通过文档索引让 AI 知道"存在但不加载"
摘要压缩：对历史对话进行摘要压缩，保留关键决策和上下文
意图识别：先让 AI 判断用户是想改写文章还是单纯闲聊，匹配不同策略

这些经验后来也直接体现在了 Notus 的 Agent 工程模块里。

九、实战项目 RepoRadar

9.1 项目背景

RepoRadar 的起源其实很接地气——我在懒猫搬砖做副业，为了方便，写了个应用去爬 GitHub 开源仓库，自动判断能不能搬，然后推送到飞书群里。

但这次不一样。这次我一开始就用上了完整的 harness 体系。

9.2 Harness 落地实践

文档体系先行（Phase 0）：在写任何代码之前，先把 PRD、AGENTS.md、docs/ 目录结构全部建好。PRD 作为总纲永久保留。

范围冻结：v1 只做 GitHub Search 抓取、规则过滤、Agent 分析、飞书推送。增速监控、批量提交、语义去重等全部推到后续版本。

分阶段 7 步走：从文档体系初始化 → 后端骨架 → 采集链路 → 分析链路 → 业务 API → 前端 → 打包上线，每一步都有明确的 DoD。

接口契约先行：在写代码之前先定义 API 契约（GET /api/repos、POST /api/submit 等），前后端以契约为准各自开发互不阻塞。

9.3 和之前失败的 AI 博客项目对比

维度	AI 博客（失败）	RepoRadar（成功）
文档	❌ 无，想到哪做到哪	✅ PRD + AGENTS.md + docs/
范围	❌ 不断加功能	✅ v1 范围冻结
阶段	❌ 无规划，一把梭	✅ Phase 0-7 分步走
上下文	❌ 约等于没有	✅ 按需加载 + 摘要压缩
结果	心态崩了	在掌控之中

十、心态

最后聊聊心态。

Vibe Coding 做久了，最大的坑不是 AI 不够强——是你自己的欲望。看到一个好玩的功能就想加，看到别人开源了什么就想自己也搞一个。但代码是一行一行堆出来的，每多一个功能，维护成本就往上翻。能复用的就别自己造，能用现成库的就别手写。我踩过太多这种坑：花三天写了个工具函数，后来发现 github上早就有成熟方案，比自己写的还好。

项目做着做着没动力了，我经历过好几次。归结下来就两个原因。

一个是无力维护。代码越堆越多，改一个地方炸三个地方，每次打开项目都有心理负担。这种情况只能靠前面说的工程化管理兜底——文档、范围冻结、分阶段推进。别等烂摊子收拾不了了才想起来，那时候已经晚了。

另一个是不赚钱。花了几百个小时做的项目，上线后用户没几个，更别提收入了。大部分 side project 都这样，没办法。我的态度是：练手的项目，学到东西就算回本；真想赚钱，立项前就想清楚谁来买单、凭什么买单。别一边写代码一边幻想"做完了就有人用了"——大多数时候不会。

个人博客

我的博客：https://blog.hejiajun.com

下一篇预告：Notus 的 Agent 工程细节——上下文压缩、意图识别和工具调用的具体实现。

问答助学