# 文档标准

本文定义 whale-girl 的文档写作规则：**散文只写契约，不写转录**。根 AGENTS.md 是常驻层（每个 session 必读）；本文件管文档与注释的写法。

## 分层：一个事实一个家

| 层 | 职责 |
|---|---|
| 根 `AGENTS.md` | 常驻规则（定位、命令、约定、按改动面选检查） |
| 根 `README.md` | 产品入口：是什么、安装启用、支持的动作/触发事件、状态动画预览 |
| `decisions/` | 决策记录（生命周期 + 备选方案），契约见 [decisions/README.md](../decisions/README.md) |
| 代码注释 | 契约与非显然定位信息，跟随源码 |

## 写作规则

- 写当前态，不写变更史：避免"之前/现在/不再"、PR 与提交号；变更故事留在 commit 与决策记录。
- 中文为默认语言，术语首次出现给英文原名。
- 保持完整命题：行为、条件、模态（必须/不得）、否定保证、例外、后果——删形容词与重复，不删事实。
- 文档间引用用相对路径链接（门禁校验可达性），不手抄他文事实。

## Slop 清单（写作自查）

- ❌ 叙述式历史、实现过程叙述、测试走查、评审史、被否决的局部方案、代码复述
- ❌ 手写目录、强调通胀、段落墙
- ❌ 已实施决策记录里的规划语气（"应该""待迁移"）
- ✅ 契约、非显然失败模式、安全边界、维护陷阱

## 验证

```sh
node scripts/gates/run.mjs   # 链接可达性 + 决策格式（本地门禁组）
```