# 代码目录 AGENTS.md 内容规范（SSOT）

> **适用范围**：仓库内**代码目录**的 `AGENTS.md`——如 `vkk_client_flutter/lib/pages/*/AGENTS.md`、`rust_server/`、`quasar/` 子目录等。**不含** `knowledge/` 文件结构（那由 [`knowledge/AGENTS.md`](../../../../knowledge/AGENTS.md) 管）。

## 定位

对齐 [agents.md 开放标准](https://agents.md/)：给 **AI coding agent** 的操作手册，不是人类 README。

- 补充 build/test/风格/边界等 agent 执行所需信息
- 不写 marketing、不重复项目简介
- 规矩提炼、可执行；非 encyclopedia

## 分层与优先级

```
monorepo 根 AGENTS.md
  └── 各端根（vkk_client_flutter/AGENTS.md、rust_server/AGENTS.md、quasar/AGENTS.md）
        └── 子目录就近生效（离编辑文件最近者优先）
```

- **冲突时**：离编辑文件最近的 `AGENTS.md` 优先，但不得违背上级根规范
- **最高优先级**：用户当前 chat 指令

## 推荐写入

- **可执行 shell 命令**（精确 flag，非「跑一下测试」）
  - ✅ `cd doger_proto/dart && bash generate.sh` 后再 `flutter pub get`
- **目录/文件命名与结构约定**
  - ✅ 页面 `*_page.dart`；大页 StateBase + part mixin，单文件 ≤300 行
- **代码风格、框架偏好、本目录特有模式**
  - ✅ `StatelessWidget + mixin 拆分 build/生命周期`；mixin 统一 `on _XxxPageStateBase`
- **测试/提交/PR 规范**
  - 与根重复则写「见上级 `AGENTS.md`」或链到项目 git 提交规范
- **Always / Ask first / Never 边界**
  - ✅ Always：关键分支用 `AppLogger.log`，Tag 与页面类名一致
  - ✅ Ask first：改动 proto 前先确认是否跨端
  - ✅ Never：build 热路径打日志；mixin 环 `on` 另一 mixin
- **❌/✅ 正反例对照**（单条一行，便于 agent 扫描）

## 禁止写入

- 变更流水账、带日期的「评审沉淀(2026-xx-xx)」章节
- 评审编号罗列（R-B-xxx）而不提炼为可执行规矩
- 复制 `03-tasks` / `04-review` 全文
- knowledge 级业务规格（接口契约、状态机、表结构 → 放 `knowledge/`）
- 模糊指令（「注意质量」「保持整洁」）

## 篇幅与维护

- 单文件建议 **50～150 行**；规矩提炼，非 encyclopedia
- **约定变更时**同 PR 更新对应目录 `AGENTS.md`
- agent 反复犯同类错 → 补一条可执行规矩（删过时条目）

## 与相邻文档边界

| 文档 | 管什么 |
|---|---|
| 目录 `README.md` | 人类读者：模块简介、本地开发入口 |
| `knowledge/` | 业务规格、变更设计、十段式知识文件 |
| IDE Rules / 项目规范 | 全仓级持久规则（提交格式、日志格式等） |
| **本 spec** | 代码目录 `AGENTS.md` **写什么、禁止什么** |
| [kb-agents-precipitation.md](./kb-agents-precipitation.md) | KB 实现收尾**何时、往哪**沉淀 |

## KB 流程关联

实现类子 Agent（kb-builder）验收通过后收尾沉淀，见 [kb-agents-precipitation.md](./kb-agents-precipitation.md)；内容口径以**本文件**为准。

## 示例：流水账 vs 规矩

❌ **错误**（流水账）：

```markdown
## 评审沉淀（2026-06-18）
### R-B-004 SettingsPage StateBase
- 主文件 settings_page.dart…（复制评审全文）
```

✅ **正确**（规矩）：

```markdown
## StateBase + mixin
- 大页入口 ≤50 行；字段放 `_XxxPageStateBase`，mixin 仅 `on _XxxPageStateBase`
- mixin 顺序：Lifecycle → Data → Build（Build 放最后）
- ❌ 禁止 mixin 互相 `on` 成环
```

## 示例：业务逻辑 / 代码规范 / 业务规格

❌ **错误**（业务逻辑写入 AGENTS）：

```markdown
## 用户登录校验
- 密码错误超过 5 次须锁定账号 30 分钟
- 验证码过期后须重新发送
```

❌ **错误**（knowledge 级业务规格写入 `rust_server/AGENTS.md`）：

```markdown
## 用户列表 keyword 搜索
- `UserListHandler` 的 `list`、`count`、`list_admin_with_filters` 三处 keyword 条件须保持一致
- Quasar `UserListFilter` placeholder 须对齐
```

✅ **正确**（业务逻辑 → 实现代码；业务规格 → knowledge；AGENTS 只写代码规范）：

- 业务逻辑写在 Handler/Service 等实现代码中
- 同上 keyword 跨端一致性等业务规格放 `knowledge/工程平台/Rust服务端/0N-*.md`，由 `/kb-archive` 合并
- `rust_server/` 子目录 `AGENTS.md` 只写：`SQL 只允许写在 infrastructure/ 层` 等**代码规范**（目录编码规矩）