Skip to content

Team Workflow

Jump to bottom
Lex edited this page Aug 21, 2026 · 3 revisions

Team Workflow

Everything works identically for one person or twenty. What changes on a team is coordination: whose policy is authoritative, how a delivery maps onto branches and PRs, and what review actually reviews.

One delivery = one branch + N issues + one PR + required checks

That aggregate is the team's unit of work and the unit of acceptance:

  • Branch or worktree. The delivery happens on one branch; parallel checkouts (worktrees) on that branch are equivalent. No delivery ever spans branches.
  • Issues. Everything the delivery is "for" is an issue number in the record. The issues carry intent and scope; SpecGit only verifies they exist and are closed by the PR.
  • One PR. The delivery merges through exactly one pull request. Its body's closing references are the contractual link back to the issues.
  • Required checks. The policy is the shared definition of "CI passed" — enforced by branch protection and by SpecGit identically.

The policy is the team contract

spec_git/policy.yaml is committed on the default branch and reviewed like code:

  • Adding a required check (say, a new security scan) is a PR that changes the policy and the branch-protection settings together.
  • Removing a required check is equally deliberate — SpecGit fails closed on an empty list, so nobody can silently turn acceptance into a no-op.

The delivery loop

issue(s) filed ──► specgit issue (branch + draft PR + record) ──► commits ──► push
                                                                                  │
      specgit finish ◄── closing refs + green checks ◄────────────────────────────┘
            │
            ├── accepted ──► merge ──► specgit unbind (or delete .specgit.yaml)
            ├── rejected ──► fix what the gates named, re-run finish
            └── unknown  ──► fix record/policy/auth, re-run finish

The record .specgit.yaml is committed on the delivery branch, so the binding travels with the work: anyone who checks the branch out can run specgit status and specgit finish and get the same verdict.

PR flow specifics

  • A draft PR always fails the verdict (pr_draft): before specgit finish, mark it ready — gh pr ready <number> on GitHub, glab mr update <number> --ready on GitLab.
  • Keep the Closes #n references in the PR body intact; after changing the PR body, head branch, or CI, re-run specgit finish.
  • The CI gate .github/workflows/specgit-accept.yml runs specgit finish --json on every PR.
  • specgit finish exit 0 is the only "done" — never request merge on any other exit. Fix the delivery, not the gate.

What review reviews

Acceptance answers "is the delivery complete and verified?" Review answers "should this delivery exist at all?" Reviewers look at:

  1. The linked issues (from the record's issues) — is this the right scope?
  2. The diff — the usual engineering review.
  3. The binding itself — does the PR really close those issues? Is the context branch the one being reviewed?

Conventions that work well

  • Branch naming. <type>/<issue>-<slug> (e.g. fix/124-flaky-tests) keeps the context self-describing and matches worktree labels.
  • Bind early, complete later. A record with issues but no PR is a valid draft; binding early makes the delivery discoverable.
  • Re-run finish after every CI run. The verdict is a fact about now.
  • Delete the record after merge. specgit unbind --yes keeps merged branches clean.

团队工作流

一个人用和二十个人用没有区别。团队里变化的是协作方式：谁的策略是权威的、交付如何映射到分支和 PR、评审到底在评审什么。

一次交付 = 一个分支 + N 个 issue + 一个 PR + 必需检查

这个聚合体就是团队的工作单元和验收单元：

  • 分支或 worktree。 交付发生在一个分支上；该分支上的并行检出（worktree）等价。交付永不跨分支。
  • Issues。 交付"为了什么"都体现为记录里的 issue 编号。issue 承载意图和范围；SpecGit 只验证它们存在且被 PR 关闭。
  • 一个 PR。 交付通过恰好一个 pull request 合并。PR 正文中的关闭引用就是回到 issue 的契约性链接。
  • 必需检查。 策略是"CI 通过"的共同定义 —— 由分支保护和 SpecGit 同样地执行。

策略即团队契约

spec_git/policy.yaml 提交在默认分支上，像代码一样评审：

  • 新增一个必需检查（比如新的安全扫描）是一个同时修改策略和分支保护设置的 PR。
  • 删除必需检查同样慎重 —— SpecGit 对空列表 fail-closed，没人能悄悄把验收变成空操作。

交付循环

提交 issue ──► specgit issue（分支 + draft PR + 记录）──► commits ──► push
                                                                        │
    specgit finish ◄── 关闭引用 + 检查全绿 ◄─────────────────────────────┘
          │
          ├── accepted ──► 合并 ──► specgit unbind（或删除 .specgit.yaml）
          ├── rejected ──► 按门禁指出的问题修复，重跑 finish
          └── unknown  ──► 修复记录/策略/认证，重跑 finish

记录文件 .specgit.yaml 提交在交付分支上，绑定随工作走：任何人检出该分支都能运行 specgit status 和 specgit finish，得到相同结论。

PR 流程要点

  • Draft PR 必然验收失败（pr_draft）：运行 specgit finish 前先标记 ready —— GitHub 用 gh pr ready <number>，GitLab 用 glab mr update <number> --ready。
  • 保持 PR 正文中 Closes #n 引用完整；修改 PR 正文、head 分支或 CI 后，重跑 specgit finish。
  • CI 门禁 .github/workflows/specgit-accept.yml 会在每个 PR 上运行 specgit finish --json。
  • specgit finish 退出码 0 是唯一的"完成" —— 任何其他退出码都不要请求合并。修交付，别修门禁。

评审在评审什么

验收回答"交付是否完成且已验证？"，评审回答"这个交付该不该存在？"。评审者看三件事：

  1. 关联的 issues（来自记录的 issues）—— 范围对不对？
  2. diff —— 常规的代码评审。
  3. 绑定本身 —— PR 真的关闭了那些 issue 吗？被评审的就是上下文分支吗？

好用的惯例

  • 分支命名。 <type>/<issue>-<slug>（如 fix/124-flaky-tests）让上下文自描述，且与 worktree 标签一致。
  • 早绑定，后补全。 有 issues 没 PR 的记录是合法的 draft；早绑定让交付可被检索到。
  • 每次 CI 跑完重跑 finish。 结论是关于当下的事实。
  • 合并后删除记录。 specgit unbind --yes 让滞留的已合并分支保持干净。

SpecGit Wiki

中文

Repository documentation

Clone this wiki locally