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>
2.9 KiB
2.9 KiB
03 — Git workflow
Small team, light process. Branches, commits, PRs, review.
Branches
mainis 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-Bytrailer 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
-uthe 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:
- Does the description match the diff? If the diff has surprises, ask.
- Read every file changed. If a file isn't related to the stated topic, ask why it's in the PR.
- Run the change locally if it's not obviously correct from reading.
- New deps, schema changes, env vars, or auth-touching code → block until justified.
- 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 --forcetomain. Period. To your own branch, only if nobody else has pulled it. - No
--no-verifyto 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 .orgit add -Awhen there are untracked files you don't recognize. Stage by name.