diff --git a/AGENTS.md b/AGENTS.md index 55a9215..a5a8253 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -107,6 +107,7 @@ - **方案可以改**:文档、计划和写了一半的代码都只是当时的最佳方案。发现更好的做法就换,在同一个改动里把文档改过来,说明改了什么、为什么;「先问维护者」里的事除外。 - **简单优先**:选最简单、又能完整解决问题的做法,代码量和问题的规模相称。每多一台服务器、一个进程或一个步骤,都要有明确的好处。 - **只做要求的事**:顺手发现的问题告诉开发者,不混进这次改动;和这次改动直接相关的小问题可以一起修,在汇报里说明。要用到的东西属于别的任务、还没做的,不先做个简化版,在 PR 里写明,留给那个任务;加接口和页面前,先查文档和别的 Issue 里有没有定过。 +- **举一反三**:发现一个问题,先想清楚它为什么会出现,再查同样的原因在别处有没有造成同样的问题,代码、文档、数据和配置都查,一起解决,比如改了一个决定,就在所有文档里搜一遍旧的说法。这算同一件事,不算「顺手发现的问题」。能用一个通用的做法解决的,不为各个特例分别打补丁。审查时也一样:发现一处,就查一遍同类的,一起指出来。 - **用证据说话**:结论只来自读过的代码和实际运行的结果;说「完成」前要真的运行过、看过结果。 - **自己定还是先问**:需求不清楚就先问,不靠猜。文档没写到的小细节和容易撤回的决定,按最简单合理的做法定,事后说明。要问的攒在一起问,每个问题附上推荐的选项和理由。 - **如实汇报**:先说结论,再说改了什么、怎么验证的;没跑的检查、失败的测试、没做完的部分照实说。 @@ -157,7 +158,7 @@ - 一个提交只做一件事:同一件事的代码、迁移、测试和文档放在一起,无关的格式调整和重构不混进来,依赖升级单独提交。只提交和这次改动有关的文件。 - 提交标题是一句动词开头的话,不超过 50 个字,不加 `feat:` 这类前缀,结尾不加句号;需要时空一行写正文,说明为什么改,值得注意的改动用 `- ` 列出。 - PR 标题和描述的写法同提交信息,squash 合并时它们就是 `main` 上的提交。写清为什么改、改了什么、怎么验证的;动了接口的写明对调用方有什么影响,改了界面的附截图。CI 通过后才能合并。 -- 按审查意见改时只改意见指出的地方;改动牵连到意见以外(比如类型不通、要动共享的代码)时,先在 PR 里问清楚,不另造一套绕过去。 +- 按审查意见改时只改意见指出的问题,同样的问题在别处也有的一起改(见「举一反三」);改动牵连到意见以外(比如类型不通、要动共享的代码)时,先在 PR 里问清楚,不另造一套绕过去。 - 分支名用英文小写加短横线,说明做什么,例如 `member-sync`,不加工具名前缀。 - 提交和 PR 只写改动本身:不加 `Co-Authored-By` 之类的署名,不提用什么工具生成。 - 不改写已推送的历史:不强推 `main`,自己的分支需要时用 `--force-with-lease`,不 amend 已推送的提交。不用会丢改动的命令(`git reset --hard`、`git checkout -- .`、`git clean`),不动工作区里别人的改动。