---
id: <feature-id>                # kebab-case，与文件名一致
status: planned                 # planned | in-progress | done | deprecated
owner: <crates/path>/           # 责任 crate 或模块
since: 2026-Q2                  # 何时开始
tags: []                        # 可选，frontmatter tag
---

# Feature: <一句话功能名>

## What（一句话）

<elevator pitch，<= 30 字>

## Why（动机）

- <业务 / 工程驱动力，1-3 条>
- <链 ADR-NNNN 解释决策依据>

## User-facing behavior（用户视角）

> <用户在 CLI / IDE / API 上做什么、看到什么具体输出>

**注意**：必须是用户能观察到的具体输出，拒绝"测试通过 / API 返回 200"这类开发者视角描述。

## Acceptance criteria（机械可验证）

每条都必须链向真实 test 文件：

- [ ] <criterion 1>
  → tests/integration/<test-file>.rs#<test-name>
- [ ] <criterion 2>
  → tests/e2e/<test-file>.rs#<test-name>
- [ ] <criterion 3>
  → crates/<name>/src/<module>.rs#<test-name>

## Non-goals（明确不做）

- <出于 ADR / scope 限制不做的事，链 ADR 解释>
- <避免 future scope creep>

## Constraints（必须遵守）

- <性能 / 安全 / 兼容性硬约束>
- <配置 / 部署限制>

## Related decisions

- ADR-NNNN: <标题>
- ADR-MMMM: <标题>

## Related modules

- 主实现：`crates/<name>/`
- CLI 入口：`crates/koala-cli/src/commands/<name>.rs`
- 配置：`koala.toml [<section>]`

## Open questions

- <未决的小问题，链 issue 跟进>

---

## 写作铁律（提交前自检）

- [ ] Acceptance 每条链向真实 test 路径，drift detector 能验证
- [ ] User-facing behavior 是用户视角，不是开发者视角
- [ ] 不写实现细节（函数名 / 调用步骤 / 算法）—— 让代码自己说
- [ ] 不写运维步骤（挪到 [runbook.md](../runbook.md)）
- [ ] 不写 API 列表（让 cargo doc 自动生成）
- [ ] 不论证为什么这么设计（挪到 ADR）
- [ ] 文件 < 600 行；超过先挤冗余，仍超才考虑拆子目录

详见 [framework-redesign.md §3.4 Feature 文件模板与写作铁律](https://github.com/koala-agent/koala/blob/main/wiki/specs/framework-redesign.md)（托管在 koala-agent/koala 仓库）。
