文档管理体系

核心原则

1. 按项目记录 — 文档写在当前工作的项目目录下
2. 自动触发 — 完成有价值工作后主动更新，不等用户要求
3. 增量更新 — 追加写入，不覆盖历史记录
4. 简洁有用 — 记录关键信息，不写废话

文档结构

项目根目录/
├── README.md              # 项目说明（功能、使用方式）
├── CHANGELOG.md           # 版本变更记录
└── docs/
    ├── DEVLOG.md          # 开发日志（代码变更）
    ├── EXPERIMENT.md      # 实验日志（训练、评估）
    ├── RESEARCH.md        # 调研笔记（论文、方案调研）
    ├── TODO.md            # 任务管理（待做、进行中、已完成）
    └── decisions/         # 决策记录
        └── NNNN-title.md  # 重要技术决策

各类文档模板

1. 开发日志 (docs/DEVLOG.md)

完成代码开发、bug修复、重构后记录。

## YYYY-MM-DD - 简要标题

### 变更类型
feature | fix | refactor | config

### 变更内容
- 具体改动 1
- 具体改动 2

### 相关文件
- `path/to/file1.py` — 改动说明
- `path/to/file2.py` — 改动说明

### 验证
- [x] 测试通过 / 功能验证

2. 实验日志 (docs/EXPERIMENT.md)

完成训练实验、评估跑分、对比测试后记录。对 ML 工作最重要的文档。

## YYYY-MM-DD - 实验名称

### 目标
本次实验要验证什么假设 / 解决什么问题

### 配置
| 参数 | 值 |
|------|-----|
| 模型 | xxx |
| 数据集 | xxx (N条) |
| batch_size | 8 |
| lr | 1e-4 |
| epochs | 10 |
| GPU | A100 x 1 |

### 结果
| 指标 | 值 | 基线对比 |
|------|-----|---------|
| metric1 | 0.85 | +0.03 |
| metric2 | 0.72 | -0.01 |

### 分析
- 什么 work 了，为什么
- 什么没 work，可能的原因

### 结论与下一步
- 结论：xxx
- 下一步：尝试 xxx

### 相关文件
- 配置: `configs/exp_xxx.yaml`
- 脚本: `scripts/train_xxx.sh`
- 输出: `/path/to/output/`

3. 调研笔记 (docs/RESEARCH.md)

论文阅读、方案调研、技术选型后记录。

## YYYY-MM-DD - 调研主题

### 背景
为什么需要调研这个

### 调研内容

#### 方案/论文 A: 名称
- 核心思路: 一句话
- 优势: ...
- 劣势: ...
- 参考: [链接/论文名]

#### 方案/论文 B: 名称
- ...

### 对比总结
| 维度 | 方案A | 方案B |
|------|-------|-------|
| 性能 | ... | ... |
| 复杂度 | ... | ... |
| 适用性 | ... | ... |

### 结论
选择 X，因为 ...

4. 任务管理 (docs/TODO.md)

项目级的任务追踪。

# TODO

## 进行中
- [ ] 任务描述 — @负责人 — 开始日期
  - 进展: 当前状态

## 待做
- [ ] 任务描述 — 优先级(高/中/低)

## 已完成
- [x] 任务描述 — 完成日期

5. 决策记录 (docs/decisions/NNNN-title.md)

重要技术决策时创建独立文件。

# NNNN - 决策标题

## 状态
accepted | proposed | deprecated

## 背景
什么情况下需要做这个决策

## 决策
选择了什么方案

## 理由
为什么选这个方案，考虑了哪些替代方案

## 影响
这个决策会带来什么后果

6. CHANGELOG (CHANGELOG.md)

面向外部的版本变更记录。

# Changelog

## [Unreleased]

### Added
- 新功能描述

### Changed
- 变更描述

### Fixed
- 修复描述

自动触发规则

完成的工作	更新的文档
代码开发、bug 修复、重构	DEVLOG.md + CHANGELOG.md
训练实验、评估跑分	EXPERIMENT.md
论文阅读、方案调研	RESEARCH.md
重要技术决策	decisions/NNNN-title.md
新建/推进/完成任务	TODO.md
新增重要功能	README.md

联动规则

• Plan 完成后 → 更新 TODO.md（添加计划中的任务）
• 压缩前 → 更新 DEVLOG.md（保存当前进展）
• 实验结束后 → 更新 EXPERIMENT.md + TODO.md（记录结果和下一步）
• 决策确定后 → 创建 decisions/ 文件 + 更新 DEVLOG.md