# AI Agent 协作指南

本文面向使用 Claude Code、Codex、Qoder 等 AI Agent 工具参与 MNN 开发的贡献者。
目标是让 Agent 以渐进式披露的方式读取仓库信息，先理解任务边界，再读取必要文档和代码，避免全量扫描、误读内部目录或做无关改动。

## 入口顺序

Agent 进入仓库后，建议按以下顺序读取上下文：

1. `AGENTS.md`：仓库级规则、架构概览、代码风格、测试要求。
2. `docs/index.rst`：文档站目录，判断当前任务属于构建、推理、转换、贡献、性能还是测试。
3. 与任务直接相关的 `docs/` 页面：只读取当前任务需要的文档。
4. 与任务匹配的 `skills/*/SKILL.md`：如果任务命中 skill，再按 skill 中的步骤文档继续读取。
5. 相关源码和测试：在明确目标后再读取代码，优先用 `rg` 定位。

不要一开始全量读取 `docs/`、`skills/` 或整个源码树。MNN 代码量较大，全量扫描会增加噪声，也更容易把旧文档、示例代码或无关 backend 当成当前任务依据。

## 任务路由

常见任务可以按下表选择入口：

| 任务 | 优先读取 |
|------|----------|
| 新增或修改算子 | `skills/add-new-op/SKILL.md`、`docs/contribute/op.md`、`docs/testing.md` |
| LLM 模型适配或导出 | `skills/support-new-llm/SKILL.md`、`docs/transformers/llm.md` |
| ARM CPU 性能优化 | `skills/arm-cpu-optimize/SKILL.md`、`docs/perf/README.md` |
| OpenCL / Metal / Vulkan 优化 | 对应 backend skill、`docs/perf/README.md`、相关 backend 文档 |
| 测试、CI、测试阶段调整 | `skills/test-ci/SKILL.md`、`docs/testing.md` |
| C++ 推理用法 | `docs/start/quickstart_cpp.md`、`docs/inference/module.md`、`docs/inference/session.md` |
| Python 推理用法 | `docs/start/quickstart_python.md`、`docs/start/python.md`、`docs/pymnn/MNN.md` |
| 构建问题 | `docs/compile/engine.md`、`docs/compile/cmake.md`、`docs/faq.md` |
| 文档修改 | `docs/index.rst`、目标文档所在目录、本文档 |

如果文档和代码表现不一致，应以当前源码和测试结果为准，并在修改中同步更新相关文档或说明剩余差异。

## 读取原则

Agent 读取上下文时应遵循以下原则：

- 先读入口，再读细节：先确认任务类型、模块边界和验证方式，再进入实现文件。
- 按路径收敛：从 `docs/index.rst` 或 skill 入口跳到具体文档，不跨目录随意扩展。
- 按证据推进：每次读取应服务于一个明确问题，例如 API 用法、测试入口、backend 注册方式或性能指标。
- 保持最小改动：只修改完成任务所需的文件，不顺手重构无关代码。
- 区分指南和参考：`docs/start/`、`docs/inference/` 更偏使用指南；`docs/cpp/`、`docs/pymnn/` 更偏 API 参考；`skills/` 是 Agent 执行流程。

## 安全边界

Agent 必须遵守仓库根目录 `AGENTS.md` 中的限制：

- 不回滚用户已有改动，不用破坏性 git 命令清理工作区。
- 不把构建产物、临时日志、下载模型或本地环境文件加入提交。
- 不手动修改由脚本生成的文件，除非任务明确要求，并且同时说明生成方式。

涉及性能或体积的改动时，需要特别谨慎。MNN 是推理引擎，代码变更应优先考虑运行时性能、二进制大小、跨平台行为和低端设备资源限制。

## 执行与验证

Agent 在完成修改后，应根据变更类型选择验证方式：

| 修改类型 | 推荐验证 |
|----------|----------|
| 文档修改 | `cd docs && make clean html` |
| 测试脚本或测试矩阵 | `bash -n test.sh`、`python3 -m json.tool test_stages.json`、必要时运行 `./test.sh help` 或目标测试 |
| C++ 代码 | 对应模块编译、相关单元测试、必要时运行 `clang-format -i -style=file` |
| Python 代码 | 相关脚本的最小可运行测试，必要时补充单元测试 |
| backend 性能优化 | 正确性测试、目标 benchmark、改动前后性能记录 |

如果本地缺少依赖、设备或模型，应明确说明未运行的验证项和原因，不要把未验证结果写成已通过。

## 更新文档和 skill

当一次变更改变了开发流程、测试入口、目录结构或常见陷阱时，需要同步考虑：

- 更新 `docs/` 中面向人的说明。
- 更新相关 `skills/` 中面向 Agent 的步骤或注意事项。
- 对非平凡 skill 任务，按 `skills/retrospective/SKILL.md` 做复盘，将新经验沉淀回对应 skill。

文档负责解释“为什么”和“如何使用”，skill 负责约束 Agent “按什么步骤做”。两者保持一致，Agent 才能在后续任务中正确、高效地渐进读取上下文。