Project Vibe Spec 大升级：我想解决 Vibe Coding 项目越写越乱的问题
开源地址：github.com/dnwwdwd/project-vibe-spec如果对你有用，GitHub 上点个 Star 是最实在的支持 ⭐
最近把自己开源的 project-vibe-spec 重构了一遍。
做这个 Skill 的原因一直没变。
现在用 Codex、Claude Code 做项目，写代码已经越来越省事。问题慢慢跑到了另外一边：项目做久以后，Agent 开始忘，文档开始乱，方案改过几轮没人记得，代码写完了也不知道到底验证到什么程度。
这种问题对 Vibe Coding 用户影响尤其大。
很多人不会逐行 Review 代码，我自己做一些项目时也不会每次把几百上千行 diff 从头看到尾。我更容易确认的是页面有没有做对、流程是不是我想要的、数据语义有没有问题、最后能不能跑。
一旦项目做几个月，光靠聊天记录就撑不住了。
这一轮 Agent 记得为什么这么改，换个 Session 可能就不知道了。PRD 还写着旧方案，代码已经跑到第三版。某个功能之前只做了 POC，过几轮以后 Agent 开始把它当成正式能力。数据库里多了一张表，几个月后没人知道当时为什么拆。
还有一种很常见。Agent 改完代码以后直接告诉你"已完成"，结果测试没跑，UI 没打开，migration 没验证，Windows 也没测。
我之前写 project-vibe-spec，主要就是在补这些东西。
旧版已经能管需求，但有点重
之前的 Project Vibe Spec 已经有一套比较完整的流程。
一个需求进来以后，会经过需求确认、REQ、方案决策、实现、测试、Progress 更新。数据库、migration、权限、安全、公开 API 这种不太好回退的改动，还要求先讨论方案，再让 Agent 动代码。
这套流程用了以后，项目确实没那么容易失控。
但它自己也慢慢长胖了。
SKILL.md 里面要规定需求怎么分类、什么算跨模块、什么时候建 REQ、什么时候写 DEC、数据库什么时候要确认、Progress 怎么更新、哪些文档一起改、最后怎么验收。项目自己的 AGENTS.md 也容易继续往里面塞规则。
时间一长，Agent 接一个很小的任务，也可能先读一堆跟当前工作没关系的内容。文档都在，Agent 的上下文反而越来越重。
现在项目上下文拆成了四层
新版大概是这个结构：
▼text复制代码AGENTS.md ↓ 判断当前任务应该读什么 DOCUMENT_MAP.md ↓ 找到项目现在认可的文档 PRD / PDD / Design / Flow / DEC ↓ 保存产品、技术、设计和决策 REQ / Bug / Progress ↓ 记录当前正在推进的工作
AGENTS.md 现在会尽量保持轻。里面放仓库边界、安全规则、任务路由、高风险操作和通用验证要求。
比如：
▼text复制代码修改产品行为 → 读产品文档和相关 REQ 修改 UI → 读设计规范和对应产品规则 修改数据库 → 读技术设计和 DEC 修改 Agent / MCP / 检索 → 读技术设计和业务流程 修 Bug → 读 Bug 记录和受影响模块规则
表结构、接口字段、当前开发进度、某个功能的详细需求，不继续往根 AGENTS.md 里堆。Agent 改哪块，再加载哪块的上下文。
DOCUMENT_MAP.md 现在会告诉 Agent 哪份文档能信
这个改动看起来不大，我自己挺在意。
项目做久以后，仓库里经常会出现这种文件：
▼text复制代码old-design.md architecture-v2.md architecture-final.md prd-new.md some-spike.md
人还能根据名字和 Git 历史猜一下。Agent 可能全部读进去，然后旧方案、新方案、实验记录一起进上下文。
新版的 DOCUMENT_MAP.md 会给文档标状态：
▼text复制代码现行 参考 缺失 不适用
例如：
▼text复制代码产品事实 docs/product/spec.md 现行 旧版产品设计 docs/archive/product-v1.md 参考 UI Design 缺失 Desktop 架构 docs/desktop-architecture.md 现行
至少 Agent 进项目以后知道当前应该看哪一份。
init 也整个重写了
旧版 init 主要围绕 PRD/PDD 和项目总进度工作。
现在执行：
▼text复制代码$project-vibe-spec init
Agent 会先把仓库过一遍。它会检查 AGENTS.md、CLAUDE.md、README、docs、需求、设计、DEC、Progress、测试、构建配置、schema、migration、部署脚本和一部分实际代码。先弄清楚项目已经有什么，再决定缺什么。
假设一个项目已经用了：
▼text复制代码specs/product.md architecture/backend.md docs/design-system.md adr/
新版不会再硬生生补：
▼text复制代码docs/PRD.md docs/PDD.md docs/UI_GUIDE.md Decisions/
DOCUMENT_MAP.md 里直接记现有路径：
▼text复制代码产品事实 → specs/product.md 技术事实 → architecture/backend.md 设计规范 → docs/design-system.md 架构决策 → adr/
跑 init，更接近给现有仓库做一次整理和审计。
没有 PRD，就先记没有
以前为了把结构补齐，很容易生成一堆空模板。PRD.md 有了，PDD.md 有了，UI_GUIDE.md 也有了，里面没有多少能指导 Agent 的内容。
这轮把这个行为改掉了。
项目没有 PRD，可以直接记：
▼text复制代码产品事实：缺失
没有设计规范，而且项目根本没有 UI，也可以记：
▼text复制代码设计规范：不适用
后面开发真的需要产品规则，再补 PRD。模板现在只在项目缺这份信息、同时后续工作又需要它的时候才创建。
历史功能也不用补几十个 REQ
一个已经做了几个月的项目第一次跑 init，如果硬套需求台账，很容易一次性生成很多历史 REQ。项目里已经有十几个功能，就补十几个需求记录。这些文件看起来规范，之后基本没人维护。
现在已有功能直接进入"当前实现基线"。
例如：
▼text复制代码Agent Loop 已验证 PDF 解析 已实现待验证 多模态 PDF 已通过（POC）
从这次初始化往后，新需求和还在推进的大任务再进入 REQ。需求台账里留下来的，基本都是后面还会继续看的内容。
"代码已经写了"单独变成一个状态
这次加了一个状态：
▼text复制代码已实现待验证
现在 Progress 有这些状态：
▼text复制代码已验证 已实现待验证 已通过（POC） 进行中 待开发 待拆分需求 待澄清 不纳入
加这个状态就是因为 Coding Agent 太容易把代码完成和功能完成混在一起。
仓库里已经有实现，只能说明代码存在。测试没跑完，就写"已实现待验证"。只验证过一个 Demo，就写"已通过（POC）"。有对应测试、构建结果或者真实用户路径验证以后，再写"已验证"。
对于不太看代码的人，这个区分比多一份技术文档有用得多。至少你问 Agent"这个功能做完没有"，它不能只因为搜到了代码就回答完成。
数据库这种改动我还是卡得很死
这轮删了不少文档负担，但数据库规则没放松。
Agent 想加表、加字段、改索引、迁历史数据、删数据或者改 ORM schema，还是先调查。我要看到这个字段表示什么，谁写，谁读，旧数据怎么办，能不能为空，有没有唯一约束，需要什么索引，上线怎么迁，失败以后怎么处理。方案确认以后再改。
Vibe Coding 里面，数据库被连续改错几轮，比一个按钮颜色错了麻烦得多。这块宁愿多一次确认。
这版对不 Review 代码的人有什么用
Project Vibe Spec 解决不了所有代码质量问题。竞态条件、慢 SQL、隐藏的安全问题、边界异常，该测还是得测，该 Review 还是得 Review。
我更关心的是另一个问题。
很多 Vibe Coding 项目做着做着，用户已经不知道项目现在是什么状态了。
需求当时怎么确认的？Agent 为什么用了这个方案？这个实现是临时的还是正式的？POC 后来有没有进正式版本？文档和代码现在该信哪个？哪些地方写完了还没测？下一次开新 Session 从哪里继续？
这些信息如果全在聊天记录里，换个 Agent、换个工具或者隔一个月回来，很容易断。
新版 Project Vibe Spec 会尽量把这些信息留在仓库里。以后无论用 Claude Code 还是 Codex，Agent 先从 AGENTS.md 进入，根据任务找到 DOCUMENT_MAP.md 里的现行文档，再读对应的需求、决策和进度。
聊天记录可以丢，项目自己的状态还能接着用。
这次重构完以后，Project Vibe Spec 少了一些"必须创建什么文件"的规定，多了一套让 Agent 找到当前可信信息的办法。对大量用 Agent 写代码、又不会每次认真 Review 全部 diff 的开发方式，这比继续加几十条规范有用。
如果这套思路对你有帮助，去 GitHub 点个 Star 吧：github.com/dnwwdwd/project-vibe-spec ⭐
