---
name: skeleton-gen
description: A2 骨架生成——基于 docs/04 § 零 技术栈 + docs/01-需求清单/index.md 模块索引，生成项目专属的架构文档（docs/04 § 一+）和工具脚本（.mjs，跨平台）。固定工具文件用 Read/Write 落盘，架构文档由 LLM 按大纲生成。
user-invocable: false
allowed-tools: Read Write Edit Skill Grep Glob AskUserQuestion
---

**所有输出必须使用中文。**

## 执行步骤

### A. 读取锁定的输入

用 `Read` 读取：
- `docs/04-技术规范.md` § 零 技术栈表
- `docs/01-需求清单/index.md` 需求索引
- `docs/01-需求清单/` 需求卡片

后续所有内容都基于它们推导。

### B. 追加 docs/04 § 一+（架构文档；保留 § 零 不覆盖）

docs/04 已由 scope-lock 写入 § 零。本步骤追加 § 一 ~ 三：

1. 读取 `docs/04-技术规范.md`（现有 § 零 完整内容）。
2. 读取 `${CLAUDE_SKILL_DIR}/templates/docs-04-skeleton-template.md`。
3. 基于技术栈，按大纲生成 § 一 ~ 三 的项目专属内容，剥掉 HTML 注释。**§ 1.2 分层结构 / § 2.1 目录约定要写清后端/前端的实际目录布局**（原 docs/09 内容并入此处，供 Coding 阶段落盘 + 跨模块判定参照）。
4. 拼接原有内容和新生成内容，写回 `docs/04-技术规范.md`。

> **A2 不再单独出 docs/06 / 07 / 09**——它们的内容各有归属：
> - 环境 / 配置值（含凭据） → `config-vars.yaml`（A1 产出）；构建 / 测试命令 → docs/04 § 零。
> - 项目目录布局 → docs/04 § 1.2 分层结构 / § 2.1 目录约定；跨模块「路径→模块」→ docs/08 § 二 模块行 `路径:`。
> - 前端 UI / 交互 / 布局 → 项目根 `prototype/`（完整 demo，权威）；Design Tokens → `src/styles/tokens.css`（**色值冲突时 tokens.css 优先于 prototype**）；前端编码规范 → docs/04 § 二。

完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
- `  - [ ] 架构文档已生成（docs/04 § 一+）`

### C. 生成工具脚本

#### C.1 复制固定模板文件（用 Read + Write，跨平台无 shell）

对下表每个文件：用 `Read` 读模板内容，用 `Write` **原样**写到目标路径（`Write` 会自动创建缺失的父目录，无需 `mkdir`）。

| 模板 | 目标路径 |
|---|---|
| `${CLAUDE_SKILL_DIR}/templates/scripts-setup-test-db-template.mjs` | `scripts/setup-test-db.mjs` |
| `${CLAUDE_SKILL_DIR}/templates/styles-tokens-template.css` | `src/styles/tokens.css` |

> `sql/migrations/` 目录不在此预建：A4 `db-init` 写 `V1__initial_schema.sql` 时 `Write` 会自动创建。

> 凭据 / 配置不在此生成：项目**全部配置**（含 DB 凭据 / 密钥）已由 A1 `scope-lock` 写入仓库根 `config-vars.yaml`；`scripts/setup-test-db.mjs` 运行时按 2 层 map 直接读它。

#### C.2 渲染 scripts/test.mjs

