Vibe Coding Architecture

---
name: vibe-coding-architecture
description: >-
  教非技术背景的人看懂技术架构、做好技术选型——把"只会照搬话术的小白"练成"能看穿方案好坏的人"。
  当用户问"该用什么技术/框架"、"帮我选技术栈"、"AI 给的方案我看不懂"、"这几个方案怎么选"，
  或者需要把 demo 做成更正经的东西、要理解 AI 提出的架构时，使用此 Skill。
  这是 vibe-coding-kit 套件里负责"成长"的核心 Skill：用 6 个大白话维度拷问任何方案，再配五步决策法做选择。
  即使用户没明说"架构"二字，只要 ta 面对多个技术方案不知道怎么选、或看不懂 AI 的技术建议，就应主动用本 Skill。
---

# 架构选型：从看不懂，到自己会判断

这是 **vibe-coding-kit** 里负责"让你成长"的 Skill。目标不是教你写代码，而是给你一套**看懂任何技术方案、拷问任何选型**的框架。用得越多，你越不需要照搬话术——因为你已经懂了。

> 前一步是 `vibe-coding-requirements`（把需求说清）。选完技术后，去 `vibe-coding-production` 处理上线。开发全程配合 `vibe-coding-survival` 避坑。

## 给使用者的话

技术上的事，**你不需要会写，但要逐步学会看懂和判断**。一开始你靠下面的话术问 AI，几个项目之后，你会发现自己已经能直接看穿方案好坏——那就是这个 Skill 想把你带到的地方。

---

## 准入检查（开始本阶段前必做）

本 skill 是流程第二阶段 **S2·架构选型**。开始前：

1. **读 `docs/进度账本.md`。** 确认 **S1 需求对齐的出口门已过**（prd.md / 需求基准描述齐了）。**没过就别开始选型**——需求没定，方案必然脱离现实；先回 `vibe-coding-prd` 或 `vibe-coding-requirements` 补完 S1。
2. 向用户报一句："需求已就绪，进入 S2 架构选型。"
3. 本阶段三步对应账本：**S2.1 六维度拷问 → S2.2 五步选型 → S2.3 项目结构（`可选`）**。每过一步回写账本。

---

## 一、架构素养速成：看懂任何方案的 6 个维度 ★（对应 S2.1）

**所谓"看懂架构"，本质上就是看懂下面这 6 个维度。** AI 给你的任何方案，都可以拿这 6 条逐条拷问——拷问得多了，你就成行家了。

| 维度 | 大白话是什么 | 它决定你该问什么 |
|------|------------|----------------|
| **1. 数据存哪、留不留得住** | 数据是写进硬盘/数据库（关机还在），还是只在内存里（关机就没）？ | "关机重开后数据还在吗？存在哪？" 这是 demo 和正式系统最大的分水岭。 |
| **2. 在谁的机器上跑** | 跑在你自己电脑上，还是一台一直开着的服务器上？要联网才能用，还是离线也行？ | "这东西要一直开机才能用吗？谁来开着它？没网能用吗？" |
| **3. 一坨还是拆开** | 整个程序是一个进程（单体），还是拆成好几个服务各跑各的（拆分/微服务）？ | "能不能一个进程就跑起来？" 对个人维护者，**一坨通常远好过拆开**——拆开是给大团队准备的负债。 |
| **4. 依赖了多少外部东西** | 这方案站在多少"别人造的东西"上：第三方库、外部 API、云服务？ | "它依赖哪些外部东西？哪个挂了我就跟着挂？少装点行不行？" 每个依赖都是未来可能坏掉、可能收费的点。 |
| **5. 即时还是排队** | 用户一点就要马上出结果（同步），还是可以先收下、后台慢慢处理（异步/队列）？ | "如果某一步很慢，会不会卡住整个系统？慢操作能不能放后台？" 简单场景别提前上队列。 |
| **6. 多少人用才扛不住** | 现在的方案，1 个人用没问题，那 100 个、10000 个同时用呢？ | "大概多少人同时用会扛不住？" 但**新手最常见的错是过度担心这个**——先按真实人数设计，扛不住了再升级，别为想象中的百万用户提前把方案搞复杂。 |

**怎么用：** 让 AI 列方案后，对每个方案用这 6 个维度问一遍，尤其第 1、3、4 条——这是个人项目最容易出事的地方。能把这 6 条问顺，你就有了基本的架构判断力。

> 隐藏好处：看懂架构，你能更准地判断"**这件事我到底能不能自己搞定**"——包括什么时候该收手找真人工程师（见 `vibe-coding-survival` 的「红线」）。会判断边界，也是行家的一部分。

---

## 二、把 AI 当老师：边做边学

你身边坐着一个不嫌烦、随叫随到的技术老师。别只让它干活，要让它教你。每个项目都这么做，几个项目下来你就脱胎换骨：

- **要大白话解释：**"用一个生活里的例子解释这个方案，假设我完全不懂技术。"
- **逼它讲取舍：**"为什么选这个方案，不选另一个？它好在哪、差在哪？"——行家和小白的区别，就在于懂不懂"为什么"。
- **攒自己的词汇表：** 遇到不懂的词，让 AI 一句话解释，记进项目说明书。同一个词见三次，你就记住了。
- **项目结束做复盘：**"把这个项目我们做的架构决定和原因列一遍，我想记住这套思路，下次自己也能判断。"

---

## 三、技术选型五步决策法（对应 S2.2）

> `▸ 过门`：列方案 → 砍方案 → 选定一个，且每步都有理由 → 账本 S2.2 标 ✅。这是 S2 的核心步骤，不能省。

