82 lines
4.6 KiB
Markdown
82 lines
4.6 KiB
Markdown
# 在实际工作流中验证了四个月并可跨 project 复用的 AGENTS.md
|
||
|
||
**来源**: [知乎](https://zhuanlan.zhihu.com/p/2009629370684306095)
|
||
**收录时间**: 2026-04-09
|
||
**标签**: #Agent #代码规范 #项目管理
|
||
|
||
---
|
||
|
||
## 文档写作原则：Self-Contained（自解释）
|
||
|
||
所有文档（PROGRESS.md、STATES.md、EXPERIMENTS.md、TODO.md）必须做到**只读文档就能完全理解**，不依赖对话上下文或任何脑内默认知识。
|
||
|
||
### 核心要求
|
||
|
||
1. **每个方法首次出现时必须解释它是什么、怎么做的**。不能只写"方法 A 效果好"，必须写"方法 A（用因果卷积在 MLP 打分前丰富 token 特征，让 gate 感知邻居信息）效果好"
|
||
|
||
2. **不要假设读者知道任何缩写**。首次使用缩写时必须给出全称和一句话解释。例如不要写"STE"，要写"STE（Straight-Through Estimator，前向用 hard 0/1 掩码，反向用 sigmoid 梯度近似）"
|
||
|
||
3. **实验结论必须包含足够上下文**。不要写"差距缩小到 0.001"，要写"TopK 自适应选择与 Fixed 周期掩码的质量差距从 0.005 缩小到 0.001（提高 gate 学习率从 0.001 到 0.1）"
|
||
|
||
4. **数字必须有参照物**。不要写"val_bpb=0.8605"，要写"val_bpb=0.8605（对比：无加速 baseline=0.840，Fixed 周期掩码=0.8605）"
|
||
|
||
5. **因果链要完整**。不要只记录结论，要记录**为什么**。"TopK 不如 Fixed"不够，要写"TopK 不如 Fixed，因为 TopK 的 think token 48% 紧挨着聚集（间距=1），导致部分 skip token 的信息供给不足（信息瓶颈），而 Fixed 均匀间隔保证每个 think token 只需支撑 2 个 skip token"
|
||
|
||
6. **docs/STATES.md 顶部维护一个术语表**，所有关键术语集中定义。其他文档开头引用该术语表即可
|
||
|
||
### 反面例子（禁止）
|
||
- "V11 实验效果不错" → 什么是 V11？做了什么？效果不错是多少？
|
||
- "提高了 gate LR" → 从多少到多少？为什么要提高？效果改善了多少？
|
||
- "信息瓶颈是核心问题" → 什么信息？什么瓶颈？为什么是核心？
|
||
|
||
### 正面例子（要求）
|
||
- "TopKConvGate 实验（在 MLP 打分前用 768 通道因果深度卷积让每个 token 看到前 7 个邻居的特征，帮助 gate 感知局部上下文以减少 think token 聚集）：E4T4D4 架构下 5k 步 val_bpb=0.8610，仍略差于 Fixed 周期掩码(0.8605)，差距 0.0005"
|
||
|
||
---
|
||
|
||
## 项目管理工作流
|
||
|
||
### 文档维护规范
|
||
|
||
**docs/PROGRESS.md**: 只记录"已经完成"的工作/实验/结论（附关键脚本/日志/ckpt 路径），不要写待办计划。
|
||
|
||
**docs/TODO.md**: 只记录"未完成/进行中/下一步"的待办与计划（尽量可一键复现）；完成后从 docs/TODO.md 移除对应项，并把结果写入 docs/PROGRESS.md（避免重复记录）。
|
||
|
||
**docs/STATES.md**: 只维护已经完成的成果，录入真正长期有用的东西而非临时的噪音。
|
||
|
||
**docs/EXPERIMENTS.md**: 实验相关内容的特殊STATE，专注于处理实验和数据。
|
||
|
||
### 关键原则
|
||
|
||
- 能用小数据集/短实验快速 debug 就不要用大数据集/长实验；优先最快迭代
|
||
- 每次准备做实验前必须先高层质疑与方向审视确认当前未知/最小实验/失败后下一步
|
||
- 两个文档都必须按时间升序记录（越早在前、越晚在后），新增内容只能追加到文件末尾
|
||
- 训练评测时只要是正式实验，一定要在正规文件里弄好脚本然后一键几乎无传参地跑
|
||
- 跑训练或评测必须在 tmux 里启动，避免中途断开导致任务退出
|
||
- 时刻注意删掉没用的 checkpoint 等大文件，维护空间不爆炸
|
||
- 有多个相同功能文件的时候，请把错误的冗余的全部都扔进 archive，只保留一个
|
||
|
||
### Git 提交规范
|
||
|
||
当完成一个完整功能或要进行破坏性改动时：
|
||
```bash
|
||
git add .
|
||
git commit -m "描述"
|
||
```
|
||
|
||
- 发现任何文档或代码有错误时，更新不要保留任何错误痕迹
|
||
- 写了一个新版本的正确文件，请删掉错误版本的文件
|
||
- 兼容性不要搞得那么好，不要 fallback
|
||
- 同样的功能禁止有错误实现，并且只能有一个位置正确实现，禁止冗余
|
||
|
||
---
|
||
|
||
## 其他要点
|
||
|
||
- 跟我沟通请使用中文。任何的临时测试都请在 tmp 文件夹
|
||
- 我们现在是在一个Docker环境里边，使用公共服务器的电脑。千万不要跟别的程序抢占GPU，这是绝对禁令
|
||
- 想用 GPU 的时候用 nvidia-smi 查看空闲 GPU 然后精确加载空闲的
|
||
- 你只要遇到问题就处理，遇到问题就处理，直到没有问题。不要问我顺序什么的
|
||
- 有不清楚的先记下来跳过，所有探究实现路径全部卡住了再都通知我
|
||
- 没用的东西放 archive/
|