# 跨层思维指南

> **目的**：在实现之前思考跨层的数据流。

---

## 问题

**大多数 bug 发生在层边界，而不是层内部。**

常见的跨层 bug：
- API 返回格式 A，前端期望格式 B
- 数据库存储 X，service 转换为 Y，但丢失了数据
- 多个层以不同方式实现相同的逻辑

---

## 在实现跨层功能之前

### 步骤 1：映射数据流

画出数据如何移动：

```
Source → Transform → Store → Retrieve → Transform → Display
```

对于每个箭头，问：
- 数据是什么格式？
- 可能出什么错？
- 谁负责验证？

### 步骤 2：识别边界

| 边界 | 常见问题 |
|----------|---------------|
| API ↔ Service | 类型不匹配、字段缺失 |
| Service ↔ Database | 格式转换、null 处理 |
| Backend ↔ Frontend | 序列化、日期格式 |
| Component ↔ Component | Props 形状变化 |

### 步骤 3：定义契约

对于每个边界：
- 确切的输入格式是什么？
- 确切的输出格式是什么？
- 可能发生什么错误？

---

## 常见的跨层错误

### 错误 1：隐式格式假设

**Bad**：未检查就假设日期格式

**Good**：在边界处显式格式转换

### 错误 2：分散的验证

**Bad**：在多个层验证相同的东西

**Good**：在入口点验证一次

### 错误 3：泄露的抽象

**Bad**：组件知道数据库 schema

**Good**：每层只知道它的邻居

---

## 跨层功能清单

实现前：
- [ ] 映射了完整的数据流
- [ ] 识别了所有层边界
- [ ] 定义了每个边界的格式
- [ ] 决定了验证发生在哪里

实现后：
- [ ] 测试了边界情况（null、empty、invalid）
- [ ] 验证了每个边界的错误处理
- [ ] 检查了数据是否存活往返

---

## 跨平台模板一致性

在 Constella 中，命令模板（例如 `record-session.md`）存在于**多个平台**，内容相同或几乎相同。这是一个跨层边界。

### 修改任何命令模板后的清单

- [ ] 找到所有具有相同命令的平台：`find src/templates/*/commands/constella/ -name "<command>.*"`
- [ ] 更新所有平台副本（Markdown `.md` 和 TOML `.toml`）
- [ ] 对于 Gemini TOML：适应行连续符（`\\` vs `\`）和三引号字符串
- [ ] 运行 `/constella:check-cross-layer` 验证没有遗漏

**现实例子**：在 Claude 中更新 `record-session.md` 使用 `--mode record`，但忘记了 iFlow、Kilo、OpenCode 和 Gemini — 被跨层检查发现。

---

## 生成运行时模板升级一致性

一些生成的文件既是文档又是运行时输入。在 Constella 中，
`.constella/workflow.md` 被 `get_context.py`、`workflow_phase.py`、
SessionStart 过滤器和每轮 hooks 解析。模板更改必须针对
全新的 init 和升级路径进行验证。

### 修改运行时解析模板后的清单

- [ ] 识别每个读取模板的运行时解析器，而不仅仅是安装它的文件写入器
- [ ] 检查相关语法是否生活在明显的管理区域之外，例如 tag 块
- [ ] 验证全新的 `init` 输出和有旧 `.constella/.version` 的版本化 `update` 场景
- [ ] 使用旧的原始模板fixture添加升级回归测试，然后断言安装的文件达到当前打包的形状
- [ ] 更新拥有运行时契约的后端 spec

**现实例子**：Codex inline 模式将 workflow 平台标记从
`[Codex]` / `[Kilo, Antigravity, Windsurf]` 更改为 `[codex-sub-agent]` /
`[codex-inline, Kilo, Antigravity, Windsurf]`。全新 init 是正确的，但
`constella update` 只合并了 `[workflow-state:*]` 块，并在那些块之外保留了陈旧的
标记。结果：升级的项目得到了新的 hook 脚本，但旧的 workflow 路由，所以
`get_context.py --mode phase --platform codex` 可能返回空的 Phase 2.1 detail。

---

## 何时创建流程文档

在以下情况下创建详细流程文档：
- 功能涉及 3+ 层
- 多个团队参与
- 数据格式复杂
- 功能以前导致过 bug
