Vibe build

Vibe Build：Spec-Driven 代码构建

核心铁律：Spec is Law。 每行代码可追溯到 spec，每个任务有验收标准，每个"做好了"附带运行证据。

面向用户：零参与。 build 阶段完全自主，仅在 Phase 7 GATE 遇到高风险操作时暂停询问。

---

输入与输出

	文件	说明
输入	.vibe/doc/REQUIREMENTS.md	vibe-clarify 产出
输入	.vibe/doc/ARCHITECTURE.md	vibe-architect 产出
输出	项目代码（可运行）	按 spec 构建的完整代码库
输出	.vibe/doc/BUILD_LOG.md	构建日志：完成了什么、验证结果、偏离记录、遗留问题

---

门禁总览

#	Phase	门禁条件	动作	用户
1	SCAN	必入	读两份 spec，提取可执行任务	零
2	READINESS CHECK	必入	检查输入文档是否真正就绪	零
3	WALKING SKELETON	READINESS CHECK 通过	部署贯穿全栈的最小可运行骨架	零
4	PRE-MORTEM	SKELETON通过+高风险	推演3个潜在失败场景	零
5	RESEARCH	必入	搜索现有组件/模板/代码	零
6	DECOMPOSE	必入	拆原子任务，标依赖+并行组+spec溯源+验收标准	可查看
7	GATE	有高风险任务	逐任务过风险矩阵，高风险暂停	仅高风险
8	BUILD	必入	逐任务四步 TDD 循环：写测试→写实现→重构→提交	零
9	AUDIT	必入	全量扫描 10 项 + 偏离 spec 检测 + 安全基线	零
10	E2E	必入	核心用户故事从头走到尾，实际运行	零
11	SATISFACTION GATE	必入	三方自检+用户确认	确认
12	HANDOFF	满意度门禁通过	汇总 BUILD_LOG.md	确认

---

Phase 1：SCAN

门禁：无（必入）

流程

1. 显式 Read .vibe/doc/REQUIREMENTS.md 和 .vibe/doc/ARCHITECTURE.md
2. 交叉提取：

从 REQUIREMENTS.md 提取	从 ARCHITECTURE.md 提取
每个 P0/P1 功能 + 量化标准	每个路由 + 对应组件
关键决策记录	每个数据实体 + 字段
明确不做什么	项目目录结构
	技术选型表

3. 生成一个实现清单草稿："要完成这些 P0 功能，需要实现以下文件和模块……"。不展示给你，直接进 Phase 5（RESEARCH）。

纪律

• 必须用 Read 工具读文件，不靠对话记忆（防问题 #1）
• 如果有任一文件不存在 → 停下来告诉你，不猜测内容

输出

P0 功能清单 + 对应实现模块映射（内部，供 Phase 6（DECOMPOSE）消费）

---

Phase 2：READINESS CHECK

门禁：必入

做什么：在继续任何工作之前，检查输入是否真正就绪。

逐条对照：

• REQUIREMENTS.md 存在且每个 P0 功能有可测的验收标准
• ARCHITECTURE.md 存在且每个数据实体有字段定义
• DESIGN.md 存在，除非用户明确说过跳过设计
• 三个文档之间没有直接矛盾（例如：REQ 说免登录，ARCH 却要求 auth 表）
• 所有 P0 功能的验收标准都能量化——不能出现"系统正常""体验良好""功能完善"

全部通过 → 进入 RESEARCH 任一项未通过 → 列出具体缺口，回到对应的前置 skill 补充。不带着缺口开工。

纪律：

• 这个门禁不妥协。模糊的验收标准不是"差不多就行"，是"还没就绪"。
• 如果发现文档矛盾 → 回到 vibes 触发回退路由，不自己判断"哪个对"。

---

Phase 3：WALKING SKELETON

门禁：READINESS CHECK 全部通过

做什么：在拆解任何功能任务之前，先部署一个贯穿全栈的最小可运行骨架。骨架不包含业务功能。唯一目的是验证"架构链路是通的"。

骨架必须包含：

