Reference

Claude Code branch workflow

One task, one agent branch, one pull request. Covered in lesson 6 and lesson 7.

The loop

Blue = main, orange = the agent branch. Nothing reaches main except through step 7.

Prompt templates

Following the Explore → Plan → Implement → Commit pattern from Claude Code's best practices.

# Explore (read only)
Read clean.py and test_clean.py. Explain how missing values are handled. Don't change anything yet.

# Plan
Plan how to add a standardize_columns() function with tests. List the files you'll touch.

# Implement (on the agent branch)
We're on branch add-standardize-columns. Implement the plan, run pytest, and fix failures.

# Commit + PR
Commit with a descriptive message and open a PR against main. Put "Closes #7" in the body.

Claude opens PRs with gh pr create, so install and log in to the gh CLI (docs). By default its commits carry a Co-Authored-By: … <noreply@anthropic.com> trailer and PR bodies say "🤖 Generated with Claude Code". Change this with the attribution setting (docs).

Before you merge

The PR is one logical change from one agent branch. Smaller PRs are easier to review and safer to squash.
You read the whole three-dot diff (git diff main...HEAD or the PR's Files changed tab), and every changed file is one you expected.
No secrets (.env, API keys) and no bulky data files were committed. "Never commit API keys or OAuth tokens directly to your repository" (docs).
The branch is up to date with main: after git fetch, git log --oneline HEAD..origin/main prints nothing. If it is a stale branch, merge origin/main into it and check again (lesson 11).
Tests pass locally, and every status check on the PR is green.
The PR description says what changed and why, and links the issue (Closes #N).
For a second opinion, use a fresh Claude session as reviewer: "A fresh context improves code review" (docs).

Recovery moves

Situation	Reach for
Claude's last few edits went wrong, still mid-session	`/rewind` (or `Esc` `Esc`) → restore code to a checkpoint. It does not undo Bash-made changes (docs).
One file has bad uncommitted edits	`git restore FILE`
The whole agent branch is a dead end	`git switch main` then `git branch -D NAME` (and `git push origin --delete NAME` if you pushed it)
A merge hit conflicts you don't want to handle now	`git merge --abort`
A bad PR is already merged into `main`	Revert the pull request on GitHub, which opens a new PR that undoes it (GitHub flow)
You deleted a PR's branch too soon	Restore branch on the PR page (docs)

Minimal CI workflow

Save as .github/workflows/ci.yml. It runs tests on every PR into main and on every push to main. The structure follows GitHub's Python tutorial, with action versions current as of October 2026.

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt
      - run: pytest

Gotchas

/branch branches the conversation, not git. Use git switch -c for a git branch (docs).
Checkpoints are not commits. They miss files changed by Bash commands (rm, mv, cp), and the docs call them "not a replacement for version control" (docs).
claude -w needs at least one commit in the repo, and by default it branches from the remote default branch, not your local HEAD (docs).
Add .claude/worktrees/ to .gitignore so worktree contents don't show up as untracked files (docs).
Branch protection and rulesets need a public repo on GitHub Free. Private repos need a paid plan (docs).
A workflow skipped by a branch or path filter leaves required checks "Pending", which blocks the merge (docs).
Closes #N only works when the PR targets the default branch (docs).
Commits pushed with the default GITHUB_TOKEN don't trigger workflows, for example from the @claude GitHub Action (docs).