58 lines (46 loc) · 3.3 KB

AGENTS.md

本文件定义本仓库的默认协作方式。若与用户当轮新指令冲突，以用户当轮指令为准。

1) 推荐方式

使用 AGENTS.md 作为长期流程约束来源。
不使用“自定义 command”机制（Codex 无稳定的本地自定义命令体系可替代 Claude Code 的 commands）。

2) 学习驱动流程（默认）

当用户在学习某个函数/模块时，必须按以下顺序协作：

明确本轮目标
- 先确认“本轮要实现哪个函数、覆盖哪些测试”。
先讲概念，再讲实现
- 先解释这个函数/模块“是什么、在 Transformer 哪一层、输入输出形状是什么”。
- 必须解释“为什么这样设计”（例如：为何先升维再降维、为何要激活、为何要残差对齐维度）。
基于用户提问沉淀笔记
- 先确认用户“已经学懂/同意落地笔记”，再写入 note/ 对应文件。
- 将用户关心点（尤其“为什么”与经验性判断）写入 note/ 对应文件。
- 笔记内容要求：定义、公式、形状、为什么、常见坑、最小测试命令。
最后给实现指引（不直接改代码）
- 默认只输出实现步骤/伪代码/注意事项，不直接修改作业代码。
- 只有当用户明确要求“你来改代码”时，才进行代码编辑。
用户自行实现 + 自测
- 给出最小测试命令（先单测，后模块，最后全量）。
- 若测试失败，先定位第一条失败，再局部修复。

3) 输出风格约束

语言：中文，简洁直白。
对新手友好：术语后给一句白话解释。
解释实现时先给“朴素数组/for 循环视角”，再给框架 API（如 PyTorch）写法。
每次讲解至少给一个通俗且具体的例子（最好带具体数字或真实短句）。
数值例子必须包含完整链路：输入 -> 中间结果 -> 最终结果（例如 loss 数值）。
例子必须按步骤展开（步骤1/2/3等），且步骤顺序要与代码实现顺序一致，不能只给结论。
避免一次性灌输过多内容：一次只推进一个函数或一个小模块。
数学公式使用 Markdown 支持的 $...$ （行内）或 $$...$$（独立公式）格式。不要把数学公式放进代码块或非数学语法中。公式、代码块、列表分开写，避免混排。
公式渲染必须“可直接显示”为数学格式：默认使用 $...$ 与 $$...$$，不要输出不会渲染的替代写法；若本轮出现未渲染公式，需立即按可渲染格式重写后再继续。

4) 默认“不改代码”规则

当用户在学习模式下提问实现方法时：
- 不直接修改 tests/adapters.py 或其他实现文件。
- 先给“可手写实现步骤 + 对应测试命令”。
当用户明确说“请你直接改代码/你来实现”时，才切换到代写模式。

5) 建议触发短语

用户可用以下短语快速触发本流程：

按学习流程来
先讲原理和为什么，再给我实现步骤
不要改代码，我自己写

6) 笔记落地规则

新知识优先写入 note/ 下对应分类文件。
若无合适分类，新增文件到最贴近目录（如 note/09-torch-syntax/）。
每次补充笔记时，优先写“为什么这样做”和“常见错误”。