Compound

---
name: compound
description: |
  Compound Learning Loop. 跨 sprint 积累的经验沉淀到 compound/, 按 doc_type 分文件存档.
  4 种 doc_type: learning / trick / decision / explore.
  铁律[复利]: 一事一档, ≤100 行.
---

# /compound — 复利知识沉淀 (v9.7.0)

## 哲学 (借 CodeStable)

> 软件复杂度膨胀撑破上下文、隐知识丢失、需求漂移. compound/ 是复利工程的物理实现.
> "下一次 cs-arch / cs-feat-design / cs-issue-analyze 会回头读 compound/, 让经验在新工作里被复用".

## 四类 doc_type

| doc_type | 用途 | 触发时机 | 模板 |
|---|---|---|---|
| **learning** | 踩坑 → 教训 | polish 完成 / review P0 finding / 用户主动 `/compound add learning` | `templates/learning.md` |
| **trick** | 可复用模式 | impl 发现优雅写法 / 用户主动 `/compound add trick` | `templates/trick.md` |
| **decision** | 拍板技术选型 (类 ADR) | design 重大决策 / 用户主动 `/compound add decision` | `templates/decision.md` |
| **explore** | 代码调研结论 | docs_researcher 完成 / 用户主动 `/compound add explore` | `templates/explore.md` |

## 文件命名 (铁律[复利])

```
compound/YYYY-MM-DD-{doc_type}-{slug}.md
```

例:
- `compound/2026-05-25-decision-jwt-rs256-vs-hs256.md`
- `compound/2026-05-25-learning-useeffect-deps-infinite-loop.md`
- `compound/2026-05-26-trick-redis-pipeline-batch-fetch.md`
- `compound/2026-05-26-explore-react-19-concurrent-rendering.md`

## 约束 (铁律[复利])

- ✅ 每个 compound 文件 **≤ 100 行** (超出 → 拆分成多个 slug)
- ❌ 不允许"压缩 pass" (一事一档, 不合并)
- ✅ `decision` 改状态用 `superseded-by: {slug}` 引用, 不直接删
- ✅ doc_type 必 4 选 1, 不允许混合
- ✅ slug 必须 kebab-case, 不允许空格 / 下划线 / 中文
- ✅ frontmatter 必填 (date, sprint, status)
- ✅ index-updater hook 按 doc_type 自动分类计数

## 写入时机 (强制)

| 时机 | doc_type | 写入责任 |
|---|---|---|
| polish 完成 (cleanup-pass.md 写完) | learning | polish_worker / 主 agent |
| 最新 review passN 发现 P0 finding | learning | reviewer subagent |
| design.md 含重大决策 (e.g. "我们决定 X 不用 Y") | decision | 主 agent / architect |
| impl 时发现优雅 pattern | trick | generator / 主 agent |
| docs_researcher 调研完成 | explore | docs_researcher |
| 用户显式 `/compound add {type}` | 任意 | 主 agent |

## 读取时机 (强制)

| 时机 | 读什么 | 责任 |
|---|---|---|
| plan stage 开始 | `_index.pointers.latest_decisions` 列出的 5 个 `decision-*.md` | 主 agent (强制) |
| design stage | grep 关键词读相关 `learning-*.md` + `trick-*.md` | 主 agent / architect |
| review stage (critic) | 历史 decision 冲突检查 + 历史 learning 重复踩坑检查 | critic subagent |
| brainstorm stage | **不读 compound** (创意空间不污染) | (跳过) |

## 命令

| 命令 | 作用 |
|---|---|
| `/compound add learning {slug}` | 触发 learning 模板, 主 agent 填空 |
| `/compound add trick {slug}` | 触发 trick 模板 |
| `/compound add decision {slug}` | 触发 decision 模板 |
| `/compound add explore {slug}` | 触发 explore 模板 |
| `/compound list [type]` | 列出 compound 文件 (按 type 筛) |
| `/compound search {keyword}` | grep 全 compound 搜关键词 |

## archive 机制 (借 OpenSpec /opsx:archive)

跨季度时自动归档:
- 触发: 新 quarter 第一 sprint 启动时, athena-dev 检测
- 动作: 上 quarter 的 `compound/*.md` 移到 `.ai_state/archive-{quarter}/compound/`
- 主 `compound/` 只保留近 1 quarter + 所有 `decision-*.md` (永远保留 decision)

## 模板

见 `~/.claude/skills/compound/templates/{learning,trick,decision,explore}.md`

## 与单文件 lessons.md 的对比 (v9.6.2 → v9.6.4 演进)

```
v9.6.2 (lessons.md 单文件):                v9.6.4+ (compound/ 颗粒化):
  - 追加一段                                  - 新建一个文件
  - grep 全文找                               - grep 文件名 + 内容
  - 3 个月后 500 行混合                       - 一事一档, ≤100 行
  - 跨 sprint 全部读                          - latest_decisions 仅近 5 个
```

## v9.6.2 → v9.6.4 迁移

`athena-migrate` 处理 lessons.md, 用户三选:
1. 整体保留 → 转成单个 `compound/{today}-learning-legacy-migration.md`
2. 手工拆分 → 主 agent 引导逐段分类
3. 全部丢弃 → 删除 lessons.md, compound/ 从空开始

详: `~/.claude/skills/athena-migrate/SKILL.md`