vibe-coding-architecture

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

这是 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 上线准备。"