Change Safely

修改已有代码或数据的安全边界。改功能、修样式、调参数、重构、迁移数据、批量改动等任何触碰现有代码或数据的任务使用;改数据只出脚本不直接执行;先说影响面,不顺手重构,交付时只对值得完全理解的部分给位置和理由、对以后会用到的部分给契约,每个验证通过的步骤一个 commit,附用户可跑的验收命令。

RedGranite 8582fdd 3.1 KB Updated

File contents

change-safely:改之前先画边界

何时用

代码已经存在,任务是改它。新建从零的功能走 before-build。

硬规则

  • MUST 动手前说影响面:改哪些文件、哪些行为会变;有人会误以为会变的,说明不变。超出这个范围的改动不做。
  • NEVER 顺手重构、顺手改格式;依赖非必要不升级。发现问题单独列出,另起任务。
  • NEVER 直接执行改数据的操作(迁移、批量 UPDATE / DELETE、批量改文件);先写成脚本给用户看,脚本带 dry-run 或备份,确认后再跑。
  • MUST 改前工作树干净;改完且验证通过即 commit,一个步骤一个 commit。
  • MUST commit 信息准确到能当回滚说明:改了什么行为、为什么;不写"update"、"fix bug"。
  • MUST 交付时只说需要说的:值得完全理解的部分(core 逻辑、状态、接口,分法同 build-vs-buy)给位置和为什么值得;用户以后会调用或配置的部分给契约(输入、输出、失败表现);其余不提。
  • MUST 附一条用户可自己跑的验收命令和预期结果;跑不了的改动说明怎么观察。
  • NEVER 用"已测试""应该没问题"代替验收命令。

审问清单

  1. 这次改动碰到的文件,每个都在影响面里吗?
  2. 有没有一行改动是"顺手"的?
  3. 用户回滚这个 commit,能从信息里看出会失去什么吗?
  4. 我标为值得读的,用户以后改需求时会碰到吗?不会就不标。
  5. 验收命令用户在他的机器上能跑吗?

反模式

  • 错误:要求改按钮颜色,同时把组件拆成三个文件。→ 正确:改颜色,commit;拆分作为建议单独列出。
  • 错误:commit 信息 fix。→ 正确:fix(checkout): 优惠券金额超过订单总额时不再出现负数
  • 错误:交付逐个文件解释改了什么。→ 正确:只说 api.py 第 40-62 行退款状态机新增 partial 态、以后改退款规则都在这;format_money 只给签名 format_money(cents) -> str,负数抛 ValueError;配置改动一句带过。
  • 错误:直接跑 ALTER TABLE users ADD UNIQUE(email),重复数据丢失。→ 正确:先写脚本,第一步查出重复项打印出来,用户确认处理方式后再加约束。
  • 错误:"已经测试过了。" → 正确:"运行 python -m pytest tests/test_refund.py,应看到 4 passed;或在页面申请部分退款,订单状态应显示「部分退款」。"

输出要求

动手前:影响面。交付时:值得读的位置与理由(如有)、契约(如有)、验收命令与预期、commit 列表。

RedGranite/smartskill/tree/main/skills/coding/change-safely commit 8582fdd34d

Frequently asked questions

npx skillmds@latest add redgranite/change-safely