Contents
- 01Know What You Are Operating
- 02Orient to an Existing Project
- 03Turn Intent Into a Build Specification
- 04Make Project Context Durable
- 05Bound Permissions and the Sandbox
- 06Make Changes With Git and Worktrees
- 07Debug and Verify the Result
- 08Extend With MCP, Skills, and Hooks
- 09Delegate and Run Work in Parallel
- 10Operate in CI and Ship the Capstone
Make Changes With Git and Worktrees
Use Git history, branches, diffs, checkpoints, and worktrees to keep agent-generated changes inspectable, isolated, and recoverable.
By the end
A complete safe-change loop: preserve the starting state, isolate the task, review the diff, verify behavior, create a coherent commit, and integrate deliberately.
Git is the change ledger
Git records snapshots and relationships between changes in a repository. GitHub or another host shares that history and adds collaboration features, but the local Git state exists before anything is pushed. Claude Code can operate Git for you, yet you still need to read the essential signals: current branch, changed files, diff, staged content, and recent commits.
Begin every change by capturing the starting state. A dirty file is not automatically safe to discard because it is uncommitted. It may contain valuable work from you, another tool, or an interrupted task. Tell Claude explicitly to preserve unrelated changes and avoid reset, restore, bulk formatting, or broad staging unless you have inspected the targets.
Branches separate history
A branch gives a line of work a name and a place in history, but ordinary branches still share one working directory if you switch between them. Use a new branch when one task needs its own commits and review. Keep the branch focused enough that its diff tells one coherent story.
Do not create branches as a substitute for understanding the checkout. Confirm the base branch and whether it is current, then record the relationship the task expects. A feature based on an old local branch can be internally correct and still conflict with the current shared system.
Worktrees separate working directories
A Git worktree gives another branch its own directory while sharing the repository's object history. This is useful for parallel Claude Code sessions because each worker can edit an isolated checkout instead of racing over the same files. Claude Code currently supports starting a worktree session with `--worktree` or `-w`, and custom subagents can request worktree isolation.
A worktree is a fresh checkout, not a copy of every untracked or ignored local file. Dependencies, local databases, caches, and `.env` files may need safe initialization. Anthropic documents `.worktreeinclude` for selected gitignored files, but copying secrets into more directories increases exposure. Prefer a controlled setup process and scoped credentials.
The diff is the review surface
A diff shows what changed relative to a reference. Review its scope before its details: which files changed, whether generated artifacts or lockfiles are expected, and whether unrelated formatting obscures the behavior. Then inspect the actual additions and removals, connect each hunk to an acceptance criterion, and ask why every new dependency or configuration change is necessary.
A green test does not make an unexplained diff acceptable. Tests cover selected behavior; the diff reveals authority expansion, secret exposure, deleted safeguards, and accidental cleanup. Conversely, a clean-looking diff is not behavioral proof. Reliable review needs both source inspection and executed checks.
Checkpoints, commits, and integration
Claude Code checkpoints can rewind conversation and file edits made through its editing tools. They are valuable for experimentation, but Anthropic explicitly notes that they do not capture every change made by Bash or external processes and are not a replacement for Git. Git commits remain the portable, reviewable history shared with a team.
Commit only after the diff and verification form one coherent unit. Stage explicit files, inspect the staged diff, and write a message that describes the outcome rather than the tool used. Pushing, opening a pull request, merging, deleting a branch, and removing a worktree are separate actions with separate consequences. Do not bundle them into an implied `finish` command.
Working reference
Commands and patterns
Capture and review current changes
git status --short git diff --stat git diff
Use the summary to understand scope, then inspect the actual unstaged diff before asking Claude to add or replace work.
Create an isolated Claude Code worktree
claude --worktree feature-request-intake
Starts Claude Code in a new worktree and branch managed by Claude Code. Confirm the base and initialize only the dependencies and local configuration the task needs.
Inspect worktrees and staged content
git worktree list git diff --cached --stat git diff --cached
List active checkouts and review exactly what a commit would contain after staging explicit files.
Create a manual worktree when needed
git worktree add ../project-feature-a -b feature-a cd ../project-feature-a claude
The documented Git-based alternative gives explicit control over branch name and directory. Validate the target path before creation.
When the happy path breaks
Failure modes
Symptom
Unrelated edits appear in the task's commit or disappear from the checkout.
Likely cause
Claude staged all files, reformatted broadly, or cleaned a dirty worktree without ownership boundaries.
Recovery
Stop, inspect reflog or backups if recovery is needed, restore only proven targets, and stage explicit task files after a fresh diff review.
Symptom
Two agent sessions repeatedly overwrite or invalidate each other's work.
Likely cause
They share one working directory or edit overlapping files without an integration owner.
Recovery
Use separate worktrees for independent lanes, declare file ownership and dependencies, and integrate through reviewed commits in a controlled order.
Symptom
Rewind restores some files but the project still behaves differently.
Likely cause
Checkpointing was treated as complete version control even though Bash, dependency, database, or external changes were outside its snapshot.
Recovery
Inspect Git, generated files, dependencies, data migrations, and external side effects separately; use commits and explicit rollback procedures for durable recovery.
Symptom
A worktree does not start because dependencies or local configuration are missing.
Likely cause
The isolated checkout was assumed to inherit ignored files, installed packages, caches, or environment state from the main directory.
Recovery
Run the project's documented setup in the worktree and supply only the minimum local configuration through a safe, repeatable process.
Hands-on lab
Complete a safe change in an isolated worktree
Make one small behavior change while preserving an already-dirty main checkout and producing a reviewable commit with verification evidence.
- 01Record the main checkout's path, branch, status, and existing uncommitted files.
- 02Create a named Claude Code worktree for the task and confirm its branch and base commit.
- 03Initialize only the dependencies and local settings required to run the targeted check.
- 04Give Claude the accepted task specification and require a plan before edits.
- 05After implementation, inspect `git status`, the diff stat, and every diff hunk.
- 06Run the targeted verification and one broader check appropriate to the project.
- 07Stage explicit files, review the cached diff, and create one outcome-focused commit.
- 08Return to the main checkout and prove its pre-existing dirty files are unchanged.
Deliverable: An isolated branch containing one coherent commit, a preserved main checkout, and a receipt linking the specification, diff, verification output, and integration status.
Reusable artifact
Safe-change receipt
A review record that ties repository state, isolation, changed files, checks, and integration actions to one outcome.
Task: [outcome and specification link] Repository: [root + remote] Main checkout preserved: [path + branch + dirty files] Task worktree: [path + branch + base commit] Files changed: [explicit list + purpose] Diff reviewed: [reviewer + date + notable risks] Checks run: [exact commands + exit/result] Commit: [hash + message] Push/PR status: [not performed / URL + version] Integration owner: [person or lane] Rollback: [revert commit / restore data / other steps] Remaining uncertainty: [known gap]
Before you move on
Receipt checklist
- The task ran in an isolated branch or worktree with a recorded base commit.
- The main checkout's pre-existing changes remain byte-for-byte or diff-equivalent intact.
- Every changed file is tied to the accepted scope and reviewed in the diff.
- Targeted and broader verification results are recorded with exact commands.
- Commit, push, pull request, merge, and cleanup statuses are reported separately.
Primary sources
