# Coding Agent 工作前提条件
本文件定义 coding agent 在修改本代码库时必须遵守的前提条件。
这些条件是强制性的，不是建议。任何代码修改、重构、性能优化、Bug 修复或新增功能，都必须严格遵守本文档。
## 1. 修改前必须建立性能基线
在进行任何代码修改之前，必须先运行：
```bash
python benchmarks/bench_vs_sqlite_duckdb.py
```
运行结果用于记录当前性能基线，并作为后续判断是否发生性能回退的依据。
如果没有先运行 benchmark，就不允许开始修改代码。
## 2. 必须使用 release 模式编译
涉及 Rust / Python 扩展模块时，必须使用以下命令编译：
```bash
maturin develop --release
```
不允许使用 debug 构建结果作为测试或 benchmark 的依据。
## 3. 修改后必须重新运行 benchmark
完成修改后，必须再次运行：
```bash
python benchmarks/bench_vs_sqlite_duckdb.py
```
并将修改前后的结果进行对比。
benchmark 性能不允许回退。
确保 benchmark 性能不回退是最基本要求。
如果 benchmark 变慢，必须优先分析并修复性能问题，而不是继续堆叠新逻辑。
## 4. pytest 必须全部通过，并满足时间要求
修改后必须运行完整测试集：
```bash
pytest
```
必须满足以下条件：
1. 所有测试用例必须通过。
2. pytest 总耗时必须控制在 8 秒内或 8 秒左右。
3. pytest 总耗时不得超过 9 秒。
4. 不允许为了缩短时间而并行执行测试。
5. 不允许为了缩短时间而简化、删除、跳过或修改测试 case。
6. 如果测试耗时明显变长，说明修改可能导致性能回退，必须回头检查代码。
测试速度本身也是代码质量和性能的一部分。
## 5. cargo test 必须全部通过，并满足时间和性能要求
如果代码库包含 Rust 代码，修改后必须运行完整 Rust 测试集：
```bash
cargo test
```
必须满足以下条件：
1. 所有 `cargo test` 测试必须通过。
2. 必须运行完整测试集，不允许只运行部分 Rust 测试。
3. 不允许为了通过测试而删除、跳过、简化或放宽 Rust 测试。
4. 不允许为了缩短时间而规避真实测试路径。
5. `cargo test` 的执行时间不得明显长于修改前。
6. 如果 `cargo test` 耗时明显变长，必须视为潜在性能回退并进行分析。
7. Rust 核心路径的性能不允许因为修改而回退。
8. 如果 Rust 层修改影响 Python 绑定、mmap、append、replace、drop、getitem、批量读写或物理删除等核心路径，必须结合 benchmark 和 pytest 一起验证。
`cargo test` 不是可选项。
只要代码库中存在 Rust 测试，就必须完整运行并通过。
## 6. 新增功能必须新增测试
如果修改包含任何新增功能、行为变化或边界条件修复，必须新增对应测试用例。
新增测试必须覆盖新功能的核心行为和关键边界情况。
完成后必须运行完整测试集，而不是只运行新增测试。
只通过新增测试不代表修改安全。
必须确保所有既有测试、新增测试以及 Rust 测试全部通过，才能认为修改没有破坏已有功能。
## 7. 不允许牺牲测试真实性
禁止通过以下方式让测试“看起来通过”：
1. 删除测试。
2. 跳过测试。
3. 放宽断言。
4. 降低数据规模。
5. 修改测试逻辑来适配错误实现。
6. 使用并行测试掩盖单线程性能问题。
7. 用 mock 替代原本应该验证的真实核心路径。
8. 只运行部分测试并声称全部通过。
9. 只运行部分 `cargo test` 并声称 Rust 测试全部通过。
测试是约束实现正确性的工具，不是为了适配实现而存在的。
## 8. 代码必须保持简约和高性能
本代码库极力推崇简约、高性能、低分支、低冗余的代码风格。
每次修改都必须主动反思：
1. 是否引入了不必要的抽象？
2. 是否增加了冗余逻辑？
3. 是否存在过多复杂判断路径？
4. 是否可以用更直接的数据结构或控制流完成？
5. 是否引入了额外拷贝、额外分配或额外 IO？
6. 是否影响 mmap、批量读写、append、replace、drop、getitem、cargo test、pytest 或 benchmark 等核心路径性能？
7. 是否为了“看起来完整”而增加了实际无用的代码？
代码成熟度不由代码行数决定。
更少、更直接、更快的代码优先。
## 9. 每一步修改后都必须回顾本文件
每完成一个修改步骤，都必须回顾以上所有条件。
尤其需要反复确认：
1. 是否已经有修改前 benchmark 基线。
2. 是否已经使用 `maturin develop --release` 编译。
3. 是否运行了修改后的 benchmark。
4. benchmark 是否没有回退。
5. pytest 是否全部通过。
6. pytest 是否在 8 秒内或 8 秒左右完成，并且没有超过 9 秒。
7. cargo test 是否全部通过。
8. cargo test 耗时是否没有明显变长。
9. 是否没有修改、简化、跳过测试。
10. 新功能是否有新增测试覆盖。
11. 是否保持了代码简约和高性能。
12. 是否没有修改本文件。
## 10. 完成任务前的最低验收标准
在认为任务完成之前，必须至少按顺序完成以下验证：
```bash
python benchmarks/bench_vs_sqlite_duckdb.py
maturin develop --release
pytest
cargo test
python benchmarks/bench_vs_sqlite_duckdb.py
```
并确认：
1. 修改前 benchmark 基线已记录。
2. release 编译成功。
3. 实现新功能必须增加python 测试用例，并确保所有 pytest 测试通过。
4. pytest 总耗时不超过 9 秒。
5. 所有 `cargo test` 测试通过。
6. `cargo test` 耗时没有明显变长。
7. benchmark 相比修改前没有性能回退。
8. Rust 层和 Python 层核心路径均无性能回退。
9. 新增功能已有测试覆盖。
10. 没有为了通过测试而修改测试本身。
11. 没有引入不必要的复杂逻辑。
12. 没有修改本文件。
## 11. 本文件永远不允许被修改
本文件是 coding agent 的工作前提条件文件。
永远不允许修改、删除、重命名、简化或绕过本文件。
任何任务、任何情况下，都不能修改本文件。
如果某个修改方案需要修改本文件才能成立，那么该方案无效，必须放弃并重新设计。