mcpField
E
engineering-small-prs

engineering-small-prs

github.com/agentara开发619125 次安装4 周前更新
代码仓库

关于 engineering-small-prs

Engineering Small PRs 是一项将改动规划为聚焦且易评审的 PR 的开发技能。它帮助团队把工作拆成可构建的步骤，明确依赖与测试，并安排迁移顺序，使改动更易理解和合并。

主要功能

  1. 01明确单一改动目标
  2. 02拆分为独立 PR
  3. 03梳理依赖和合并顺序
  4. 04确保每个步骤均可构建
  5. 05规划迁移阶段与回滚
  6. 06记录评审背景和测试

适用场景

  1. 01将大型功能拆成易评审的 PR
  2. 02准备安全的架构或 API 迁移
  3. 03分离重构与行为改动
  4. 04规划改动的测试与合并顺序

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/agentara/skills --skill engineering-small-prs

安装后在 Claude Code 中输入/engineering-small-prs确认已加载。

详细介绍

小型 PR 的工程实践

小型 PR 更容易得到全面审查，合并起来更安全，回滚起来更容易；如果方向发生变化，也更不容易造成无用功。“小型”指的是概念上聚焦且自成一体，而不只是代码行数少。

改编自 Google 工程实践文档，尤其是《Small CLs》。来源：https://google.github.io/eng-practices/review/developer/small-cls.html。许可证：CC-BY 3.0。

优质小型 PR 的定义

优质 PR：

  • 完成一项自成一体的改动。
  • 包含验证该改动所需的测试。
  • 合并后保持系统正常运行。
  • 在 PR 描述、现有代码或更早审查过的 PR 中，为审查者提供足够的背景信息。
  • 不会小到无法理解其行为。新 API 通常至少需要在同一个 PR 中包含一个用法示例。
  • 将大型重构与行为变更分开，除非清理工作非常局部。

如果 PR 过大，无法得到良好审查，审查者完全可以仅以此为由拒绝它。

拆分工作流

  1. 用一句话描述最终目标。
  2. 列出相互独立的行为变更、重构、架构／配置变更、测试和文档。
  3. 找出必须先行合并的依赖项。
  4. 从下方章节中选择拆分策略。
  5. 安排合并顺序，确保每个 PR 合并后构建都能通过。
  6. 补充背景说明，帮助审查者理解每个 PR 如何融入整体工作。
  7. 对有风险或无法避免的大型变更，在提交 PR 前征得审查者同意。

拆分策略

  • 先补准备性测试：在进行有风险的重构之前，为现有行为补充缺失的测试。
  • 先重构：移动、重命名、提取或简化代码，但不改变行为。
  • 垂直切片：端到端地交付一项小型、用户可见或 API 可见的行为。
  • 水平切片：仅在同一个 PR 中配套真实的首次用法，或已有一个明确关联且正在审查中的依赖 PR 时，才添加共享接口、协议定义或适配器。
  • 按文件或负责人分组：如果各项变更本身自成一体，可根据审查者的专长拆分文件。
  • 单独处理配置：如果回滚时机不同，将发布配置、实验或部署接线与代码分开。
  • 单独处理生成式或机械式变更：将可信的自动化改写与手写逻辑隔离开。
  • 适时单独删除：移除无用代码可以形成简洁且易于审查的 PR。

迁移安全

对于架构、数据、API 或基础设施迁移，优先采用扩展／收缩流程：

  1. 扩展：添加向后兼容的架构／API／配置支持，不移除旧行为。
  2. 双路径：仅在必要时同时写入或读取两条路径，并监控差异。
  3. 回填：迁移现有数据，并跟踪进度、处理重试和进行验证。
  4. 切换：验证确认两条路径都安全后，再切换流量或调用方。
  5. 收缩：在清理 PR 中移除旧架构、代码路径、标志和兼容性垫片。

每个迁移 PR 都应说明部署顺序、回滚行为、验证信号，以及在下一个 PR 合并前绝不能发生的事项。

输出模板

## Goal
[Final outcome]

## Proposed PR Sequence
| # | PR | Purpose | Depends On | Tests | Reviewer Notes |
|---|----|---------|------------|-------|----------------|
| 1 | Add characterization tests for ... | Protect existing behavior before refactor | None | ... | ... |
| 2 | Extract ... without behavior change | Prepare smaller implementation | 1 | ... | ... |
| 3 | Implement ... vertical slice | User-visible behavior | 2 | ... | ... |

## Migration Safety
- Expand/contract phase:
- Backfill/validation:
- Observability:
- Rollback:

## Build Safety
- Each PR keeps:
- Rollback notes:

## Large-Change Risk
- What could not be split:
- Reviewer consent needed:

启发式原则

  • PR 应比你认为必要的更小；审查者很少会反对聚焦的变更。
  • 如果一项小型逻辑变更分散到许多文件中，就应将其视为比代码行数所显示的更大。
  • 如果审查者需要大量未来背景才能理解 PR，说明拆分序列可能缺少更早的准备性 PR，或者 PR 描述不够完善。
  • 如果无法拆分 PR，就让它特别易于审查：加强测试、改进描述、明确风险，并事先取得审查者同意。

常见错误

  • 将大范围格式调整与功能逻辑混在一起。
  • 引入没有实际用法的新抽象。
  • 创建会导致中间 PR 无法通过构建的堆叠式提交序列。
  • 在“重构” PR 中掩盖有风险的行为变更。
  • 在安全的堆叠式工作流可行时，仍等一个 PR 合并后才开始下一个。

评论

支持 Markdown