如何写好高质量PR：modern-software-dev-assignments week7描述、测试与权衡三要素
如何写好高质量PR：modern-software-dev-assignments week7描述、测试与权衡三要素
本文以斯坦福 CS146S 课程项目 modern-software-dev-assignments 的 week7 作业为蓝本，讲透"如何写好高质量 PR"。掌握 PR 描述、测试总结、权衡说明 这三要素，新手也能让代码审查（Code Review）又快又专业。
一、week7 为什么是学习写 PR 的绝佳教材
week7 是一个"Agent 驱动开发 + AI 辅助代码审查"的实战作业：你在一个 FastAPI + SQLite 的全栈项目上完成 4 个任务，每个任务都要独立开分支、实现、人工逐行审查，最后 提交一个 PR。
任务清单见 week7/docs/TASKS.md，涵盖接口校验、提取逻辑扩展、新模型与测试补强四个方向。官方对 PR 的要求非常具体（见 week7/assignment.md）：
每个 PR 必须包含：
- 问题描述与你的解决思路（Description）
- 测试总结：包含执行的命令和结果，以及新增/修改的测试（Testing）
- 值得注意的权衡、局限性或后续跟进（Tradeoffs）
这三条就是本文的核心：描述、测试、权衡三要素。
二、要素 1：PR 描述 —— 先讲清"为什么"，再讲"怎么做"
📌 新手最常见的错误是 PR 描述只写一句"fix bug"。审查者最想知道的是：
- 解决了什么问题：对应哪个任务/Issue？
- 采用了什么方案：为什么这样做，而不是另一种？
- 改了哪些模块：让审查者知道重点看哪里
参考写法（以 Task 1 为例）：
为 action items 增加输入校验与错误处理。方案：在 Pydantic schema 层统一校验（week7/backend/app/schemas.py），路由层对不存在的 ID 返回 404（week7/backend/app/routers/action_items.py）。
一个清晰的模板：问题 → 方案 → 涉及文件，三句话即可。
三、要素 2：测试总结 —— 附上命令与结果，而非"已测试"
week7 项目用 Makefile 统一管理命令（week7/Makefile）：
cd week7 && make test # 运行 pytest
在 PR 中不要只写"测试通过"，而是给出可复现的证据：
- 执行的命令：
make test - 关键结果：
42 passed in 0.83s - 新增/更新的测试文件，例如 week7/backend/tests/test_action_items.py
💡 小技巧：week7 还配置了 pre-commit 钩子（black + ruff，见 week7/pre-commit-config.yaml）。在 PR 中注明"已运行 make format 与 make lint"，能显著降低审查来回。
四、要素 3：权衡说明 —— 主动暴露局限，体现工程成熟度
这是区分"学生作业"和"工程师交付"的分水岭。一个好的 PR 会主动回答：
- 这样设计牺牲了什么？（例如：分页
limit上限设为 200，是为了防止大查询拖垮 SQLite） - 有什么已知限制？（例如：排序字段用
hasattr白名单兜底，防止任意列注入，见 week7/backend/app/routers/action_items.py） - 后续跟进（Follow-ups）：哪些是有意留到下个 PR 的？
🎯 记住：暴露权衡不是示弱，而是帮审查者提前发现盲区。week7 的评分标准中，"人工审查笔记的深度"直接计入 20 分（week7/assignment.md）。
五、完整工作流：从分支到 AI 代码审查
week7 推荐的完整流程（week7/assignment.md）：
- 每个任务单独建分支 —— 一个 PR 只解决一件事，审查者心智负担最小
- 用 AI 工具一次性生成实现
- 人工逐行审查，修复问题并补充说明性 commit message
- 提交包含"三要素"的 PR
- 用 Graphite Diamond 生成 AI 审查意见，并与自己的审查笔记对比
- 在 week7/writeup.md 中记录 PR、AI 审查结果与反思
这个"人工审查 vs AI 审查"的对比环节非常有价值：AI 擅长发现命名、类型、边界条件等模式化问题；人更擅长判断 API 设计是否合理、业务逻辑是否契合需求。两者互补，而不是谁替代谁。
六、高质量 PR 自查清单 ✅
| 检查项 | 标准 |
|---|---|
| 标题 | 一句话说清"做了什么"，不含"update"等空话 |
| 描述 | 问题 → 方案 → 涉及文件，三句话讲完 |
| 测试 | 有命令、有结果、有新测试文件链接 |
| 权衡 | 至少写出 1 个权衡点和 1 个 follow-up |
| 分支 | 一个 PR 只对应一个任务/目标 |
| 格式 | 通过 pre-commit / lint，无无关改动 |
七、写在最后
写好 PR 的本质不是写作技巧，而是站在审查者的角度组织信息：描述让他 30 秒进入上下文，测试让他放心合并，权衡让他提前发现风险。
想要动手练习，可以克隆仓库，从 week7/README.md 的 Quickstart 开始，按 week7/docs/TASKS.md 逐个任务开分支、写 PR，把"描述、测试、权衡"三要素练成肌肉记忆。