leesama/trunk-based-development

Trunk-Based Development

何时使用

当用户或仓库约定体现出以下意图时使用本技能：

• 明确提到 trunk-based、trunk base、主干开发、短分支、快速合并
• 要求基于 main / master / 团队约定的 trunk 来创建分支或同步代码
• 希望把大需求拆成可独立合并的小改动
• 需要在未完全交付前先合入 trunk，并且必须先建立 feature flag 或等效的默认关闭保护
• 需要判断当前改动是否过大、是否偏离 trunk-based 的节奏

核心原则

• trunk 是唯一集成主线；不要默认长期停留在分叉很久的功能分支上工作。
• 改动必须尽量小、可验证、可回滚，优先追求“今天可合并”，不是“一次做完全部”。
• 只要未完成功能要先合入 trunk，就必须建立 feature flag 或等效的默认关闭保护，不能把半成品直接暴露在 trunk 上。
• 如果当前改动无法被 feature flag 安全关闭，说明拆分还不够小，应继续缩小增量或先补保护层。
• 分支生命周期应尽量短；默认从最新 trunk 切出短分支，完成后尽快合并并删除。
• 一个分支只做一件事；无关改动要拆开，不要顺手混入重构、格式化和额外修复。

执行流程

1. 识别 trunk

• 不要想当然把某个分支当作 trunk；优先识别仓库默认分支或团队明确指定的主线。
• 常见 trunk 是 main 或 master；若仓库另有约定，以仓库约定为准。
• 如果无法确认远端状态，就基于本地已知 trunk 工作，并在回复里明确说明这一点。

2. 先判断改动是否需要拆分

出现以下情况时，先拆成多个可独立合并的增量：

• 同时跨多个业务域、多个页面或多个基础模块
• 既改行为又大规模重构
• 需要数天以上才能形成可验证结果
• 不能在一次最小验证中证明安全性

拆分时优先选择：

1. 先铺底层兼容代码，不改变现有行为
2. 再接入新逻辑，但默认关闭
3. 最后切换入口、清理旧路径

3. 未完成功能必须先建 feature flag

• 只要本次改动不是完整交付、仍可能继续迭代，但又希望先合回 trunk，就必须先建立 feature flag。
• 隐藏入口、默认关闭配置、兼容分支逻辑 可以作为 feature flag 的具体实现方式或补充保护，但不能省略“可显式控制启停”的开关能力。
• 如果一项改动做不到在 trunk 中默认关闭，就不要把它当作“可提前合入”的增量；先继续拆分，或先补开关基础设施。
• 在回复用户、准备 PR 或描述方案时，要明确指出 feature flag 的名称、默认状态，以及后续何时移除。

4. 选择分支策略

• 默认做法：从最新 trunk 拉短分支。
• 分支名优先遵循仓库约定；若仓库没有明确规范，则保持简短、语义清晰，并与当前任务直接对应。
• 只有在用户明确要求且团队允许直推 trunk 时，才直接在 trunk 上提交。
• 如果当前工作区已有用户未完成改动，先理解并避让，不要强行重置或覆盖。

5. 保持与 trunk 同步

• 开始实现前，尽量基于最新 trunk。
• 在提交、开 PR 或准备合并前，如果 trunk 已明显前进，优先 rebase 到 trunk 最新状态，再重新验证。
• 若网络、权限或远端访问受限，至少基于本地最新 trunk 工作，并把限制条件告诉用户。

6. 验证必须贴合改动面

• trunk-based 不等于弱化质量门禁；每次小改动都应完成最小充分验证。
• 优先运行与改动直接相关的检查：测试、类型检查、构建、lint、关键路径手测。
• 如果无法完成某项验证，要明确缺口及风险，不要把“未验证”包装成“已完成”。

7. 合并准备

当需要准备 PR、合并说明或交付结论时，默认给出这些信息：

• trunk 分支是什么
• 当前分支是否为短分支、名称是什么
• 这次改动为什么足够小、可独立合并
• 是否使用了 feature flag / 隐藏入口 / 兼容逻辑
• 已完成哪些验证，仍有哪些风险

避免这些做法

• 长期功能分支不回 trunk
• 一个 PR 混入多类无关修改
• 为了“先合入”而跳过必要验证
• 未建 feature flag 就把未完成功能直接合入 trunk
• 把半成品直接暴露给用户且没有开关或保护逻辑
• 分支明显落后 trunk 很久却继续堆改动

响应偏好

• 如果用户的任务不符合 trunk-based 节奏，先主动收敛范围，再动手实现。
• 如果任务天然适合拆分，默认直接按增量方案执行，而不是把完整大方案一次塞进同一分支。
• 当用户要求建分支、准备 PR、同步主线或评估改动大小时，优先按本技能的约束给出可执行结论。