Files
praxis/docs/03-git-workflow.md
T
阿白叔andClaude Opus 4.7 7f9ca07903 init: scaffold team-guide v0.1
Working agreements for our 1-3 person AI-assisted team. Six docs
(vibe coding, Claude Code, git workflow, skills/planning, code style,
handoff) plus four templates (CLAUDE.md, README, PR description,
handoff checklist).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 09:02:21 +08:00

2.9 KiB

03 — Git workflow

Small team, light process. Branches, commits, PRs, review.

Branches

  • main is always shippable. No direct pushes. No exceptions.
  • Feature branches: <owner>/<short-slug> — e.g. bai/auth-retry, bai/eval-agent-rerun. Lowercase, hyphens, your handle as prefix.
  • Long-lived integration branches: integration/<topic> — only with team agreement.
  • Delete branches after merge. Old branches confuse search.

Commits

Format:

<area>: <imperative summary under 60 chars>

<optional body — what changed and why, not how>
  • <area> is a directory or component, lowercase: eval-agent, task_assistant, docs, git-workflow.
  • Imperative: "add", "fix", "rename" — not "added" / "adding".
  • Body wraps at ~72 chars. Skip it for trivial commits.
  • One topic per commit. "and" in the summary means split it.
  • AI-assisted commits get the Co-Authored-By trailer Claude Code adds by default. Don't strip it.

Examples:

eval-agent: rerun failed tasks with stable seed
docs: clarify branch naming in git-workflow
task_assistant: drop unused legacy export path

Pull requests

  • One PR per topic. If you can't describe it in one sentence, it's multiple PRs.
  • Title under 70 chars, same shape as a commit summary.
  • Description uses templates/PR_DESCRIPTION.template.md.
  • Push to your feature branch with -u the first time so it tracks remote.
  • Open the PR as soon as you have something runnable, even if it's a draft. Review-as-you-go beats review-at-the-end.

Review

We review every PR before merge, even our own AI-assisted ones.

Reviewer checks:

  1. Does the description match the diff? If the diff has surprises, ask.
  2. Read every file changed. If a file isn't related to the stated topic, ask why it's in the PR.
  3. Run the change locally if it's not obviously correct from reading.
  4. New deps, schema changes, env vars, or auth-touching code → block until justified.
  5. Comment on the least important issue first; save the merge-blocker for last so it's clearly the gate.

Author follow-ups:

  • Address every comment, even with "agreed, fixed in ".
  • If you disagree, push back in writing. Don't silently ignore.
  • Squash fixup commits before merge if the history is noisy.

Merging

  • Squash for feature branches. Merge commits are reserved for integration branches.
  • Final squash message follows the commit format above. The PR title is usually the right starting point.
  • Delete the branch on merge.

What NOT to do

  • No git push --force to main. Period. To your own branch, only if nobody else has pulled it.
  • No --no-verify to skip hooks. Fix what the hook is complaining about.
  • No amending pushed commits. Once it's on the remote, add a new commit.
  • No committing .env, credentials, or files larger than ~5 MB without a Git LFS conversation first.
  • No staging with git add . or git add -A when there are untracked files you don't recognize. Stage by name.