给产品经理：上一节我们把"想做什么"翻译成了 SPEC、ARCHITECTURE 与 ROADMAP 三份文档。这一节要回答的问题是——这堆文字怎么变成第一个能跑起来的工程？答案就是脚手架（Scaffolding）。脚手架不是一份"代码"，而是一组初始化的目录、依赖、配置文件，它决定了团队接下来几个月每天敲下的每一行代码长什么样。技术选型，则是决定脚手架"用什么砖"的过程。

给工程师：6.1 输出了 SPEC.md / ARCHITECTURE.md / ROADMAP.md，但从架构图到 pnpm dev 跑起来之间有一道鸿沟——脚手架与版本锁定。本章重点拆解 2026 年主流脚手架的演进、Claude Code 在选型与初始化阶段的协作姿势，以及如何把团队规范写成 CLAUDE.md 和 Skills，让"第一行代码"开始就长在团队基因里。

承接 6.1，需求与架构方案已经躺在 docs/ 目录里。接下来一周，团队每天会被问到的不是"做什么"，而是"用 Vite 还是 Webpack"、"Pinia 还是 Zustand"、"PostgreSQL 还是 MySQL"。这些问题如果在脚手架阶段没想清楚，三个月后会以"重构"或"技术债"的形式收回利息。本节会把脚手架与技术选型当作一个完整的工程动作来讲，并演示 Claude Code 在每一步如何降低决策成本。

为了让阅读节奏更明确，本章会按"演进 → 协作 → 方法论 → 实战 → 风险"五段递进。前两节铺垫认知，第三节给可复用的判断框架，第四节用一个 30 分钟的真实回放把所有概念串起来，最后一节列出工程师不能让渡的决策与 AI 自动化的反噬。读完本章你应当能独立完成：让 Claude 推荐脚手架候选、用 Plan 模式控制初始化节奏、把团队规范写成可执行的 CLAUDE.md 与 Skills、识别选型阶段的常见陷阱。

一、脚手架工具的现代演进

给产品经理：脚手架（Scaffolding）就像装修前师傅按户型图搭的钢架，决定了哪里是承重墙、哪里能改。早些年前端工程师手动写一堆配置，后来出现一键生成命令，再后来连"一键"都被 AI 接管。理解这段演进，有助于你判断技术方案是不是"现代"。

1.1 从 create-react-app 到 Vite/Turborepo

回溯一下时间线：

• 2016 年，Facebook 推出 create-react-app（CRA），用一条命令完成 React 项目初始化。它隐藏了 Webpack、Babel 配置，让上手门槛骤降。代价是配置黑箱、构建慢、很难在不"eject"的情况下定制。
• 2017 年，Vue 团队推出 vue-cli，思路相似：模板化项目、可选 preset。
• 2020 年，Vite 由尤雨溪发起，利用浏览器原生 ES Module 与 esbuild/Rollup，把开发服务器冷启动从十几秒压到几百毫秒。这种数量级的提速直接终结了"create-react-app 时代"。React 官方文档此后也不再推荐 CRA，转而引导用户使用 Vite、Next.js、Remix 等元框架。
• 2022 年起，Turborepo、Nx、Moon 等 Monorepo 编排工具兴起，把"脚手架"从单包扩展到多包，加入远程缓存、增量构建、任务图。
• 2024 年起，Bun、Deno、Rolldown、Rspack 等新一代运行时和打包器陆续进入生产，业界普遍认为 esbuild/Rollup 仍是当前生态最主流的组合，但 Rust 系工具链增长迅速。

时间走到 2026 年，"脚手架"这个词的含义已经从"生成模板"扩展为"项目初始化 + 任务编排 + 缓存策略 + 类型与 Lint 体系 + AI 协作约定"。一个现代脚手架的产物，往往不只是一个 package.json，而是一整套包括 pnpm-workspace.yaml、turbo.json、tsconfig.base.json、.eslintrc、.prettierrc、CLAUDE.md、.claude/ 在内的"工程身份证"。

1.2 不同领域的主流脚手架（前端/后端/Monorepo/CLI）

下表整理 2026 年常见脚手架（具体版本号在使用前请用 npm view <pkg> version 校验）：

PM 需要记的不是命令，而是这一层判断：**做的是 SPA 还是需要 SEO？是单包还是多包？团队是 TS/JS 为主还是混合 Python？**这三个问题决定了脚手架的大方向。

为了便于和工程师沟通，下面给一组"翻译卡"，把 PM 常说的需求术语映射到对应的脚手架选项：

这张表本人在和非技术同事开会时会贴白板上，避免大家在术语层面来回打转。

1.3 脚手架背后的技术选型隐含决策

