可复现开发环境：让新成员半小时跑起项目

把隐含前提变成仓库文件

README 里写“安装一个较新的 Node”不具备可复现性。仓库应声明运行时、包管理器和系统依赖版本，并提供一个统一启动入口。版本文件既服务本地工具，也应被 CI 读取。

.tool-versions       # nodejs 22.14.0, pnpm 10.6.1
.env.example         # 变量名、用途和安全默认值
compose.yaml         # PostgreSQL、Redis 等依赖服务
Makefile             # setup、dev、test、reset 统一入口

初始化脚本必须幂等

setup 连续执行两次不应破坏已有数据或重复插入配置。脚本先检查工具版本，再安装锁定依赖、启动服务、执行迁移并输出下一步。失败时给出具体检查项，不要只返回一串子命令日志。

检查必要命令和版本；从示例文件创建本地配置；启动带健康检查的依赖服务；执行数据库迁移和最小种子数据；运行一次冒烟测试。

定期从零验证

现有成员的电脑会积累全局工具和缓存，无法代表新人体验。在 CI 中创建干净容器，严格按照 README 执行安装、启动和测试。把完成时间作为开发体验指标，持续清理过时步骤。

重置命令只操作明确命名的本地容器和卷，执行前展示目标。不要使用宽泛路径或未解析变量做递归删除。