1. 项目初始化 + 构建工具链：npm init / next.config / tsconfig 配置完成，npm run build 通过
2. Next.js 基础设施页面（每个项目必有的脚手架，不是业务功能）：
   • app/layout.tsx：根布局 + metadata（标题/描述取自 REQUIREMENTS.md）
   • app/error.tsx：全局错误边界（"出错了" + 重试按钮）
   • app/loading.tsx：全局加载占位（骨架屏或 spinner）
   • app/not-found.tsx：全局 404 页面
   • 如果 ARCHITECTURE.md 要求认证 → middleware.ts（只搭架子，不写认证逻辑）
3. 一个数据库表（如果有数据库）：建表 migration + 能写入一条记录 + 能读出
4. 一个 API 端点：能收到请求并返回响应（返回硬编码 JSON 即可）
5. 一个前端页面：能看到内容（"Hello World" 级别即可）
6. 自动部署：Vercel（或其他 ARCHITECTURE.md 指定的平台）一键部署 → 线上能访问上面的页面
7. 健康检查：至少一个端点返回 200

验证标准：

• 线上 URL 能打开看到页面
• 访问不存在的路由 → 看到 not-found.tsx 页面（不是白屏或默认 404）
• API 端点 curl 有响应
• 数据库写入后能读出同一条数据
• error.tsx 存在且 npm run build 不报错（不要求线上触发错误来验证）
• 以上全部在同一次部署中通过

纪律：

• 骨架不包含任何业务功能。出现业务代码 → 删除，这不是骨架的职责。
• ARCHITECTURE.md 说用什么技术，骨架就必须用什么。不降级、不替换、不模拟。
• 三次尝试仍无法通过骨架部署 → 回到 vibe-architect 重新审查架构选型。
• 骨架通过后，代码保留。后续 feature 任务在此基础上增量构建。

输出：可访问的线上骨架 URL + 验证报告

---

Phase 4：PRE-MORTEM

门禁：WALKING SKELETON 通过，且项目复杂度为 🔴 高风险

• 复杂度 🟢🟡 → 跳过。

做什么：在拆解任务之前，先回答一个问题：

"如果这个项目在 90 天后失败了，最可能的 3 个原因是什么？"

每个失败场景必须包含三个要素（缺任一 → 不通过）：

1. 什么失败了——具体组件或结果。不是"项目"，是"XX 接口"或"YY 流程"。
2. 为什么失败——机制或根因。不是"没做好"，是"XX 和 YY 之间的同步延迟超过了 ZZ 秒"。
3. 第一个预警信号——可观察的早期指标。不是"用户不满意"，是"2 人测试时延迟 > 3 秒"。

示例（合格）： "失败场景 1：AI API 调用延迟在多人并发时超过可接受范围。 原因：Supabase Realtime + AI API 串行调用，6 人同时触发时请求排队。 预警信号：2 人并发测试时，任一回车到响应超过 3 秒。"

示例（不合格，驳回重写）： "失败场景 1：项目没做完。原因：时间不够。预警：进度慢了。" 驳回理由："什么组件没做完？时间不够是因为什么具体瓶颈？什么指标算进度慢？"

三个场景必须来自不同维度：

• 至少一个技术维度（性能、并发、数据一致性）
• 至少一个产品维度（用户体验、需求偏差、复杂度膨胀）
• 至少一个工程维度（维护性、可扩展性、外部依赖）

纪律：

• 不接受模糊词。不接受"可能""大概""也许""应该"。
• 不接受"团队不行""时间不够"之类不可操作的原因。
• 如果专家判断三个场景都不成立 → 可以输出"未发现高风险失败场景"，但必须每条附一句话说明为什么不成立。

输出：3 个失败场景，或 3 条"未发现"的判断理由

---

Phase 5：RESEARCH（避免造轮子）

门禁：无（必入）

流程

理解了需要实现的功能之后，搜索社区是否已有现成的组件或代码可复用。

搜索方向

搜索内容	方法
现成 UI 组件	shadcn/ui registry (npx shadcn add)、21st.dev 搜索
同类功能的实现代码	GitHub 搜索、WebSearch "[功能] implementation [技术栈]"
npm 包	npm search [功能]、现有包能直接实现需求吗
开源项目参考	gh search repos "[项目类型] [技术栈]"