用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/scripts-test-template.mjs`，基于步骤 A 的技术栈（docs/04 § 零）为 7 个占位推断命令后用 `Write` 写到 `scripts/test.mjs`：

- `{{backend_build}}` / `{{backend_lint}}` / `{{backend_test}}` 后端各 stage 命令
- `{{frontend_build}}` / `{{frontend_lint}}` / `{{frontend_test}}` 前端各 stage 命令
- `{{e2e_cmd}}` E2E（无 E2E 工具则填 `echo "[test.mjs] e2e 略"`）

> 占位是普通 shell 命令字符串，模板在运行期用 `spawnSync(cmd, { shell:true })` 跨平台执行，缺席 stack 由模板内的 `existsSync('backend')` / `existsSync('frontend')` 守卫跳过。

完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
- `  - [ ] 工具脚本已生成（scripts/*.mjs）`
- `  - [ ] 样式 token 骨架已生成（src/styles/tokens.css）`

### D. 追加 .gitignore 忽略项

用 `Read` 读 `${CLAUDE_SKILL_DIR}/templates/gitignore-append-template`，并入项目根 `.gitignore`（与 C.1 同款 Read+Write，跨平台无 shell）：

- `.gitignore` **不存在** → 用 `Write` 原样写入模板内容。
- **已存在** → `Read` 现有 `.gitignore`，把模板里**尚未出现**的规则行用 `Edit` 追加到末尾（已有的跳过；重复 ignore pattern 本身无害，判重只为整洁）。

完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
- `  - [ ] .gitignore 已配置`

### E. 占位符补填 + QA 闸门

#### E.1 扫描 + 分组

用 `Grep` 在以下路径扫 `【人工填写：`，记录命中（文件 / 行号 / 说明）：
- `docs/04-技术规范.md`
- `config-vars.yaml`（A1 留下的未填字段）
- `scripts/*.mjs` / `.gitignore`

分两组：
- **敏感组**：`config-vars.yaml` 中敏感字段命中（`database.password` / `admin_init.password` / `secrets.*` 等凭据 / 密钥）。**不弹 QA**（凭据不进会话），E.3 提示用户自填。
- **非敏感组**：其余命中（含 config-vars.yaml 的非敏感字段）。按说明文字聚合为「根占位」（相同说明 = 同一值，多处共用）或「派生占位」（说明表达派生关系，如"后端 java 根包路径"派生自"根包名"）。

无命中 → 跳 E.4。

#### E.2 问根占位 + 推派生 + 批量 Edit

- 每个根占位用 `AskUserQuestion` 问（给合理默认值 + 自由输入），用 `Edit` 批量替换所有命中位置
- 派生占位**不问**，CC 基于根占位值推断后 `Edit`；不能可靠推断则回退当独立根占位问

#### E.3 敏感占位提示（不弹 QA）

若敏感组非空：打印提示横幅，列出 `config-vars.yaml` 待填的敏感字段名 + 告诉用户"直接编辑 config-vars.yaml 填真实值，凭据不进会话"。

#### E.4 验证 + QA 闸门

循环直到两条件**同时**满足：
(a) `Grep` 重新扫 E.1 全部路径，0 命中
(b) 用户 `AskUserQuestion` 选「继续」

每次弹 QA 前重扫；有残留则打印残留位置清单（文件:行号 — 说明）+ 再弹 QA。

QA 横幅涵盖：产出文件清单（docs/04 / 07 + scripts/*.mjs + .gitignore；config-vars.yaml 由 A1 产出，此处仅扫其待填项）、占位状态（N=0 或待填清单）、「继续」/「有疑问先沟通」两选项。

通过后（N=0 且用户选「继续」），用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
- `- [ ] A2 骨架生成 — skeleton-gen`

### F. 进入 A3

输出 `skeleton-gen: 完成`，立即调用 `Skill(db-design-gen)`。

## 参考

- `docs/04-技术规范.md` § 零
- `docs/01-需求清单/index.md`
- `${CLAUDE_SKILL_DIR}/templates/docs-04-skeleton-template.md`
- `${CLAUDE_SKILL_DIR}/templates/scripts-test-template.mjs`
- `${CLAUDE_SKILL_DIR}/templates/scripts-setup-test-db-template.mjs`
- `config-vars.yaml`（A1 产出，含 DB 凭据；setup-test-db.mjs 运行时读取）
- `${CLAUDE_SKILL_DIR}/templates/gitignore-append-template`
- `${CLAUDE_SKILL_DIR}/templates/styles-tokens-template.css`