# 文档规则

读者对象：新增功能、模块或配置的人。

## 三类文档

| 文档 | 用途 |
| --- | --- |
| `README.md` | 用户入口、快速开始、核心能力总览 |
| `AGENTS.md` | Agent 协作规则、目录边界、测试策略 |
| `docs/` | 人类可浏览的内部说明文档 |

## 什么时候必须同步

新增或移除以下内容时，要同步文档：

- 顶层目录或重要模块。
- npm script 或 legacy 脚本。
- CLI 子命令或启动参数。
- Slash 命令。
- Hook 事件。
- 环境变量。
- 测试套件或专项跑法。
- 用户可见行为。

## 写法

- 先写读者需要知道什么，再写路径。
- 短页面优先，别把 README 原样复制进来。
- 命令用 fenced code block。
- 路径和变量用反引号。
- 不写密钥、token、本地私人路径和 `.env` 内容。
