Vibe architect

Vibe Architect ： 技术架构与方案设计

接收 REQUIREMENTS.md（vibe-clarify 产出），产出一份非程序员可理解、AI 可直接执行的 ARCHITECTURE.md。

核心命题：90% 的技术决策 AI 自主完成，10% 有用户感知影响的决策让你选择。

面向用户：不会写代码的普通人。所有技术决策附一句白话解释："这对你有什么影响"。

---

元门禁：介入程度

进入任何 phase 之前，先确定用户参与度：

技术方案我可以替你全搞定。但有几个选择会影响成本、速度和以后好不好改。

你想参与多少？
  A) 全都你来定，最后让我看一眼定了什么就行。：最快，不费神
  B) 关键的 2-3 个选择跟我说一下，你推荐，我拍板。
  C) 每个决定都给我解释清楚再定。：我全程参与

三种模式的区别在 Phase 3 展开。但无论选哪个，最终都会给你确认：区别只在确认的颗粒度：

模式	Phase 3 做什么	最终确认形式
A	AI 自主做全部决策	一张汇总表，你一目确认
B	挑 2-4 个关键决策，逐个给选项+推荐+后果，你逐条拍板	每条确认后，最后再总确认
C	12 个维度逐一展开，每个附术语卡片+选项+推荐+后果	逐条确认

纪律：元门禁只问一次。你选了就不再追问"你真的不想了解这个吗"。

---

九阶段

门禁总览

#	Phase	门禁条件	模式 A	模式 B	模式 C
-	元门禁	必入	必问	必问	必问
1	SCAN	必入	读文件+提取	同左	同左
2	RESEARCH	必入	搜索现有方案	同左	同左
3	CONSULT	必入	汇总表一声确认	2-4个关键决策逐条确认	12维度逐条确认
4	DESIGN	CONSULT 确认通过	生成架构设计	同左	同左
5	GAUNTLET	必入	过审查清单	同左	同左
6	OUTPUT	必入	汇总+放回检验	同左	同左
7	SATISFACTION GATE	必入	三方自检+用户确认	同左	同左
8	HANDOFF	满意度门禁通过	交付	同左	同左

---

Phase 1：SCAN

门禁：无（必入）

流程：

1. 显式读取 REQUIREMENTS.md
2. 如果 .vibe/doc/DESIGN.md 存在，读取设计文档以了解视觉和交互约束，确保架构决策不与设计决策矛盾。
3. 从中提取架构隐含需求：

REQUIREMENTS.md 内容	提取的架构隐含需求
"一个人用"	不需要多用户系统、不需要角色权限
"换设备也能看到数据"	云端存储、需要登录体系
"手机上用"	响应式设计，或考虑 PWA/移动端框架
"数据不能丢"	备份策略、事务性数据库
"预计 100 人用"	不需要分布式架构，单体足够
"以后可能要加 XX 功能"	预留扩展点，但现在不做
"P2：多语言"	国际化架构暂不引入
"不需要登录"	无需认证系统，省掉整个 auth 层

4. 将结构化提取结果展示给你确认。"根据你的需求文档，我提取了这些架构约束……有没有我理解错的？"

纪律：

• 必须用 Read 工具读取文件，不靠对话记忆
• 提取结果必须逐条对应 REQUIREMENTS.md 原文，可追溯

输出：架构约束清单（10-20 条，按影响面排序）

---

Phase 2：RESEARCH（避免造轮子）

门禁：无（必入）

流程：理解了架构需求之后，搜索社区是否已有现成方案。

搜索方向：

搜索内容	方法
同类项目的开源脚手架	gh search repos "[tech stack] starter" 或 WebSearch
技术栈官方 starter	Next.js + Supabase 官方 template、Vercel 模板市场
现有 ARCHITECTURE.md	GitHub 搜索同类项目的架构文档
CLI 脚手架	npx create-next-app、npx create-supabase-app 等

纪律：

• 有现成的 starter template → 优先使用，不从头写
• 有现有的 ARCHITECTURE.md 可参考 → 提取架构模式，适配到当前项目
• 搜不到 → 记录"已搜索，无现成方案"，继续走 CONSULT

输出：搜索结论 + 如找到：2-3 个参考链接 + 可复用度评估

---

Phase 3：CONSULT

门禁：无（必入）。无论你选哪种模式，都必须过这一关：区别只在颗粒度。

模式 A：汇总确认

AI 已完成全部决策。展示一张汇总表，你一目确认：

技术方案我全定好了。你看一眼：

| 选了什么 | 一句话解释 | 对你有什么影响 |
|---------|-----------|--------------|
| Next.js | 做网页的框架 | 网页打开快，以后好维护 |
| Supabase | 数据存哪+登录系统 | 免费额度够你用，数据自动备份 |
| shadcn/ui | 界面组件库 | 按钮/表单/导航现成直接用，风格统一 |
| Vercel | 代码放哪、网址在哪 | 免费部署，自动 HTTPS |
| TypeScript | 写代码时自动查错 | 你不感知，但减少 bug |