纪律

• 有现成组件 → 直接引入，不重写
• 有可参考的实现 → 适配而非照搬
• 搜不到 → 记录"已搜索，无现成方案"，继续走 DECOMPOSE
• 搜索结果注入 DECOMPOSE 的 task 拆分：有现成的东西就用，别拆 task 去重写

输出

搜索结论 + 如找到：可复用的组件/包/代码链接

---

Phase 6：DECOMPOSE

门禁：无（必入）

流程

将实现清单拆成原子任务。拆分规则：

1. 1 任务 = 1 文件或 1 个内聚单元，预计 2-5 分钟可完成
2. 每个任务含五个字段：

Task #03: 创建 ShipmentTable 组件
  依赖: Task #01 (类型定义), Task #02 (数据库连接)
  Spec 溯源: REQUIREMENTS.md §2 P0 "发货单列表展示", ARCHITECTURE.md §4 "ShipmentTable"
  测试类型: component（单元=工具函数/纯逻辑 | component=UI组件渲染+交互 | integration=API+DB端到端）
  验收: (1) npx tsc --noEmit 通过 (2) 组件渲染不发散 (3) 空数据时显示"暂无发货单"
  并行组: [group-2] (与 Task #04, #05 无相互依赖)

3. 标注并行组：不互相依赖的任务标为同一 [parallel] 组

4. 验证完整性：每个 P0 功能 → 至少 1 个 task 覆盖。逐条对一遍，"P0 '发货单列表' → Task #03, #06, #09"：确认无遗漏

5. 渐进增强分层（建议按此顺序思考）：同一依赖层内的任务按此顺序执行更稳健，但如果你能确认某项没有下层依赖，也可以并行：

6. Static（HTML 结构、路由）→ 先有骨架

7. Styled（CSS、组件样式、设计 tokens）→ 再穿上衣服

8. Interactive（事件处理、状态管理、API 调用）→ 然后能交互

9. Accessible（aria、键盘导航、焦点管理）→ 保证可用

10. Optimized（性能、缓存、懒加载）→ 最后优化

建议下层任务完成后才进入上层。架构相关的 infrastructure 任务（数据库连接、类型定义）作为第 0 层最先执行。

输出

写入 .vibe/state/task_list.md：

# Build Task List：[项目名]

> 基于 REQUIREMENTS.md r1 + ARCHITECTURE.md r1
> 生成时间: 2026-07-15

## 依赖图
Task #01 (类型定义) ← 无依赖
Task #02 (数据库连接) ← Task #01
Task #03 (ShipmentTable) ← Task #01, #02  [parallel: group-2]
Task #04 (StatsCard) ← Task #01  [parallel: group-2]
...

## 任务列表
- [ ] Task #01: 创建 TypeScript 类型定义文件
  - 文件: src/types/index.ts
  - 测试: unit
  - 验收: npx tsc --noEmit 通过
  - Spec: ARCHITECTURE.md §4 数据模型

- [ ] Task #02: 初始化 Supabase 客户端连接
  - 文件: src/lib/supabase.ts
  - 测试: unit
  - 验收: import 不报错，环境变量正确读取
  - Spec: ARCHITECTURE.md §2 Supabase
...

纪律

• 不跳过任何 P0 项的 task 覆盖
• 验收标准必须可执行（具体命令 + 预期输出），不能写"功能正常"
• 并行组谨慎标记：有共享依赖的不能放一组

你参与

"任务拆好了，共 N 个任务，M 个并行组。要不要看一眼？直接回复'开始'我就开始写代码。"

---

Phase 7：GATE

门禁：任务列表中存在中风险或高风险操作？

• 全低风险 → 跳过。"全是低风险任务，直接开始。"

流程

逐任务过风险分级矩阵：

风险等级	操作类型	示例	处理
🟢 低	UI 组件、样式、工具函数、类型定义	创建 Button 组件、写 CSS	自主执行
🟡 中	新依赖安装、数据库 schema 变更、新路由、环境变量	npm install xx、创建新表、添加新页面路由	告知你，确认后执行
🔴 高	认证/授权逻辑、支付相关、数据删除、修改已有数据库迁移、涉及密码/密钥	修改登录逻辑、接入 Stripe、DROP TABLE	暂停，等你明确批准

完整风险矩阵见 references/risk-matrix.md。

# 风险审查

🟢 低风险：22 个任务：自主执行
🟡 中风险：3 个任务
  - Task #02: 安装 supabase-js 依赖 → "需要装一个新包，不影响已有功能。继续吗？"
  - Task #08: 创建 shipments 数据库表 → "需要在 Supabase 新建一张表。继续吗？"
  - Task #15: 添加 /api/upload 路由 → "加一个新接口。继续吗？"
🔴 高风险：0 个

中风险任务需要你确认。其余的我自己搞定。

高风险任务回滚契约： 每个 🔴 风险任务在 EXEC 之前，必须附带一句回滚说明： "如果这个改动出问题，回滚方式：[具体步骤]"

回滚说明不符合以下任一条件 → 不开始执行：

• 步骤具体可执行（不是"恢复代码"而是"git revert <commit>"）
• 可在 5 分钟内完成
• 不需要依赖外部系统或人工判断

高风险特性开关： 🔴 风险且涉及用户可见行为的 task → 默认实现为特性开关（默认关闭）：

1. 代码实现两个分支：flag-off（旧行为）和 flag-on（新行为）
2. flag 定义在统一的 flags 配置文件或环境变量中
3. 测试覆盖 flag-off 和 flag-on 两种状态
4. 部署后 flag 保持关闭 → 通过 vibe-deploy 或手动开启逐步放量

不需要 UI 层面的特性开关框架——一个环境变量或配置文件项即可。

纪律

• 任何涉及钱、密码、删除数据的操作必须红色，不准降级
• 不确定风险等级 → 往上报一级
• 你说"全通过" → 全部放行，不逐个追问
• 你对某个任务有疑问 → 展开解释后等待确认

输出

风险分级表 + 你确认记录

---

Phase 8：BUILD

门禁：GATE 全部通过（或跳过）

流程

逐任务执行四步 TDD 循环。

提交消息遵循 conventional commits 格式（feat:, fix:, refactor:, test:, chore: 等前缀）。

for each task in task_list（按依赖顺序、并行组内可并行）:

  STEP 1 — 写测试：先写测试用例覆盖本 task 的验收标准。运行确认测试失败。
  
    ⛔ TDD 门禁（STEP 1 → STEP 2 之间强制执行）：
    - 测试文件已写入且 `npm test -- --grep <test name>` 返回失败（预期失败）→ 通过，进入 STEP 2
    - 测试直接通过 → 驳回：测试没有真正验证新功能（可能是空测试或测试了已存在的代码）。重新写测试。
    - 没有测试文件 → 驳回：TDD 要求测试先行。必须先写测试。
  
  STEP 2 — 写实现：写最小代码让测试通过。不改测试。
  STEP 3 — 重构清理：改进代码结构。运行测试确认全部仍通过。

    📋 完成标准自检（STEP 3 → STEP 4 之间，AI 自问，不阻断）：
    本 task 创建/修改的组件或页面：
    - [ ] 空状态处理了吗？（数据为空时不是白屏或报错）
    - [ ] 加载状态处理了吗？（数据还在请求时用户看到什么）
    - [ ] 错误状态处理了吗？（API 失败时用户看到什么、能做什么）
    - [ ] 可访问性及格了吗？（img 有 alt、form 有 label、颜色不只是唯一的信息传达方式）

    如果任一项为"否"但确实不适用于本 task（如纯工具函数不需要加载态），在 commit message 中注明原因即可。
    如果为"否"且适用 → 回到 STEP 2 补上，重新走 STEP 3。

  STEP 4 — 提交：git commit（遵循 conventional commits 格式）。npx tsc --noEmit 通过。更新 task_list.md。

4.2 批量审计

每 3-5 个 task 执行一次：

派遣一个独立子 agent（context: fork，只读权限）审查最近 3-5 个 task 的变更：

• 只读 diff 和 spec 相关段落
• 不知道这些代码是怎么写出来的
• 检查：类型安全、import 有效性、错误处理、与 spec 对齐、无假代码
• 输出：通过 / 发现问题清单 发现问题 → 下一个 task 开始前修复（最高优先级） 连续两次批量审计均通过 → 可以适当增大批量审计间隔

若无法派遣子 agent，回退为内部审计。

4.3 上下文同步

每完成 3-5 个 task（或每 15 分钟），更新 .vibe/state/progress.md：

# Build Progress
## 当前进度: 15/28 tasks 完成
## 当前并行组: group-3 (Task #12-16)
## 最后完成: Task #15：API /api/upload 路由
## 当前状态: 正常推进，无阻塞
## 下一步: Task #16 开始

作用：上下文压缩或会话中断后，新会话读取此文件即可恢复。

4.4 偏离处理

如果 subagent 发现必须偏离 spec 才能完成（spec 有矛盾/技术不可行）：

"Task #08 需要偏离 ARCHITECTURE.md §4 的设计。
  原 spec 写：[具体内容]
  实际遇到：[具体问题]
  建议改为：[具体建议]
  影响：[只影响本 task / 会影响下游 task #XX, #YY]

  同意这个改动吗？"

• 你同意 → 记录偏离，更新对应 spec 文档，继续
• 你不同意 → 标记 BLOCKED，跳过，由你决定方向

偏离记录格式（写入 BUILD_LOG.md 的偏离区）：

偏离 #001 | Task #08 | ARCHITECTURE.md §4
  原：Supabase Storage 存文件
  改：先用本地 public/ 目录，部署前迁移
  原因：Supabase Storage 配置需要先完成域名验证
  你确认：2026-07-15

输出

• 完整的可运行代码库
• task_list.md 全部 checkbox 打勾（或有明确 BLOCKED 标记）
• 每个 task 的 commit 记录
• 所有偏离记录

---

Phase 9：AUDIT

门禁：无（必入）

流程

逐条扫描，每项通过打 ✅，失败标记 ❌。

5.1 假代码扫描（8 种模式）

#	检查项	扫描命令/方法	通过标准
1	占位者	grep -rn "TODO|FIXME|placeholder|not implemented|stub|temp" --include="*.ts" --include="*.tsx"	0 结果
2	空函数体	grep -rn "pass\s*$|{\s*}|{\s*/\*.*\*/\s*}" --include="*.ts" --include="*.tsx"	0 结果（排除空接口声明）
3	幻觉 import	逐个 import 语句检查包名是否在 package.json / 可解析	每个 import 可解析
4	拖延语言	grep -rn "will implement|下一步|left as|exercise|you.ll need|should be|later|coming soon"	0 结果
5	吞错	grep -rn "catch\s*(\s*[eE].*\s*)\s*{\s*}" --include="*.ts" --include="*.tsx"	每个 catch 块至少有一行有实质内容
6	缩水	对照 REQUIREMENTS.md 逐条 P0，搜索关键词确认有实现	每个 P0 有对应代码
7	承诺者	grep -rn "in the next|下一步会|once.*ready|when.*done"	0 结果
8	绕行安全	每个路由文件检查是否引用了认证中间件（如果 spec 要求认证）	100% 覆盖

5.2 结构化错误处理检查

#	检查项	方法
9	结构化错误处理	grep "catch\s*(" → 每个 catch 块必须有实质处理（不能只是 console.log）
		grep ".then|await" → 每个异步操作必须有 .catch 或 try-catch
		用户可见的错误信息是否具体？grep "出了点问题|请重试|Something went wrong" → 0 结果
		API 返回是否用类型化响应（不是 res.json({ error: "..." }) 而是结构体）？

5.3 原子操作与竞态检查（如果有数据库或支付相关代码）

#	检查项	方法
10	原子操作与竞态	涉及并发写入的代码是否有锁或幂等机制？
		Webhook handler 是否有 Idempotency-Key 验证？
		"先查后写"模式是否存在 → 替换为原子操作
		定时任务/后台任务是否用了 worker 而非 setTimeout？
		如代码不涉及数据库写入或第三方回调 → 跳过此项

5.4 偏离 spec 检测

逐条对照：
  ARCHITECTURE.md §2 技术选型 → package.json 对齐了吗？
  ARCHITECTURE.md §3 数据模型 → 实际数据库 schema 对齐了吗？
  ARCHITECTURE.md §4 路由表 → 每个路由文件存在且路径匹配吗？
  ARCHITECTURE.md §4 组件树 → 每个组件文件存在且导入关系匹配吗？

5.5 安全基线检查

检查项	方法
.env 文件在 .gitignore 中	grep ".env" .gitignore
无硬编码密钥	grep -rn "sk-|api_key|secret|password\s*=" --include="*.ts" --include="*.tsx"
TypeScript strict mode	tsconfig.json 中 strict: true
无 eval/exec	grep -rn "eval|exec(" --include="*.ts" --include="*.tsx"

输出

审计报告（✅/❌ 清单），记录到 BUILD_LOG.md

参考

完整假代码模式清单见 references/fake-code-patterns.md。

纪律

• 审计不通过 → 不进入 Phase 10（E2E）
• ❌ 项分类：能自动修的（如忘记 gitignore .env）当场修复；不能自动修的（如 P0 功能缺实现）→ 记录，标记 BLOCKED
• 假代码扫描的 8 个模式是硬性门禁：任何一项不通过就不能说"构建完成"

---

Phase 10：E2E

门禁：AUDIT 全部通过（或 ❌ 已全部修复）

流程

选 1 条最核心的用户故事（REQUIREMENTS.md P0 第一条），从头到尾在终端实际运行。

必须覆盖两个路径（缺一不可）：

路径 A：happy path（正常用户）

用户故事："用户打开页面→看到登录框→登录→看到今日数据"

Step 1: npm run dev → 项目能启动吗？
  → 能，localhost:3000 可访问

Step 2: 打开 http://localhost:3000 → 看到什么？
  → 重定向到 /login，显示登录表单
  → ✅ 路由守卫生效

Step 3: 输入测试账号 → 点击登录 → 发生了什么？
  → 跳转到 /dashboard
  → ✅ 认证流程正常

Step 4: 仪表盘页面 → 看到什么？
  → 显示"暂无发货单"（空状态）
  → ✅ 空状态处理正确

Step 5: 点击"上传"→ 上传一个测试文件 → 发生了什么？
  → 显示识别结果
  → ✅ 核心功能链路完整

路径 B：首次用户（空数据）

这是上线后第一个用户必然经历的路径。AUDIT 只检查代码，这里验证实际渲染。

前置条件：数据库清空（模拟新用户第一次打开）

Step 1: 打开 http://localhost:3000 → 看到什么？
  → 页面正常加载，没有白屏
  → ✅ 空数据库不导致崩溃

Step 2: 核心页面在空数据下怎么显示？
  → 列表区域显示空状态占位（不是空白，不是报错）
  → ✅ 空状态处理正确

Step 3: 空状态下点击核心操作按钮 → 发生了什么？
  → 能正常进入下一步（如上传页面），不卡死
  → ✅ 空状态不影响功能入口

路径 B 的任何一步出现白屏或未捕获异常 → 返回 Phase 8（BUILD）修复，然后重新 E2E 的两个路径都重跑。

每步记录实际输出。任何一步断了 → 返回 Phase 8（BUILD）修复对应 task，然后重新 E2E。

纪律

• 不跳过任何步骤，不接受"应该可以"：每一步都要实际跑
• 测试数据只用假数据（不用真实数据）
• E2E 链路断了不硬修：回 Phase 8（BUILD），定位到具体 task
• 最多修复 3 次，3 次后仍失败 → 记录到 BLOCKED，标记为已知问题，在 HANDOFF 中坦白

输出

E2E 走查记录（每步的命令 + 实际输出 + ✅/❌）

---

Phase 11：SATISFACTION GATE（满意度门禁）

门禁：必入

→ 执行满意度门禁（详见 hlvibes/references/satisfaction-gate.md）。当前阶段名称：「代码构建」。

---

Phase 12：HANDOFF

门禁：满意度门禁通过

12.1 特性开关清理

如果 Phase 7 GATE 中创建了特性开关（feature flags），在 HANDOFF 前执行轻量清理：

1. 扫描 flags 配置（或 NEXT_PUBLIC_FLAG_* 环境变量）
2. 对每个 flag：
   • 如果 E2E 已验证通过且 flag 默认开启 → flag 可以永久化：移除 flag 判断，保留 flag-on 分支的代码，删除 flag-off 分支
   • 如果 flag 仍默认关闭（仍在灰度中）→ 记录到 BUILD_LOG 遗留问题，注明"flag X 待验证后移除"
3. 清理后运行 npx tsc --noEmit 确认编译通过

纪律：不强制移除。AI 判断可安全移除的自动移除；有疑问的标记为遗留。

12.2 交付

→ 执行交付（详见 hlvibes/references/handoff.md）。产出 .vibe/doc/BUILD_LOG.md。下一步：vibe-review（自动路由）。

BUILD_LOG.md 格式

# Build Log：[项目名]

> 构建时间: [日期] | Spec: REQUIREMENTS.md rN + ARCHITECTURE.md rN | 最后 commit: [hash]

## 完成统计
- 总任务数 / 已完成 / 并行组 / Commits

## 审计结果
- 假代码扫描 / 偏离 spec / 安全基线

## E2E 走查
- 用户故事 / 步骤 / 结果

## 偏离记录·遗留问题·下一步
- 特性开关状态（如 GATE 阶段创建过 flag）：X 个已清理 / Y 个遗留

额外产出

• 创建根目录软链：REQUIREMENTS.md → .vibe/doc/REQUIREMENTS.md，ARCHITECTURE.md → .vibe/doc/ARCHITECTURE.md

---

项目目录约定

生成的代码直接放在项目根目录，不额外嵌套 src/：

项目根目录/
├── .vibe/                        ← vibe 体系产出
├── app/                          ← 页面路由（Next.js App Router）
├── components/                   ← 可复用组件
├── lib/                          ← 工具函数、数据库连接
├── public/                       ← 静态文件
├── types/                        ← TypeScript 类型（如需要）
├── package.json
├── tsconfig.json
├── .gitignore
├── REQUIREMENTS.md               → 软链到 .vibe/doc/REQUIREMENTS.md
└── ARCHITECTURE.md               → 软链到 .vibe/doc/ARCHITECTURE.md

---

设计原则

• Spec is Law：ARCHITECTURE.md 和 REQUIREMENTS.md 是代码的唯一合法来源
• 原子执行：1 task = 1 独立 subagent，干净上下文
• 证据优先："做好了" = 验收命令通过 + E2E 实际跑通
• 假代码零容忍：8 种模式任一种出现，不进入 HANDOFF
• 偏离透明：任何和 spec 不一样的地方必须记录+你确认
• 上下文可恢复：progress.md 保证会话中断后能继续
• 你只在高风险时参与：认证、支付、删除数据，其他全自主

---

问题覆盖

#	问题	解法
1	AI 忘东西	Phase 1 显式 Read spec 文件；Phase 8（BUILD）每 3-5 task 写 progress.md
6	忽略问题	Phase 9（AUDIT）强制全量扫描，不过不进入 HANDOFF
7	说做了没做	Phase 8（BUILD）TDD 循环逐条验收；Phase 10（E2E）实际运行
8	不对齐 spec	Phase 6（DECOMPOSE）每个 task 绑 spec 溯源；Phase 9（AUDIT）交叉检查
9	自己乱来	Phase 8（BUILD）subagent 约束：不准碰其他文件、不准加未授权技术
10	模块不接	Phase 10（E2E）从头走到尾，哪断修哪
11	假代码	Phase 9（AUDIT）10 项检查硬性门禁扫描

---

通用纪律（所有 Phase 共享）

→ 完整通用纪律见 hlvibes/references/common-rules.md。