# 最佳实践 ## 1. 测试即一切 ### 原则 - 每个新功能实现前先写测试 - 发现 bug 时先添加复现测试 - 测试是最重要的部分 ### 测试优先级 ``` 1. 核心功能测试（必须） 2. 边界条件测试（重要） 3. 集成测试（推荐） 4. 性能测试（可选） ``` ### 测试命名 ``` test_{功能}_{场景}_{预期结果} 例如： test_task_creation_minimal test_task_creation_with_invalid_data ``` ## 2. 记录失败方法 **这是最重要的实践！** ### 为什么重要 - 智能体每次会话都是"新生的" - 不记录就会重复尝试同样的失败方法 - 浪费时间和资源 ### 如何记录在 CHANGELOG.md 中： ```markdown ## 失败的方法 ### 方法：使用 Python 实现 - 2026-03-19 **尝试**: 使用 Python 创建任务计划表，使用 pytest 测试套件 **结果**: 系统未安装 Python，命令不可用 **根本原因**: - 当前环境未配置 Python - Node.js 是主要运行时 **教训**: - 先检查环境再选择技术栈 - OpenClaw 项目优先使用 JavaScript/TypeScript **相关文件**: tests/test_planner.py（已弃用） ``` ### 记录什么 - 尝试了什么方法 - 为什么失败 - 根本原因是什么 - 学到了什么教训 - 相关文件路径 ## 3. 简洁输出 ### 原则上下文窗口是有限资源，输出要精炼。 ### 标准 | 情况 | 行数 | 内容 | |------|------|------| | 成功 | 5-10 行 | 结果摘要 | | 失败 | ~20 行 | 错误信息 + 原因 | | 进度 | ~10 行 | 当前状态 | ### 输出格式 **成功**： ``` ✅ 任务完成测试: 22 passed 覆盖率: 85% 文件: src/Task.ts, src/store.ts ``` **失败**： ``` ❌ 测试失败错误: test_task_creation Expected: "pending" Got: "in_progress" 位置: tests/planner.test.ts:45 原因: 状态初始化错误 ``` ### 避免 - ❌ 打印完整数组 - ❌ 打印完整日志 - ❌ 冗长的描述 ## 4. 每步更新 CHANGELOG ### 何时更新 - 完成一个子任务 - 发现一个问题 - 尝试一个方法（成功或失败） - 达到一个里程碑 ### 更新什么 - 当前状态 - 进度百分比 - 完成的任务 - 下一步行动 ### 示例 ```markdown ## 当前状态: Phase 1 完成 **进度**: 5/14 任务完成，36% **下一步行动**: 1. 实现 CLI 界面 2. 编写验证报告 ``` ## 5. 定向协议 ### 什么是定向协议每个会话开始时执行的固定步骤。 ### 为什么需要 - 确保从正确位置开始 - 快速恢复上下文 - 避免重复工作 ### 示例协议 ```markdown ## 定向协议每个会话开始时： 1. 读取 CHANGELOG.md 的"当前状态"和"下一步" 2. 运行快速测试确认无回归 3. 从优先列表选择任务 4. 开始工作 ``` ### 协议设计原则 - 简单明了 - 可快速执行 - 能恢复上下文 ## 6. Git 提交粒度 ### 原则每个"有意义的工作单元"提交一次。 ### 什么是"有意义的工作单元" - 一个功能实现 - 一个 bug 修复 - 一个重构 - 一组相关改动 ### 提交信息格式 ``` :