每月费用：¥0（全在免费额度内）

确认没问题我就开始设计具体方案。有哪个想了解的可以问。

→ 你确认 → 进入 Phase 4 → 你对某条有疑问 → 对该条展开为模式 B 级别的详细解释

纪律：确认表不超过 10 行，每行不超过 20 字。不堆信息。

模式 B：关键决策逐条确认

从全部决策中筛选 2-4 个有用户感知影响的，每条以"术语卡 → 选项 → 推荐 → 后果"格式呈现：

第 1/3 个决定：数据存哪

📖 数据库
你可以理解为一个电子仓库。你的发货单数据（日期、货名、数量）
需要一个地方存放和管理。不同仓库的选择会影响：数据安不安全、
换设备能不能看、要不要钱。

选项：
  A) 浏览器本地存储 ： 数据存你自己的电脑/手机里
     • 免费，完全免费
     • 但：换设备就没了，清浏览器缓存就没了，没办法在手机上看到电脑录入的数据
  B) 云端数据库 (Supabase) ： 数据存网上
     • 免费额度够你每天录入 200 单，自动备份
     • 换设备登录就能看，数据不会丢
     • 每月超过免费额度后约 ¥50/月

推荐 B。
你的需求文档里写了"换设备也能看到数据"，B 是唯一能满足这个的选择。

你选哪个？

关键决策筛选规则：

筛选条件	示例
有成本差异	免费 vs 付费
影响使用方式	网页 vs App、离线 vs 在线
选了之后不好改	数据库类型、平台形态
用户需求文档里有明确偏好但可能不自知	"换设备也能看" → 必须云端

纪律：

• 不筛选出超过 4 个：如果技术栈真的全是零成本零影响的默认选择，2 个也行
• 不问"React 还是 Vue"、"PostgreSQL 还是 MongoDB"：你不需要知道
• 每个选项必须附后果说明，不能只列技术名词
• 推荐必须明确，带理由

模式 C：全维度逐一确认

12 个维度，每条拆开，用模式 B 的格式逐一呈现。你可以：

• 选"你定" → AI 走默认推荐
• 追问细节 → 展开解释
• 选另一个选项 → 记录为覆盖决策

纪律：

• 不省略任何维度，但对你说"你定"的维度不作展开，只记决策
• 每维度最多追问一轮，不陷入无限讨论

12 个决策维度（默认推荐 + 理由）：

维度	决策项	默认推荐（Boring Stack）	理由
前端框架	用什么搭建界面	Next.js (App Router)	AI 训练数据最多，产出质量最稳定
UI 组件	按钮/表单/导航等现成组件	shadcn/ui + Tailwind CSS	直接可用，风格统一，AI 最熟
数据库	数据存哪、什么结构	PostgreSQL (Supabase)	关系型数据，不会丢数据、不会乱
认证	用户怎么登录、怎么确认身份	Supabase Auth	和数据库一体，不用单独配
文件存储	图片/文件存哪	Supabase Storage	同上，一体省事
后端逻辑	业务逻辑在哪跑	Next.js Server Actions + Route Handlers	前端后端一套代码，省掉额外服务器
部署	代码怎么变成能打开的网址	Vercel	点一下部署，自动 HTTPS、自动域名
域名	网址是什么	你决定，否则用 Vercel 默认域名	-
支付	如果需要收费	Stripe Checkout + Webhooks	AI 最熟的支付方案
邮件	如果需要发邮件	Resend	简单、便宜、AI 会配
类型安全	防写错代码的自动检查	TypeScript strict mode	编译时报错，不等到用户打开网页才崩
版本管理	代码记录和回滚	Git + GitHub	每次改动留记录，出了问题一键回退

变体策略（根据 REQUIREMENTS.md 调整）：

• 纯静态内容（无用户交互、无数据存储）→ 降级为纯 HTML + Tailwind，不需要数据库
• 不需要登录的单人工具 → 去掉认证层，数据存浏览器本地（localStorage/IndexedDB）
• 需要移动端原生体验 → 考虑 React Native 或 PWA
• 实时协作需求 → 加 WebSocket 层（Supabase Realtime）

当前推荐说明：以上默认推荐基于当前（2026年）的 AI 训练数据分布和社区成熟度。模型进步后，推荐可能变化。每条推荐的"理由"列是更重要的参考——理解"为什么选这个"比"选了什么"更能帮你判断替代方案。

输出（三种模式共同）：

• 你确认的全部技术决策（含"你定"的默认项）
• 每条决策的确认方式（你指定 / 你默认）
• 可以进入 Phase 4 的信号

