开发环境新人引导工作流

目标

新入职者就是一台干净机器，会把环境的每个隐式假设都踩一遍。把全程脚本化、以冒烟任务收尾、让每次新人失败都回流进脚本——引导从受难的仪式变成环境的诊断仪。每周在 CI 干净机器上重跑引导，漂移由机器先撞上而不是新人。

步骤要点

1. 全程脚本化：把所有手工步骤——版本、依赖、密钥脚手架、种子数据——编码进一条引导脚本，不留口传环节。
2. 用冒烟项目验证：引导以规范冒烟任务收尾——构建、测试、运行并访问本地端点，证明整条工具链。
3. 给引导路径打点：计时每个阶段并捕获失败，让脚本的薄弱环节可见而非仅存于传闻。
4. 每次新失败都修脚本：新人撞到未脚本化步骤或坏阶段时，修复在下一次引导前落进脚本而不是留在聊天记录里。
5. CI 每周跑引导：在干净 CI 机器上执行引导，先于任何人发现漂移（下载地址变了、新增了必需步骤）。

排错提示

脚本退出码零不代表环境可用，冒烟任务通过才是完成定义；新人又卡在同一步说明上次修复没进脚本，失败必须回流到脚本本体；下载链接失效只有新人会撞上，每周 CI 干净机重跑让机器替人踩坑。

适用边界

引导脚本覆盖通用路径，个别操作系统或硬件差异仍需少量人工分支；密钥脚手架只能给假值，真实凭据走独立授权流程。

代码示例

bootstrap.sh phases (timed):
  1 toolchain (node 22.11, pnpm 9)      3.1 min
  2 deps (pnpm install)                  2.4 min
  3 env scaffolding (.env from vault)    0.4 min
  4 seed db (docker compose + seeds)     1.8 min
  5 SMOKE: build + test + hit /health    1.2 min
  ------------------------------------------
  total: 8.9 min  (was: 2-4 days of asking)

CI weekly clean-machine run:
  2026-10-14 PASS  8.6 min
  2026-10-21 FAIL phase 3: vault policy
    changed  -> fixed before any human hit it