代码与规格收敛

---
name: code-and-spec-alignment
description: 变更结束时的"收口"技能：核对代码与文档是否一致，把过程产物归档，把新知识回写到 context 与 memory。产出 `变更/<id>/收敛记录.md`。
---

# 代码与规格收敛

## 何时使用

- 变更已发布（或已合入主干）且观察正常。
- 需要把 `变更/进行中/` 的目录移到 `变更/已完成/`。
- 需要更新 `.agents/context/`、`.agents/memory/`、`模块与契约/` 使其匹配现实。

> 一句话：**让文档追上代码，让经验留得下来。**

## 前置

- 有 `验证记录.md`（通过）与发布记录（如已上线）。
- 有本次变更的全部产物。

## 输入

- `变更/<id>/` 全部文件
- 实际代码 diff
- 相关 `.agents/context/`、`模块与契约/`、`.agents/rules/`

## 步骤

1. **核对代码 ↔ 文档一致性**（逐项打勾）：
   - API / 事件 / Schema 是否与 `模块与契约/` 一致；
   - 模块职责是否与 `.agents/context/模块边界.md`、`代码地图.md` 一致；
   - 环境变量 / 配置 / 依赖是否与 `.agents/context/技术栈与本地环境.md`、`外部依赖与集成.md` 一致；
   - 错误码是否与 `模块与契约/后端/错误码与异常约定.md` 一致。
   发现不一致 → **以代码为准**修正文档，并把"文档为何漂移"记一笔。
2. **更新 context**：把真实结构变化写进对应条目（这是本技能的核心动作）。
3. **沉淀 memory**：
   - 重要技术取舍 → ADR 或 `.agents/memory/工程决策.md`；
   - 踩过的坑 / 反直觉的点 → `.agents/memory/经验与陷阱.md`；
   - 新的排查思路 → `.agents/memory/常见排查路径.md`；
   - 遗留未解决 → `.agents/memory/未解决技术问题.md`。
4. **记录技术债**：本次为赶进度做的妥协 → `架构决策/技术债务.md`。
5. **写收敛记录**：本次变更"实际交付了什么 vs 计划交付什么"、偏差原因、遗留项、后续变更建议。
6. **归档**：把 `变更/<id>/` 移入 `变更/已完成/`；若规则 / 规范被替代，把旧版移入 `历史归档/已替代规范/`。
7. **提出流程改进**：若本次暴露出流程 / 规则缺陷，提出对 `.agents/rules/` 或 `.agents/skills/` 的修订建议（**提出，不强改**）。

## 输出

- `变更/<id>/收敛记录.md`（模板：`.agents/templates/变更/收敛记录.md`）
- 更新后的 `.agents/context/*`、`.agents/memory/*`
- 更新后的 `模块与契约/*`
- 更新后的 `架构决策/技术债务.md`
- 目录移动：`变更/进行中/<id>/` → `变更/已完成/<id>/`

## 检查清单

- [ ] 代码与 `模块与契约/` 已逐项核对一致。
- [ ] `.agents/context/` 已更新到与代码一致。
- [ ] `.agents/memory/` 中至少写入一条本次经验（如确有可复用价值）。
- [ ] 技术债已登记（如有）。
- [ ] 收敛记录写明了"计划 vs 实际"的偏差。
- [ ] 变更目录已移动到 `变更/已完成/`。
- [ ] 遗留项已明确归属（转新变更 / 记技术债 / 记未解决问题）。

## 边界与禁止

- **禁止**把"文档更新"留到"以后再说"——收敛就是这个"以后"。
- **禁止**只改文档掩盖代码问题（应为代码修 bug 或记技术债）。
- **禁止**擅自删除历史产物；旧内容进 `历史归档/`。
- 收敛发现严重不一致（如生产配置与文档完全不同）时，**先报告用户**再动手改文档。