---
name: walking-skeleton
description: 搭建贯穿前端到数据库的端到端最小可运行系统雏形，作为后续正式开发的基座；区别于分支不合并进主干的 prototype。
disable-model-invocation: true
---

# 端到端可运行骨架

搭建贯穿系统从最外层入口（UI、CLI 或 API）到最深层持久化（数据库或外部存储）的最小可运行系统雏形（Walking Skeleton）。

## 与原型的核心区别

- **端到端可运行骨架（Walking Skeleton）**：是正式工程产物，目的是验证脚手架、工具链、依赖注入与各分层能否在真实环境中协同工作。**验证完毕后保留在代码库主干中，并在其上持续演进和增加特性**。
- **一次性原型（见 `prototype` skill）**：是为了探究某个具体逻辑或界面方向而编写的代码，验证完毕后将其作为一手资料保留在独立分支上，不合并进主干代码。
- **端到端最小闭环任务（tracer bullet）**：是后续特性开发阶段的任务颗粒度拆分方式；Walking Skeleton 仅在项目起步阶段执行一次，是项目颗粒度的基座。

## 搭建流程

整个流程严格围绕“极窄切片、穿透全层、真实连接”展开。

### 1. 选定单一垂直切片（Vertical Slice）

选定一条最简业务链路，要求：

- **穿透全部层级**：从外部请求触发，经过路由解包、业务调度，最终写入或读取持久化层并返回结果。
- **剥离非核心复杂度**：绝对不在此阶段实现用户认证鉴权、风控、第三方复杂集成或富交互逻辑。例如：“健康检查路由查询数据库当前时间并返回”或“提交一条极简文本并存入数据库查询回显”。
- **单条主路径**：不处理分支逻辑或复杂错误重试，只确保正常路径能走通。

### 2. 真实装配与链路打通

杜绝骨架阶段的“全 Mock”假象，验证真实的工程接缝：

- **配置与依赖注入**：完成环境变量加载、数据库连接池初始化及服务依赖组装。
- **入口与通信**：实现真实的 HTTP 路由、CLI 命令或消息订阅入口，完成请求解包。
- **持久化触达**：执行真实的数据库迁移或表结构初始化（参考 `data-modeling`），通过数据访问层发起真实 I/O 查询。
- **响应序列化**：按照约定的错误与成功格式（参考 `api-contract`）将数据回传给调用端。

### 3. 建立自动化冒烟反馈

为骨架配置最小自动化测试，证明各层真正连通：

- 编写一个端到端（E2E）或集成冒烟测试，真实启动服务或测试容器，发送一条真实请求并断言持久化结果。
- 将冒烟测试集成进项目统一检查命令，确保任何人在全新环境中执行一条命令即可验证链路健康。

### 4. 纳入主干与后续衔接

- 链路打通且测试变绿后，作为正式代码提交并合并进主干分支。
- 骨架搭建完成标志着项目起步阶段结束，后续功能开发进入核心主干：
  - 需求方案澄清：运行 `/grill-with-docs`；
  - 规格与任务拆解：运行 `/to-spec` 与 `/to-tickets`。