# AI 文档按需加载策略

> 目标：在保证准确性的前提下，最小化上下文读取范围，节省 token 并提升执行速度。

## 1. 分层读取模型

- L0（启动必读）：`AGENTS.md`
- L1（任务必读）：按任务类型读取 1-3 个规则文档
- L2（证据按需）：仅在需要历史、计划、报告时读取具体文件，不批量全读

## 2. 任务到文档路由

| 任务类型 | 最小读取集 | 可选补充 |
|---|---|---|
| 代码修改 | `AGENTS.md` + `developers/CODE-STYLE.md` + `developers/CODE-STYLES/` 对应语言/场景规范 | `developers/SKILLS/SKILL_CODE_QUALITY_CHECK.md` |
| 文档修改 | `AGENTS.md` + `developers/DOC-RULES.md` | `developers/INDEX.md` |
| 计划状态更新 | `AGENTS.md` + `developers/INDEX.md` + `developers/DOC-RULES.md` | `developers/ANALYSIS/ANALYSIS_*.md` |
| 历史追溯 | `AGENTS.md` + `developers/SESSIONS/NOTE_YY_MM_DD.md` | `developers/REPORTS/` 文件 |
| 快照/无上下文接入 | `AGENTS.md` + `developers/SKILLS/SKILL_SNAPSHOT.md` | `snapshots/` 快照 |
| 查询代码完成情况 / 代码修改 | 上述最小读取集 + 条件读取代码快照（见第 3 节） | — |

## 3. 读取约束（强制）

- 禁止”先全量读所有文档再行动”。
- 对单次任务，优先在最小读取集内完成。

### 3.1 代码快照条件读取规则

代码快照（`repomix-output.xml` 或 `snapshots/` 下文件）**仅在满足以下条件之一时读取**，其余情况不主动加载：

| 触发条件 | 说明 |
|---|---|
| 需要查询某功能/模块的实现完成情况 | 如”XX 功能做了吗？做到哪一步？” |
| 需要在现有代码基础上做修改或扩展 | 如”在 XX 文件中增加 YY 逻辑” |
| 明确发现当前上下文对代码结构描述不足 | Agent 判断无法准确定位文件时 |

不触发快照读取的情况：

- 仅修改文档、规范、配置
- 仅做计划状态同步
- 用户未涉及代码内容的一般性对话

## 4. 代码检索优先级（强制）

定位代码符号、文件、实现时，**按以下顺序执行，不可跳步直接全量遍历**：

| 优先级 | 工具 / 资源 | 可用性 | 回退策略 |
|---|---|---|---|
| ① | `developers/CODE-INDEX.md` | 总是可用（文件存在时） | 文件不存在则跳过 |
| ② | `tags` 文件（ctags） | 需要安装 universal-ctags | 未安装 → 跳至 ③ |
| ③ | `ast-grep`（`sg` / `npx @ast-grep/cli`） | npx 无需安装 | npx 失败 → 跳至 ④ |
| ④ | `ripgrep`（`rg`）/ 系统 `grep` | 通常预装；不可用降级 grep | grep 兜底 |
| ⑤ | Repomix 快照 | ①-④ 均无法定位时 | 最后手段 |

> **禁止**：未经 ①-④ 尝试，直接读取全量快照或遍历目录。
> **容错**：每步检测工具可用性，不可用时立即降级，不报错中断。

## 5. 输出约束（建议）

- 回复优先给出“改动文件 + 验证结果 + 下一步”。
- 引用历史时仅引用必要片段与文件路径。