每一个 pnpm create vite 的回车，都同时按下了一连串隐含决策：

1. 包管理器：pnpm 还是 npm/yarn/bun。pnpm 节点链接策略对 Monorepo 友好；bun 速度极快但生态尚在补齐；corepack 在团队全局环境里被本人禁用，原因是它会拦截命令。
2. 打包器：Vite（基于 Rollup/Rolldown）、Webpack、Rspack、Turbopack、Parcel。
3. 运行时：Node.js、Bun、Deno。Bun 与 Deno 提供更现代的标准库，但生产稳定性需要按业务评估。
4. TS 编译策略：tsc、esbuild、SWC、Babel。esbuild/SWC 速度快，但严格类型检查仍需 tsc。
5. 测试框架：Vitest、Jest、Playwright、Cypress。
6. Lint/Format：ESLint v9 flat config、Biome、Oxlint、Prettier、dprint。Biome 与 Oxlint 把 lint+format 合一并带来数十倍提速。
7. 目录约定：src/ vs app/ vs pages/，单包扁平 vs Monorepo packages/*。
8. CI/CD 假设：Turborepo 的 remote cache 默认假设有 Vercel 账号或自建 cache；Nx Cloud 同理。

工程师常犯的错是把第 1～8 项分别视为独立选择。事实上它们高度耦合：例如 Bun + Vite + Vitest 是一条流畅链路，混用 Bun + Webpack + Jest 则水土不服。脚手架的价值，正是把这些耦合预先收敛成一个可工作的组合。

举个具体例子。下面是一份本人脚手架阶段会让 Claude 生成的 tsconfig.base.json，每一行都对应一个隐含决策：

// tsconfig.base.json — Monorepo 共享 TS 配置
{
  "compilerOptions": {
    "target": "ES2022",            // 目标运行时 = Node 20+ / 现代浏览器
    "module": "ESNext",            // 输出 ESM，需配套 package.json 的 "type": "module"
    "moduleResolution": "Bundler", // 让 TS 与 Vite/esbuild 的解析行为一致
    "strict": true,                // 强类型，TEMP-S 中的 M（可维护性）核心保障
    "noUncheckedIndexedAccess": true, // 数组/对象索引返回 T | undefined，防止运行时炸
    "exactOptionalPropertyTypes": true,
    "skipLibCheck": true,          // 跳过 node_modules 类型检查，加速 tsc
    "verbatimModuleSyntax": true,  // 与 isolatedModules 配套，使 import type 不被擦除
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}

这份配置不是"复制粘贴模板"。moduleResolution: "Bundler" 决定了下游必须用 Vite/esbuild/SWC 而不是 ts-node 直跑；noUncheckedIndexedAccess 会让团队全部代码都被迫处理 undefined，这是一个文化决策。脚手架阶段的每一个 flag，都是给未来三年的工程文化埋一颗钉子。

二、与 Claude 协作完成脚手架搭建

给产品经理：这一节展示一个真实场景——你只用一句话告诉 Claude 想做什么，它先反问、再列计划、再敲命令。你不需要懂 npm，但你能从对话里看出 Claude 在做哪些选择，以及哪些选择需要你拍板。

2.1 用自然语言描述项目需求并让 Claude 推荐

打开 Claude Code，最合适的开场不是"建一个 Vue 项目"，而是把 6.1 的成果摆出来：

我把 SPEC.md 和 ARCHITECTURE.md 放在 docs/ 下了。
请基于这两份文档，推荐脚手架与技术栈，要求：
1. 列出至少两套候选组合，写明各自取舍
2. 默认偏好 TypeScript + Vue 3 + Vite，但如果你认为不合适请直接说
3. 暂时不要执行任何命令，先输出对比表

这条 Prompt 有几个关键动作：让 Claude 读已有文档（它会调用 Read）、显式约束输出形式（对比表）、禁止过早执行（避免它直接 npm create）。Claude 的回复通常是一张技术栈对比表，列出各自的依赖、CI 假设、学习曲线。

2.2 Plan 模式如何在执行 npx/pnpm create 前展示完整步骤

确认方案后，进入 Plan 模式（Shift+Tab 切换），让 Claude 先给完整计划：

进入 Plan 模式。基于上一步选定的"TypeScript + Vue 3 + Vite + pnpm + Vitest + ESLint flat config"组合，
请给出从空目录到第一次 git commit 的完整步骤计划，包括：
- 每一步的命令
- 命令产生的文件清单
- 中间需要我确认的决策点

Plan 模式下，Claude 不会直接执行 Bash，而是返回一份分阶段方案，例如：

Phase 1 — 初始化
  - 步骤 1.1: pnpm create vite@latest my-app --template vue-ts
  - 步骤 1.2: cd my-app && pnpm install
  - 决策点: 是否启用 strict mode？是否引入 vue-router/pinia？

Phase 2 — 工程规范
  - 步骤 2.1: 安装 eslint@9 + @typescript-eslint + eslint-plugin-vue
  - 步骤 2.2: 创建 eslint.config.ts (flat config)
  - 步骤 2.3: 安装 prettier 与 eslint-config-prettier

Phase 3 — 测试与 CI
  - 步骤 3.1: 安装 vitest + @vue/test-utils + jsdom
  - 步骤 3.2: 配置 vitest.config.ts
  - 步骤 3.3: 创建首个 smoke test

Phase 4 — 团队协作约定
  - 步骤 4.1: 撰写 CLAUDE.md
  - 步骤 4.2: 配置 .claude/settings.json
  - 步骤 4.3: 首次提交

只要审查这份计划没问题，按 Esc 退出 Plan 模式，再回一句"按计划执行"，Claude 会按 ROADMAP 一步步动手并停在每个决策点等你拍板。这种"先看再做"的姿势，是脚手架阶段防止 AI 自由发挥的最有效手段。

2.3 Claude 阅读项目结构并撰写 CLAUDE.md

脚手架跑完，目录大致长这样：

my-app/
├── public/
├── src/
│   ├── assets/
│   ├── components/
│   ├── composables/
│   ├── router/
│   ├── stores/
│   ├── views/
│   ├── App.vue
│   └── main.ts
├── tests/
├── .claude/
├── eslint.config.ts
├── vite.config.ts
├── vitest.config.ts
├── tsconfig.json
└── package.json

接下来让 Claude 自己读完这棵树写 CLAUDE.md：

请阅读当前目录所有非 node_modules 文件，输出一份 CLAUDE.md。
要求：
- 项目概览（1 段）
- 关键脚本说明（dev/build/test/lint）
- 目录约定（每个一级目录用一句话描述）
- 编码风格（参考已生成的 eslint.config.ts，不要重复列出规则细节）
- 与 Claude 协作时必须遵守的禁忌（例如"不要修改 vite.config.ts 而不解释原因"）

生成的 CLAUDE.md 会成为团队后续每次启动 Claude Code 时自动加载的"项目记忆"，其作用相当于第一节里讲的那份"项目身份证"。

2.4 通过 Skills 把团队脚手架规范固化

CLAUDE.md 适合放静态规范，Skills 适合放可复用工作流。例如团队希望每次新建子包都遵循同一套结构：

.claude/skills/new-subpackage/
├── SKILL.md
└── template/
    ├── package.json.hbs
    ├── tsconfig.json.hbs
    └── src/index.ts.hbs

SKILL.md 描述触发词、参数、步骤；template 目录存模板文件。下次任何成员说"新建一个名叫 logger 的子包"，Claude 会按 skill 的步骤复制 template、改 package.json 名称、加入 pnpm-workspace、跑安装。这把"团队规范"从口头传承升级为可执行资产。本人项目里类似的做法是：所有 npm script 命名都按 dev:<subpkg-name> 而不是 <subpkg-name>:dev，这条偏好直接写进 skill 模板里，后来者新建子包时不会再写错。

2.5 MCP 服务器辅助技术选型（context7 / npm registry）

技术选型最大的风险是"训练数据时间窗口"。Claude 训练数据的截止日期早于今天，对最新版本号、Breaking Change 不敏感。解决办法是接入 MCP（Model Context Protocol）服务器，把实时信息源当作工具暴露给 Claude：

• context7：把开源项目文档变成可查询的 MCP 工具。问"Vite 7 的 environment API 怎么用"它会查 Vite 仓库官方文档而不是猜。
• npm registry MCP：查 npm view 实时版本与依赖，避免写出已经 deprecated 的依赖。
• GitHub MCP：查 issue、PR、release notes，决定要不要追新版本。

接入方式通常在 .claude/settings.json 里加一段：

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "npm-registry": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-npm"]
    }
  }
}

接好之后，对话里说"查 vite 最新稳定版与对应的 @vitejs/plugin-vue 版本"，Claude 会真的去查而不是脑补。MCP 是 Anthropic 在 2024 年底开源的协议，2026 年生态已相当丰富，凡是涉及外部数据源的选型都建议先接 MCP 再让 AI 推理。

下面给一段"接入 MCP 后选型"的对话片段，体现 MCP 的实际价值：

PM:    我们要做一个 PDF 在线签批工具，前端用 Vue 3，后端 Node。
       签批要支持手写签名图层。给我前端 PDF 渲染库的候选。

Claude(无 MCP): 推荐 pdf.js（Mozilla 维护）或 react-pdf。
                注意：react-pdf 是 React 生态，与 Vue 不直接兼容。

Claude(有 npm-registry MCP): 已查询：
  - pdfjs-dist：周下载约百万级，活跃维护，体积较大
  - @vue-pdf/* 系列：周下载较低，最近一次发布 6 个月前，需要谨慎
  - mupdf-js：商用许可证，请法务确认
  推荐：pdfjs-dist + 自封装 Vue 组件层。理由：唯一同时满足"维护活跃 + 许可证宽松 + 框架无关"的选项。

差别非常直接：没有 MCP 的回答更像"猜测 + 安全话术"，接了 MCP 之后回答带数据、带许可证提醒、带候选淘汰理由。技术选型的对话里，每多一个数据点，就少一个三个月后才暴露的雷。

三、技术选型方法论

给产品经理：选型不是技术品味问题，是风险管理问题。这一节给一个可以印在 A4 纸上的判断框架，帮你和工程师一起讨论时不至于被术语淹没。

3.1 选型决策框架（团队熟悉度/生态成熟度/可维护性/性能成本）

本人采用的简化框架是 TEMP-S 五维：

每一维打 1～5 分，做雷达图。雷达图未必精确，但能逼团队把直觉量化。

下面用 TEMP-S 评估"前端打包器"这个槽位作为示意（只是演示形式，具体分数按团队实际填）：

雷达图能直观告诉 PM："Vite 是当下平衡得最好的，但 Rspack 在性能维度有可见优势——如果项目规模超过 500 个组件，半年后值得评估迁移。"这种"今天选 A、什么时候考虑 B"的话语，比"用 Vite 因为它快"更有决策价值。

3.2 与 Claude 对话式选型——让 AI 罗列候选并比对优劣

把 TEMP-S 表喂给 Claude 是更聪明的用法：

请用 TEMP-S 框架评估"前端状态管理"这个槽位，候选：
1) Pinia
2) Zustand（搭配 Vue 适配层）
3) 自研 reactive store

约束：
- 团队是 Vue 3 + TypeScript
- 生态成熟度只看 2025 年至今的数据
- 输出 markdown 表格，最后一行是推荐项与理由

引用任何数据时，请通过 context7 / npm-registry MCP 查询，
没有可靠数据来源就明确写"无数据"，不要捏造数字。

这条 Prompt 同时启用了 MCP 工具与"无数据就写无数据"的反幻觉护栏。Claude 会输出一张可审查的对比表，工程师在表上批注，最终落到 ARCHITECTURE.md 的"技术选型记录"小节。

3.3 真实案例对照（Vue vs React、Express vs Fastify、SQL vs NoSQL）

以下案例不引用具体数字，只展示决策路径：

• Vue vs React：团队熟悉度决定一切。组合式 API 与 React Hooks 心智模型相近，但 SFC 的样式作用域与模板语法对设计师友好。如果团队曾用 React 三年以上，没必要为了"看起来更新"切到 Vue。
• Express vs Fastify vs Hono：Express 生态最广但性能最低；Fastify 在 Node 生态里性能与生态平衡较好；Hono 跨运行时（Cloudflare Workers / Bun / Node），适合边缘部署优先的项目。
• SQL vs NoSQL：业务能用主键 + 索引解决就用 PostgreSQL，需要灵活模式的领域（用户行为日志、IM 消息）再考虑 MongoDB / DynamoDB。一刀切"用 NoSQL 才现代"是反模式。

再举一个本人遇到的真实案例。某项目早期选型把"实时通知"映射到 Redis Pub/Sub + WebSocket，理由是"性能最强"。三个月后做多端同步时发现 Pub/Sub 没有"未读计数"语义，团队又叠了一层 Redis Sorted Set 维护已读偏移，再叠一层 MySQL 做持久化。最终架构图里有 3 套存储、2 条消息通路。回头看，第一性问题其实是"我们要的是消息流还是事件总线"——如果是消息流，从一开始就该选有持久化与游标的 Kafka / NATS JetStream / Redis Streams，而不是 Pub/Sub。这种"在错误抽象上叠层"的代价，远高于第一天多花两天选型。让 Claude 在 Plan 模式下显式列出"这个方案不适合什么场景"，能拦住相当一部分类似失误。

下面是本人沉淀的"AI 选型对话四问"，按顺序问完，幻觉率会显著下降：

1. "请列出至少 3 个候选方案，并按 TEMP-S 五维打分"
2. "请列出每个候选方案‘最不擅长的场景’"
3. "请列出推荐方案在未来 12 个月可能踩到的 3 个坑"
4. "如果团队 6 个月后想替换该方案，迁移成本最高的部分是什么？"

这四问的核心思想是：让 AI 不仅回答"选什么"，还回答"什么时候不该选"和"换走的代价"。AI 在第一种问题上容易表现得过分自信，在后三种问题上反而能给出相当中肯的答案。

3.4 选型反模式（过早抽象/过度工程/跟风新框架）

业界普遍认为以下几类是技术选型的高频陷阱：

1. 过早抽象：MVP 阶段就搭 Monorepo + 微前端 + 微服务。结果三个月后第一个用户都没有，团队却在维护 8 个子包。
2. 跟风新框架：每出一个 X.js 就重写一次。每次重写都吃掉团队 2～3 周窗口期，业务停滞。
3. 简历驱动开发（Resume-Driven Development）：选型理由是"我想学"，不是"项目需要"。
4. 零配置幻觉：以为脚手架"零配置"就不需要懂底层。事实是黑箱配置一旦出问题，调试成本远高于自己写一份。
5. AI 推荐照单全收：Claude 经常因为训练数据偏好推荐 Next.js、TailwindCSS——它们确实是好工具，但未必匹配当前业务。AI 给的推荐永远要过 TEMP-S。

为了把"反模式"变成可观测信号，本人在脚手架阶段会做一份"选型决策记录"（ADR，Architecture Decision Record），每个决策一份独立 markdown，模板如下：

# ADR-002 选用 Pinia 作为状态管理

- 日期：2026-04-26
- 状态：Accepted
- 背景：团队是 Vue 3 + TS，需要全局共享当前用户、未读消息、主题设置
- 候选：
  - Pinia（Vue 官方）
  - Zustand + Vue 适配（社区方案）
  - 自研 reactive store
- 评估（TEMP-S）：
  - Pinia: T5 E5 M5 P4 S4
  - Zustand+Vue: T2 E3 M3 P5 S4
  - 自研: T3 E1 M2 P5 S3
- 决策：Pinia
- 取舍：放弃 Zustand 的极简 API；放弃自研的灵活性
- 退出条件：当 Pinia 维护活跃度连续 6 个月低于阈值，或 Vue 官方推荐换栈时重新评估

ADR 看起来很重，但它是技术债的前哨。每写一份 ADR 大约花 20 分钟，节约的是半年后"为什么当时选这个"的考古时间。让 Claude 在每个选型对话结束时主动生成 ADR 草稿，是脚手架阶段最划算的协作姿势之一。

四、实战 Demo——TypeScript + Vue 3 + Vite

给产品经理：本节是一段"对话回放"，演示一个新项目从一句话到第一次 commit 的全过程。你不需要复现命令，只看 PM 视角的发言节奏与决策点即可。

4.1 一句话需求到第一次 commit 的完整对话流程

第 1 轮 — PM 给需求：

PM: 我们要做一个团队周报工具，员工每周五写日报，老板看汇总。
    技术栈优先 TS + Vue 3 + Vite，部署放 Vercel。
    请进入 Plan 模式，先给我搭脚手架的完整步骤。

第 2 轮 — Claude 反问澄清：

Claude: 进入 Plan 模式前我需要确认 4 件事：
  1) 是否需要服务端？日报数据存哪里——本地 LocalStorage、Supabase、还是自建后端？
  2) 老板视图与员工视图差异大吗？要不要做权限？
  3) 部署目标是 Vercel，前端纯静态还是需要 Edge Function？
  4) 团队规模与技术背景，影响是否引入 Pinia/Vue Router 等。
请逐条回答。

第 3 轮 — PM 回答：

PM: 1) Supabase  2) 老板看汇总，员工只看自己的，需要权限  
    3) 可以用 Vercel Edge Function  4) 4 人团队，都熟悉 Vue 3

第 4 轮 — Claude 出 Plan：

Claude: 已生成 ROADMAP-scaffold.md，主要阶段：
  Phase 1 - pnpm create vite + 基础依赖
  Phase 2 - 接入 vue-router + pinia + supabase-js
  Phase 3 - 配置 eslint flat + prettier + vitest
  Phase 4 - 编写 CLAUDE.md + 配置 .claude/skills
  Phase 5 - 配置 Vercel 部署预设
  Phase 6 - 首次 commit + 推送 main
请审查并回复"按计划执行"。

第 5 轮 — PM 同意：

PM: 按计划执行，但 Phase 5 暂缓，我们今天先到 Phase 4。

第 6 轮 — Claude 执行：

Claude 依次执行下面的命令（Plan 模式退出后），每一步都先打印命令、等用户确认后再跑：

# Phase 1 — 项目骨架
pnpm create vite@latest weekly-report --template vue-ts
cd weekly-report
pnpm install

# Phase 2 — 路由 / 状态 / 后端 SDK
pnpm add vue-router@4 pinia @supabase/supabase-js

# Phase 3 — 工程规范
pnpm add -D eslint@9 @typescript-eslint/eslint-plugin \
  @typescript-eslint/parser eslint-plugin-vue \
  prettier eslint-config-prettier vitest @vue/test-utils jsdom

# Phase 4 — 写入 CLAUDE.md
# (Claude 调用 Write 工具)

第 7 轮 — PM 收尾：

PM: 帮我做第一次提交，commit message 中文。
Claude: 已生成 commit「chore: 初始化周报工具脚手架（vue3 + vite + supabase）」，是否提交？
PM: 是。

整段对话花费约 12 分钟，背后跑了 50 多条命令、写了 30 多个文件。PM 只做了 7 次决策。

4.2 Claude 主动询问的好问题模板

观察上面的回放，Claude 的"反问"是高质量协作的核心。本人沉淀的好问题模板：

1. 数据 / 状态：数据存在哪里？要不要持久化？
2. 边界 / 权限：用户分几类？谁能看到什么？
3. 部署 / 运行环境：跑在浏览器、Node、Edge、Worker？
4. 团队 / 时间预算：人数？经验？deadline？
5. 演化 / 退出条件：MVP 结束后下一阶段做什么？

如果 Claude 没主动问，说明它在"猜"。这时不要回答它的方案，而是回一句"在出方案前，请用上面 5 类问题先 interview 我"。这条提示词本身可以固化到 ~/.claude/CLAUDE.md 里，全局生效。

4.3 团队规范固化为 CLAUDE.md 与 Skills

最终生成的 CLAUDE.md 关键片段：

# Weekly Report

## 项目概览
4 人团队周报工具，前端 Vue 3 + Vite，后端 Supabase + Vercel Edge。

## 关键脚本
- `pnpm dev` 本地开发，端口 5173
- `pnpm build` 生产构建
- `pnpm test` Vitest 单测
- `pnpm lint` ESLint flat + Prettier

## 目录约定
- `src/views/` 路由级页面
- `src/components/` 通用组件，超过 300 行考虑拆分
- `src/composables/` 组合式函数，文件名以 `use` 开头
- `src/stores/` Pinia store，按业务领域分文件
- `src/api/` Supabase 调用，按表分文件

## 与 Claude 协作约定
- 涉及 vite.config.ts / supabase schema 的修改必须先进 Plan 模式
- 任何新依赖必须用 npm-registry MCP 查最新稳定版
- 提交信息统一中文，前缀使用 conventional commits
- 禁止 `git push --force` 到 main

同时在 .claude/skills/ 下放：

.claude/skills/
├── new-view/SKILL.md          # 新建视图（生成 vue 文件 + 路由 + 测试样板）
├── new-store/SKILL.md         # 新建 Pinia store
├── add-supabase-table/SKILL.md # 加表 + 生成 TS 类型 + API 文件
└── release/SKILL.md           # 发版流程

这些 Skills 是团队最值钱的资产之一——它们不是"AI 提示词"，而是把团队工作流变成可执行代码。新人入职第一天 pnpm install + 启动 Claude Code，团队规范就已经在他终端里跑起来了。

为了让读者有一个具体的 Skill 文件参照，下面给出 new-view/SKILL.md 的精简实现：

---
name: new-view
description: 在 src/views 下新建路由级页面，附路由表注册与冒烟测试
trigger: 当用户说"新建一个页面/视图/路由"时启用
---

# 步骤
1. 询问用户：页面名称（PascalCase）、URL 路径、是否需要鉴权
2. 在 `src/views/<Name>.vue` 写入模板：
   ```vue
   <script setup lang="ts">
   // {{Name}} 视图：{{description}}
   </script>
   <template>
     <section class="{{kebabName}}">
       <h1>{{Name}}</h1>
     </section>
   </template>

3. 修改 src/router/index.ts，按字母顺序插入路由
4. 在 tests/views/<Name>.spec.ts 写入冒烟测试（mount + toMatchSnapshot）
5. 运行 pnpm test -- <Name> 验证通过
6. 调用 git-commit skill，提交信息中文：「feat(view): 新增 页面」

校验清单

• 路由表按 path 字典序
• 页面注释写明"做什么"
• 冒烟测试通过

这种把"团队约定 + 命令 + 测试"打包到一起的写法，是脚手架阶段最值得投资的事。它意味着无论是 Claude 还是新人，第一天就能写出"团队风格"的代码，而不是写完之后被 PR review 改个三轮。

---

## 五、风险与边界

### 5.1 Claude 在选型时的偏见（训练数据时间窗口/流行度倾向）

Claude 的"偏见"主要来自三处：

1. **训练数据截止日期**：模型对截止日期之后发布的库一无所知。问"2026 年 4 月发布的 X 怎么用"它要么承认不知道，要么编造。这就是为什么 6.2 节反复强调要接 MCP。
2. **流行度倾向**：训练语料里 React/TailwindCSS/Next.js 出现频率远高于小众方案，模型会无意识偏向它们。即使你说"用 Vue 3"，它仍会偶尔写出 JSX 风格的伪代码。
3. **英文偏见**：英文文档密度高，中文最佳实践会被低估。问"Vue + Element Plus + 中文 a11y 最佳实践"时，常需要补充本地资料。

应对手法：在 CLAUDE.md 里明确写"本项目技术栈是 Vue 3 + Vite + TypeScript，禁止建议 React 替代方案"；并在系统级 CLAUDE.md 写"假设用户偏好 TS + Vue"。

### 5.2 工程师不能让渡的决策点（架构/安全/合规）

下列决策永远必须由人做出，AI 只能提供材料：

- 架构边界（哪些是核心域、哪些可以外包给 SaaS）
- 数据所有权与隐私合规（PII 是否能上第三方 LLM、跨境数据传输）
- 鉴权方式与会话生命周期
- 数据库 schema 的主键策略与索引策略（影响多年）
- 第三方依赖的许可证审查（GPL / AGPL 在商业项目里的传染性）
- 关键依赖的供应链安全（package squatting、postinstall 脚本）

这些决策不可逆或代价巨大，让 Claude 列候选可以，但拍板必须是工程师/架构师/法务三方签字。

### 5.3 脚手架自动化的反噬（黑箱配置/升级困境）

脚手架越自动，黑箱越深。常见反噬：

- **升级困境**：CRA 当年也曾是"开箱即用"，今天没人维护。任何脚手架的核心维护者活跃度，是必须考察的指标。
- **配置漂移**：脚手架默认配置与最佳实践随版本变化，老项目越拖越偏离主流。
- **AI 加速失控**：Claude 可以一夜生成 200 个文件，工程师审不过来就 commit。半年后 bug 来了，没人记得这个文件谁写的、为什么这么写。

对策：

1. 把脚手架当作"一次性脚手架"，而不是长期依赖。生成完之后所有配置归项目所有，不再受脚手架版本约束。
2. 对 AI 大批量生成的代码使用"先 Plan 再 Apply"双阶段，并在 commit message 标注 `co-authored-by: claude`，便于追责。
3. 关键配置文件（vite.config / eslint.config / tsconfig）写注释，解释每一项"为什么这么配"。半年后回头才看得懂。

下面是本人 vite.config.ts 的"带注释版"，可以直接当作团队模板：

```ts
// vite.config.ts — 周报工具前端构建配置
// 任何一项变更必须同步更新本文件顶部 CHANGELOG，否则 PR 不予合并
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      // 统一使用 @/ 别名，禁止使用相对路径 ../../../
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  server: {
    port: 5173,        // 与团队约定一致，便于 Cypress 默认配置
    strictPort: true,  // 端口被占就直接报错而不是 silently 换端口
    open: false        // 禁止自动开浏览器，避免远程开发环境弹窗
  },
  build: {
    target: 'es2022',
    sourcemap: true,   // 生产 sourcemap，配合 Sentry 解析栈
    rollupOptions: {
      output: {
        // 简化 chunk 命名便于线上排错
        chunkFileNames: 'js/[name]-[hash].js',
        assetFileNames: 'assets/[name]-[hash][extname]'
      }
    }
  },
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./tests/setup.ts']
  }
})

这份文件里每条注释都对应一个"半年后会忘掉的决策"。例如 strictPort: true 是因为本人有过一次端口悄悄漂移导致 nginx 反代到错误端口的事故；sourcemap: true 是因为线上一个 1px 像素错位 bug 排查了两天，最后发现 sourcemap 没传 CDN。把这些教训写在配置注释里，比写在 wiki 里更不容易丢。

六、附录——常见问题与速查

给产品经理：脚手架阶段是问题最密集的时期，下面这些问答整理自本人和团队过去两年的实战。读到对应场景时回头查即可。

6.1 我已经有一个老项目，要不要重搭脚手架？

判断依据三条：

1. 当前 dev 启动是否超过 30 秒？超过就值得评估迁移到 Vite 系。
2. CI 构建是否超过 10 分钟？超过就值得引入 Turborepo / Nx 的远程缓存。
3. 团队是否每次升级依赖都"心里发虚"？如果是，先补 ADR 和测试覆盖，再谈脚手架重建。

不要为了"重新感觉良好"而重搭。脚手架重建的本质成本不在 pnpm create，而在团队几周内 PR review 的混乱。

6.2 Claude 总是推荐 Next.js / Tailwind 怎么办？

在仓库根 CLAUDE.md 顶部写：

# Stack Guardrails

- 本项目栈：Vue 3 + Vite + TypeScript + Pinia + UnoCSS
- 禁止建议：React / Next.js / TailwindCSS（除非用户明确询问）
- 推荐方案前必须先用 npm-registry MCP 验证版本号

这条 guardrails 在每次会话开始时都会注入，能拦住 80% 的"AI 偏见"型推荐。

6.3 多人协作时，CLAUDE.md 和个人 settings 怎么分？

按层级：

• 仓库根 CLAUDE.md：团队共识，进 git。
• 仓库 .claude/settings.json：团队工具配置（MCP、hooks），进 git。
• 仓库 .claude/settings.local.json：个人偏好（端口、API key），加入 .gitignore。
• 用户级 ~/.claude/CLAUDE.md：个人跨项目偏好，比如"中文回复"、"祈使语气"。

四层叠加，互不污染。本人的全局 CLAUDE.md 里只放偏好和绝对约束，把项目细节留给仓库级文件。

6.4 什么时候该把脚手架沉淀为内部模板？

经验阈值：当团队连续启动第 3 个相似项目时，把前两个项目的"共性"抽出来做成 create-<team-name>-app。低于 3 个就抽象，往往是过早抽象，每个项目的差异会迅速吃掉模板的复用价值。抽象时只保留"几乎所有项目都要的"内容（lint、tsconfig、CI、CLAUDE.md 模板），把"业务相关"的东西留给项目自己。

6.5 脚手架阶段如何评估 AI 协作的投入产出？

本人会用一份简单的"AI 协作账单"表格记录：

这张表的价值不是"证明 AI 能省多少时间"，而是定位"哪些场景 AI 价值高、哪些场景需要人工兜底"。从本人的统计看：纯模板/配置型任务 AI 节省最多，涉及外部 API 实时变化的部分 AI 反而容易拖慢节奏——这正是 MCP 要解决的问题。把账单坚持记三个月，团队会自然形成"这件事让 AI 做、那件事自己来"的肌肉记忆。

脚手架不是一次性动作，而是"项目身份证"的初次签发。这一节我们做了三件事：把脚手架的演进与现状串成时间线、把 Claude Code 在选型与初始化阶段的协作姿势固化为可执行步骤、给出一份避坑清单。完成 6.2 之后，团队应该已经拥有可跑的工程骨架、CLAUDE.md、若干 Skills，以及一份选型记录。下一节 6.3 将进入"核心功能多轮迭代"——脚手架立起来之后，怎么用 Claude 一周内推出可用 MVP、并保证迭代过程不破坏现有约定。

最后留给读者两个习题，可以在自己项目里立即落地：

1. 为当前项目写一份 ADR-001，回答"为什么用现在这套技术栈"。如果写不出三条理由，说明选型基础不牢，是时候补课。
2. 在 .claude/skills/ 下加一个 release/ skill，把"打 tag → 改 CHANGELOG → 推送"流程固化下来。下一次发版让 Claude 跑这条 skill，看节省了多少分钟。

这两个习题做完，本章的内容才真正变成你团队的肌肉记忆。脚手架不是"一次搭好就结束"的工程动作，而是会随着团队对工具与 Claude Code 协作模式的理解持续演化的"活文档"——下一次 PR review 时，回头审视一下今天的 CLAUDE.md，看看还有哪些隐性约定值得显式化，把它们一条条搬到文档里。

延伸阅读

• Vite 官方文档 — 现代前端构建工具的事实标准
• Turborepo 官方文档 — Monorepo 任务编排与远程缓存
• TypeScript Handbook — TS 官方教程，配置 tsconfig 必读
• Vue 3 官方指南 — Composition API、SFC、生态总览（中文）
• React 官方文档 — 含官方推荐脚手架与元框架建议
• pnpm 文档 — 包管理与 workspace 设计哲学
• Anthropic Claude Code 官方文档 — Claude Code 安装、Plan 模式、Skills、Hooks 全览
• Model Context Protocol 规范 — MCP 协议本身与生态服务器列表
• context7 项目主页 — 实时文档 MCP 服务，缓解 LLM 训练数据过时问题
• The Twelve-Factor App — 现代应用架构经典原则，选型时的"对照基线"
• Awesome Claude Code — 社区维护的 Claude Code 资源集
• State of JS 2024 — 前端生态年度调查，选型参考数据来源之一