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>
91 lines
2.9 KiB
Markdown
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.
|