> **先查推荐库再开列方案。** 产品形态（prd S1.3）定了之后，**先翻 `references/技术栈推荐库.md`**，按平台（网站 / 小程序 / 移动端 / 后端接口）取那个 ★ 默认成熟栈作为起点——它已经替你挑出"最成熟、AI 写得最好、最好维护"的方案。再用下面五步法**拿现有资源清单去对照、砍掉、最终选定**。不要凭空让 AI 从零列方案——那容易跑偏成它训练里最常见的重栈。

**目标：** 从多个可行方案里，选出最适合你约束的那个。结合上面的 6 维度，你不只是逼 AI 摊开"代价"，更是在练自己的判断力。

**第一步 · 列菜单**
> "列出 3–5 种可行方案，每种用一句话说明核心思路，先不要展开细节。"

**第二步 · 曝代价**
> "对每个方案，告诉我：① 最适合什么场景 ② 最不适合什么场景 ③ 最大的隐性代价（部署多复杂、维护要花多少精力、我学起来难不难、出问题好不好查）。"

**第三步 · 约束过滤**——用你的真实约束逐条砍：

| 约束维度 | 砍掉什么 |
|---------|---------|
| 服务器配置 | 需要多进程、吃内存的方案 |
| 维护人力 | 需要专人盯着运维的方案 |
| 技术能力 | 你完全看不懂、出事全靠运气的方案 |
| 长期稳定性 | 依赖一长串第三方、哪个挂了都跟着挂的方案 |

**第四步 · AI 协作评估**（Vibe Coding 专属，最容易被忽略）：

| 评估项 | 问你自己 |
|--------|---------|
| AI 生成质量 | AI 用这技术写代码，一次跑通的概率高吗？ |
| 可读性 | 代码摆在你面前，你能大致看懂它在干嘛吗？ |
| 错误可描述性 | 出 bug 了，你能把错误信息完整复制给 AI 吗？ |
| 社区资料量 | 中文教程、网上现成答案多吗？ |

**第五步 · 维护成本裁决**
> 终极问题："一年后这系统出 bug，我还能不能自己（靠 AI）修好？" 修不动的方案，再先进也是坑。

**输出物：** 选定的技术栈 + 每个被否决方案的否决理由（写下来，防止过两周自己又动摇）。存进项目说明书。

**核心原则：** 复杂度是负债不是资产；你有权对 AI 的方案说不；从最简单的开始，不够用了再升级；依赖越少，维护越轻松。

---

## 四、项目结构设计（对应 S2.3 ·`可选`）

> `▸ 过门`：画出目录结构、每个目录一句话职责 → 账本 S2.3 标 ✅；只跑 demo、结构显而易见时可跳并留痕。

**目标：** 让 AI 给出清晰的目录结构，确保你知道每个文件大概干什么。

> "请给出这个项目的目录结构，每个目录/文件用一句话说明职责。遵循单一职责原则——每个目录只做一件事，不要把不相干的功能混在一起。"

**验收标准（你来检查）：**
- 你能指着每个目录说出"这是管 XX 的"。
- 没有那种"啥都往里塞"的杂物目录。

**输出物：** 项目目录树 + 每个目录的一句话说明。

---

## 常用追问话术

| 场景 | 话术 |
|------|------|
| 列方案 | "列出 3–5 种可行方案，每种一句话。" |
| 曝代价 | "每个方案的隐性代价是什么？" |
| 求简化 | "有没有更简单的做法？去掉不必要的组件。" |
| 求大白话 | "用一个生活里的例子解释这个方案，假设我完全不懂技术。" |
| 学取舍 | "为什么选这个方案，不选另一个？它好在哪、差在哪？" |
| 压复杂度 | "我的机器只有 X 配置，给我一个进程就能跑的方案。" |
| 问维护 | "一年后这方案出问题，修复流程是什么？" |
| 问数据 | "关机重开后，我的数据还在吗？数据存在哪？" |
| 问结构 | "给我画一下项目目录结构，每个目录干什么的。" |
| 复盘学习 | "把这个项目我们做的架构决定和原因列一遍，我想记住这套思路。" |

---

## 出口门（声称 S2 完成前必过）

> 以下约束来自项目治理配置 `harness.json`（`workflow.stages[S2].exit_gate`）和 `CLAUDE.md`。
> 在声称"选型阶段完成"之前，你必须逐条确认。
> **全过之后，最后一步：在 `docs/进度账本.md` 把 S2 标记为「已完成、出口门 ✓」，并提示用户"可进入 S3 上线准备（若要做成正式系统）"。**

### 必须产出的内容

- [ ] `docs/项目说明书.md` 中「选定技术栈」已填写
- [ ] `docs/进度账本.md` 中 S2 各必经步骤为 ✅（S2.3 目录结构可跳并留痕）
- [ ] `docs/项目说明书.md` 中「目录结构」建议填写（非强制）

### 硬性检查

- [ ] 「选定技术栈」中明确写出了**选定了什么方案**
- [ ] 「选定技术栈」中明确写出了**否决了哪些方案**及其否决理由
- [ ] 选定的方案与 PRD 中「形态与资源约束」的「它活在哪」兼容（如果 PRD 已存在）
- [ ] 目录结构中每个目录有一句话职责说明
- [ ] 没有"啥都往里塞"的杂物目录

### 自检完成声明

全部通过后声明：
"✅ S2 出口门通过：技术栈已选定并写入项目说明书，否决方案和理由已记录，账本 S2 已标完成。可进入 S3 上线准备。"