用 gf 开发 gf:一次真实的 dogfooding 案例
gf 从第一行代码开始,就是用它自己驱动开发的:需求进 Issue,评估进四阶段编排,代码通过本地合并或 PR 交付,发布用它自己的 gf release。本文初次发布时采集了 30 个 gf-workflow 历史执行合同,横跨 fast / standard / full 三种模式。这篇文章保留当时的样本与结论,同时按当前工作流更新功能说明。
更新说明(2026-09-23):旧版工作流默认派发后台代理并固定创建 PR。当前版本已移除后台代理模式,执行改为“手动新窗口”或显式选择“同会话”,交付可选本地合并或推送并创建 PR。
四阶段编排:一次真实的走查
/gf-workflow 把一次改动切成四个强制闸门的阶段:需求澄清 → 计划制定 → 执行 → 交付后检查。阶段流转只有一个强制审批闸门(计划批准);执行中的安全检查选择、交付方式以及收尾清理仍会按场景请求确认。以 v1.0.0 发布前的一次真实 dogfooding 会话为例(docs/dogfooding-report-v1.0.0.md):
$ /gf-workflow release-dogfooding
# Phase 1: 需求澄清
→ 读取发布检查清单,确定本轮 GitHub 可执行项范围
# Phase 3: 执行(逐项验收)
✅ gf release create --tag-name <tag> PASS
✅ Release 在 GitHub 网页可见 PASS
✅ 非交互模式 --yes 传递 PASS
❌ 删除操作幂等,重复删除不报错 FAIL
❌ 删除后 git tag 清理(--cleanup-tag) FAIL流程在这里没有”发现问题就算了”,而是直接把两个 FAIL 项转成了 Issue #130:release delete 没有清理残留的 git tag,重复删除同一个 release 还会报错而不是幂等返回。根因很具体——crates/github/src/release.rs 里的 delete 调用 gh release delete 时没传 --cleanup-tag,也没有对”release not found”做幂等判断。
修复走的是同一套 TDD 闭环:PR #131 补了 3 个测试(JSON 幂等、纯文本幂等、--cleanup-tag 参数断言),跑通 gitflow-github crate 全部 202 个测试,clippy --all-targets --all-features -- -D warnings -W clippy::pedantic 干净。复验环节重新走一遍”创建 → 删除 → tag 清理确认 → 重复删除幂等”,全部转绿后才在报告里写下 APPROVED。
这不是唯一一次。仓库里现存的 docs/dogfooding-report-*.md、docs/pipeline-analysis-report-*.md、docs/code-review-report-*.md 加起来几十份,每一份都是某次真实执行留下的证据链,而不是补写的总结。
历史样本:30 个合同背后的分布
gf-workflow 的模式不是”一刀切”,而是按改动复杂度自动分诊:docs:/chore:/hotfix 前缀走 fast(可跳过计划阶段,执行验证与收尾仍不可跳过),单文件 fix:/refactor: 走 standard,跨模块 feat: 或破坏性变更走 full。下表是文章初次发布时对 30 个已归档合同的快照,不代表当前工作区的实时数量:
| 模式 | 数量 | 特征 |
|---|---|---|
| standard | 19 | 单模块修复/重构,占主流 |
| full | 6 | 跨模块新功能,走完整四阶段(含 Issue triage、review、dogfooding checklist) |
| fast | 5 | 文档/杂项,跳过计划但不跳过测试与审查 |
这个分布本身就是证据:大部分真实改动落在中等复杂度,而流程没有为了图省事把执行验证和交付收尾也降级。即使是 fast 模式,Phase 3 仍执行实现、测试与按改动面触发的安全/回归检查,Phase 4 仍必须完成 Branch Finish。
契约测试与兼容性矩阵:把”平台差异”焊死
gf 同时封装 GitHub(gh)、GitLab(glab)、GitCode(gitcode)三套底层 CLI,最容易踩的坑是三个平台的 JSON 输出格式、错误语义各不相同,且会随版本漂移。docs/superpowers/plans/2026-07-31-contract-test-compatibility-matrix.md 记录了这套防线的落地过程:
- Fixture 契约测试:
crates/github/tests/fixtures、crates/gitlab/tests/fixtures、crates/gitcode/tests/fixtures下固化了真实 CLI 输出样本,反序列化逻辑对着这些 fixture 跑,CLI 输出字段一旦漂移,测试立刻红。 - 统一错误类型:
PlatformCliError(crates/core/src/cli_error.rs)把三份平台各自的错误类型收敛成一个,user_message/raw_stderr/hint/doc_link分离,原始 stderr 只进tracing::debug!,绝不直接回显给用户。 - 单一数据源的兼容性矩阵:
crates/core/resources/compatibility-matrix.json编译期通过include_str!嵌入gitflow-core,同时驱动prerequisites.rs的版本前置检查和docs/compatibility-matrix.md/ 官网兼容性页的生成——三处只维护一份数据,不会出现”文档写的版本和代码校验的版本不一致”。
这套机制不是纸面设计。当前已验证版本由兼容性数据源持续更新,官网兼容性页直接读取该数据;本文不再复制具体版本号,避免随上游 CLI 发布而失真。
dogfooding 反过来教会了流程什么
几点是从真实执行里长出来的经验,不是设计阶段就想到的:
- 交付证据要分场景,不能一刀切。 Gate 3→4 最初只认 PR URL,后来发现本地合并(
local_merge)场景下没有 PR,于是拆成pr_url/merge_commit二选一,闸门校验代码同步更新(gates.md)。 - 测试通过不等于远端检查通过。 Phase 3 的
tests_passed是本地前置自检,不是 CI 结论。PR 路径仍以平台必需检查和gf pr merge --auto的排队结果为准;本地合并路径则在 Phase 3 记录merge_commit。 - worktree 也会脏。 Phase 3 Step 1 的 Worktree Preflight(提交前先分类 A/B/C 三桶、绝不自动提交或删除)是在真实执行里撞见过”设计文档被落在主工作区、worktree 里找不到”之后加上的强制前置检查。
参考
- 四阶段编排规则:
skills/gf-workflow/SKILL.md - 门控定义:
skills/gf-workflow/gates.md - 契约测试与兼容性矩阵设计:
docs/superpowers/specs/2026-07-31-contract-test-compatibility-matrix-design.md - 全部 dogfooding 报告:
docs/dogfooding-report-*.md
本文原发布于 gf 官网(byx-darwin.github.io/gitflow-cli/dogfooding),如在掘金 / 知乎等平台转载,请在文首注明来源并保留指回此地址的 canonical link。