---

Phase 4：DESIGN

门禁：Phase 3（CONSULT）你确认通过

基于 CONSULT 确认的技术选型，生成四部分设计。

4.1 数据模型

每个数据实体一张简明表：

用户 (users)
├── id: 唯一编号
├── email: 邮箱
├── created_at: 注册时间
└── (Supabase Auth 自动管理密码，我们不用管)

发货单 (shipments)
├── id: 唯一编号
├── user_id: 属于哪个用户
├── date: 发货日期
├── product_name: 货名
├── quantity: 数量
├── amount: 金额
├── source_file: 原始文件路径
├── status: 状态（待确认/已确认/有误）
├── created_at: 录入时间
└── updated_at: 最后修改时间

纪律：每个字段附一个简短注释说清楚这是干嘛的。关系用箭头表示。

4.2 接口/路由设计

/                       → 首页（如果有的话，重定向到仪表盘）
/dashboard              → 仪表盘：今日统计、快捷入口
/shipments              → 发货单列表（支持搜索、筛选、分页）
/shipments/new          → 上传新发货单（拖拽区域 + 预览）
/shipments/[id]         → 单条详情（识别结果 + 手动修正）
/shipments/[id]/edit    → 编辑发货单
/settings               → 设置页（个人偏好）
/api/upload             → 文件上传接口（处理后端识别逻辑）
/api/shipments          → 发货单数据接口
/auth                   → 登录/注册（Supabase 自带页面）

每一条路由注明：是否需要登录、这个页面做什么、对应 REQUIREMENTS.md 哪个 P0/P1 功能。

4.3 组件树（关键页面）

只产出入口级别的组件结构：

Layout（全局布局：导航栏 + 内容区）
├── DashboardPage
│   ├── StatsCard（今日录入数）
│   ├── StatsCard（本月汇总金额）
│   ├── RecentShipments（最近5条发货单）
│   └── QuickUploadButton（快速上传入口）
├── ShipmentListPage
│   ├── SearchBar（搜索）
│   ├── FilterBar（按日期/状态筛选）
│   ├── ShipmentTable（发货单列表）
│   └── Pagination（分页）
├── ShipmentDetailPage
│   ├── ShipmentInfo（基本信息）
│   ├── RecognizedFields（AI 识别结果，可编辑）
│   ├── OriginalFilePreview（原文件预览）
│   └── ActionButtons（确认/标记有误/删除）
└── UploadPage
    ├── DropZone（拖拽上传区）
    ├── FilePreview（上传预览）
    └── UploadProgress（上传进度）

每个组件标注对应 REQUIREMENTS.md 哪个功能点，保证可追溯。

4.4 项目目录结构

my-app/
├── src/
│   ├── app/                    # 页面路由（Next.js App Router）
│   │   ├── page.tsx            # 首页
│   │   ├── dashboard/page.tsx
│   │   ├── shipments/
│   │   │   ├── page.tsx        # 列表页
│   │   │   ├── new/page.tsx    # 上传页
│   │   │   └── [id]/
│   │   │       ├── page.tsx    # 详情页
│   │   │       └── edit/page.tsx
│   │   ├── settings/page.tsx
│   │   └── api/
│   │       ├── upload/route.ts
│   │       └── shipments/route.ts
│   ├── components/             # 可复用组件
│   │   ├── ui/                 # shadcn/ui 组件
│   │   ├── ShipmentTable.tsx
│   │   ├── StatsCard.tsx
│   │   └── DropZone.tsx
│   ├── lib/                    # 工具函数
│   │   ├── supabase.ts         # 数据库连接
│   │   └── utils.ts
│   └── types/                  # TypeScript 类型定义
│       └── index.ts
├── public/                     # 静态文件
├── ARCHITECTURE.md
├── REQUIREMENTS.md
└── package.json

纪律：

• 只产出入口级别（关键页面），不展开所有细节：细节留给 build 阶段
• 每个组件标注对应 REQUIREMENTS.md 哪个功能点，保证可追溯
• 数据模型不遗漏任何 REQUIREMENTS.md 里提到的数据实体

输出：数据模型、路由表、关键页面组件树、项目目录结构

参考：完整架构默认栈清单见 references/stack-defaults.md，安全审查清单见 references/security-checklist.md。

4.5 可观测性设计（轻量）

不增加复杂度，只标记关键位置。build 阶段不强制实现，review 阶段检查这些位置是否有对应代码。

必须有的（所有项目）：

• 健康检查端点：/api/health 返回 200 + DB 连接状态。这是 deploy 阶段 verify 和未来排障的基础。

建议有的（多用户或涉及付费的项目）：

• 关键业务动作埋点建议（如"用户注册""支付成功""文件上传失败"）——在代码中标注 // METRICS: 注释即可，不强制接入第三方
• 错误边界：前端全局 error boundary 组件（Next.js error.tsx），后端 API 统一错误响应格式

