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

91 lines
2.9 KiB
Markdown

# 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 <commit>".
- 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.