# 工作准则

> 引导卡。完整设计：[`framework-redesign.md`](https://github.com/koala-agent/koala/blob/main/wiki/specs/framework-redesign.md)（必要时查阅）。
> Wiki 入口：[`wiki/README.md`](wiki/README.md)。
>
> 注：framework-redesign.md 是 koala 框架的设计文档，托管在 koala-agent/koala 仓库；新项目可参考但不必复制。

## 这是什么

<一句话项目定位。例如："让 X 用户能 Y，从而 Z"。本段保留 1-2 句即可。>

## 新 session 5 步引导

1. 读本文件（30 秒）
2. `cat wiki/vision.md`               2 分钟，知道目标
3. `cat wiki/architecture.md`         5 分钟，知道结构
4. `koala-core status`                30 秒，看当前状态
5. 看 GitHub Issue / 用户消息 → 按任务类型读补充文档（见下方映射）

## 13 条铁律（违反 = CI 红线）

### 架构

1. 改代码前先确定它属于哪个模块；不知道归属 → 先讨论再写
2. 单一职责：模块/函数命名能不能一句话说完？说不完 → 拆
3. 依赖单向：core 不依赖 shells，fn 不依赖 io
4. 公开 API 改动 = 架构改动，需 ADR

### 流程（按变更体量自适应）

5. 小改（< 20 行 / 不跨模块）：直接 PR + smoke test
6. 中改（< 200 行）：PR 同步更新对应 `wiki/features/X.md`
7. 大改：先写 ADR + 改 `architecture.md`，人审通过再写代码
8. 任何改动都要测：能 reproduce 才算 fix，能验收才算 done

### 长期

9. ADR 永不删，只标 superseded
10. 每季度 pruning sprint 必跑（删死代码 / 合并相似抽象 / 修红线）

### 反 LLM 自欺

11. Reviewer 必须落 `.review/round-N/*.md` artifact，"我审过了"不算数
12. 测试必须真跑，看输出对不对，不靠 LLM 复述
13. `git push` 之后必看 `gh run list` 一眼——本地绿 ≠ CI 绿（macOS↔Linux 二进制差异、locale、缓存、外部服务都会咬人）

## 任务类型 → 必读

| 任务 | 必读 |
|---|---|
| Bug fix | 相关 `wiki/features/X.md` + grep `wiki/decisions/` |
| 新功能 | `wiki/roadmap.md` + GitHub Milestone + 相关 `features/X.md` |
| 架构改动 | 相关 ADR + `wiki/architecture.md`，然后写新 ADR |
| Pruning | `wiki/tech-debt.md` + `koala-core pruning start <sprint>` |
| Hotfix / 安全 | `wiki/runbook.md` 故障排除 + 相关 ADR |
| 写文档 | `wiki/features/_template.md` + 要改的文件 |

## 高频命令

```bash
koala-core status                       项目状态摘要
koala-core check --profile strict       全套 CI gate（本地复现）
koala-core drift [--explain]            wiki ↔ code 一致性 + 修复提示
koala-core adr list / validate          决策历史 + 引用图校验
koala-core health show                  健康指标快照
koala-core wiki gen                     重写 Tier 1 _index/_tags
koala-core workflow size                判 PR 体量四档
koala-core invariant list / explain <id>   16 条契约规则
gh pr view <N>                          PR 详情
gh run list --limit 3                   最近 CI 状态（push 后必看）
git log --oneline -20                   最近变更
```

> **引导期豁免**：如果项目处于 bootstrap 早期阶段（koala-core 工具尚未安装 / 实现），
> 部分命令可能不可用——用语言原生工具兜底（Rust: `cargo test/clippy/fmt/audit`；
> Node: `npm test / lint`；Python: `pytest / ruff` 等）。具体豁免范围见宿主项目的
> 根 `CLAUDE.md` 引导期段。

## 不要做的事

- 编辑 `wiki/health.md` / `_index.md` / `_tags/*`（CI 自动写，手编 = PR 拒）
- 绕过 ADR 改架构（即使是"小改动"也不行）
- 在 `feature.md` 写实现细节（让代码自己说，wiki 写代码自证不了的）
- 直接读写 `wiki/decisions/` 下被 superseded 的 ADR（用 `koala-core adr list` 看 supersede 链）
- 在 wiki 里写开发者视角的 behavior（"调用 fn 返回 X"），改成用户视角
- 写超过 100 行的本文件——本身就是 dogfood

## 完整工作流

详见 [`framework-redesign.md`](https://github.com/koala-agent/koala/blob/main/wiki/specs/framework-redesign.md)：

- §3.6 体量自适应流程（小/中/大/架构 4 档）
- §4 工作单元存放位置（vision/roadmap/epic/story/PR/bug/...）
- §6 完整工作流图

## 卡住时

1. 读 `wiki/runbook.md` 故障排除段
2. `koala-core status && koala-core check --profile light` 看本地 baseline
3. grep 相关 ADR：`grep -r "<keyword>" wiki/decisions/`
4. 提交 issue 到项目仓库

---

> 此文件由 `koala-core init` 创建。删除 `<...>` 包裹的指引文字后开始填写。
> 写作约束：本文件 ≤ 100 行是刻意的——dogfood「Convention thin, judgment thick」原则。