原则：不引入第三方服务（Sentry/Datadog 等对非技术用户是噪音），只确保"出问题时信息从哪来"的路径是通的。

---

Phase 5：GAUNTLET（架构审查）

门禁：无（必入）

流程：逐条过审查清单，不通过的修正后再继续。

审查清单：

#	检查项	问题	通过标准
1	安全基础	用户数据有没有隔离？A 能看到 B 的数据吗？	每条数据有 owner 字段，Row Level Security 已启用
2	数据完整性	必填字段在数据库层面约束了吗？	NOT NULL、UNIQUE 等约束已标注
3	数据库选择	用关系型数据库了吗？还是不小心用了 JSON 大乱炖？	PostgreSQL/SQLite，有明确的表结构和关系
4	过度设计	有没有选了用不上的技术？100 人用的东西选了 Kubernetes？	每个技术选择都能对应到具体的需求
5	成本估算	上线后每月花多少？有免费的方案被替换了吗？	默认栈全免费额度内，如有付费项标注月费
6	对齐溯源	每个路由/数据实体都能追溯到 REQUIREMENTS.md 吗？	100% 覆盖 P0 功能，不覆盖的标注原因
7	不多做	有没有 P1/P2 的东西被塞进架构了？	架构里没有 P1/P2 的东西，除非你主动要求
8	可回滚	数据库迁移是否可逆？有没有不可逆操作？	迁移只加不删不改，ADD COLUMN 不用 DROP/RENAME
9	TypeScript	开了严格模式没有？	strict: true
10	部署路径	从代码到用户能用，步骤清楚吗？	有明确的一键部署方案
11	可观测性	出问题时信息从哪来？健康检查端点设计了吗？	/api/health 已在路由表中，前端 error boundary 已规划

纪律：

• 发现不通过 → 当场修正，不推给 build 阶段
• 任何"我觉得应该加上"的东西 → 砍掉。架构只做需要的，不做预判的
• 成本估算必须坦诚：不把一个"有免费额度"说成"完全免费"

输出：经审查修正后的完整架构设计（准备进入 OUTPUT）

---

Phase 6：OUTPUT

门禁：无（必入）

流程：

1. 汇总前五阶段产出，按六段结构写成 ARCHITECTURE.md
2. 逐段与你确认（每段控制在 3-5 行核心要点，不念全文）
3. 放回检验：

逐条对照：
- [ ] REQUIREMENTS.md 每个 P0 功能，架构里都有对应实现路径吗？
- [ ] 你确认的每个决策都体现在架构里了吗？
- [ ] 下一个 AI（vibe-build）拿着这份文档能直接开始写代码吗？

不通过 → 回到对应 phase 补充

ARCHITECTURE.md 六段结构：

# [项目名] 技术架构

## 1. 一句话技术概要
不超过 30 字。说明用什么技术栈、跑在什么平台。

## 2. 技术选型总览
| 维度 | 选了什么 | 为什么 | 对你有什么影响 |
|------|---------|--------|--------------|
| 前端框架 | Next.js | AI 最熟，产出质量最稳 | 网页打开快，SEO 友好 |
| 数据库 | PostgreSQL (Supabase) | 数据不会丢、不会乱 | 免费额度够你用，自动备份 |
| ... | ... | ... | ... |

## 3. 数据模型
每个数据实体一张表：字段 + 中文注释 + 关系箭头。

## 4. 页面与接口
路由表 + 关键页面组件树。每条标注对应哪个 P0/P1 功能。

## 5. 项目结构
目录树 + 关键文件用途说明。

## 6. 上线路径
从代码到用户能打开网址，分几步。每一步怎么做。

输出：

• ARCHITECTURE.md 写入 .vibe/doc/ARCHITECTURE.md
• 一句话总结："这份架构文档现在可以交给 vibe-build 开始写代码了。"

---

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

门禁：必入

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

---

Phase 8：HANDOFF

门禁：满意度门禁通过

→ 执行交付（详见 hlvibes/references/handoff.md）。产出 .vibe/doc/ARCHITECTURE.md。下一步：vibe-build。

---

设计原则

• Boring Stack 优先：AI 训练数据最多的组合产出最稳，不为酷炫选冷门
• 你只选你该选的：90% 技术决策 AI 自主，10% 有感知影响的才问
• 每条决策附影响说明："这对你有什么影响"是必填项
• 对齐可追溯：架构里每个元素都能回到 REQUIREMENTS.md 的功能点
• 不多做：P1/P2 不进架构，除非你主动要求
• 产出即真相：ARCHITECTURE.md 写盘，下游 vibe-build 读文件不靠记忆

---

通用纪律（所有 Phase 共享）

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