---
title: "Claude Code Workflow"
slug: "claude-code-workflow"
category: "tooling"
tags: ["tooling", "claude-code", "ai-agents", "workflow"]
status: "stable"
last_updated: 2026-05-14
summary: "Day-to-day Claude Code patterns: anchor files, the brief loop, phase-and-verify, subagent isolation, and the failure modes to watch."
related: ["[[ai-agents/claude-code]]", "[[prompt-engineering/prompt-design]]", "[[ai-agents/multi-agent]]", "[[tooling/github]]", "[[howto/set-up-claude-code]]"]
---

## Overview

This page is the operational layer for working with Claude Code day to day. The deeper pattern guide is [[ai-agents/claude-code]]; read it for the why. Read this page for the file layout, branch flow, and concrete commands that make CC productive on a repo you return to over weeks. For first-time install and authentication, see [[howto/set-up-claude-code]].

## Keep anchor files at the repo root

CC has no memory across sessions. Anchor files give it durable context.

- `CLAUDE.md`: mission, voice rules, schemas, folder map, "how to add a page" or "how to add a feature." CC reads this first every session.
- `TODO.md`: open work as a checkbox list. CC checks items as they ship and adds new ones it discovers.
- `SESSION_LOG.md`: dated entries describing what each session shipped and what was deferred. Append-only.

All three live at the repo root, never in a subfolder. CC finds root-level files by default; nested ones require explicit pointers.

## Write the brief in chat, execute in CC

Use two Claude surfaces for one task. The split saves tokens and improves quality.

1. Draft the brief in a chat session (Claude.ai or another lightweight surface). Iterate on phrasing, acceptance criteria, and non-goals there. Chat context is cheap.
2. Paste the finalized brief into Claude Code. CC executes the plan with tool calls. Tool-call context is expensive.
3. Report back in chat with the build output, the PR URL, or the failure trace. Iterate the brief if needed.

A brief includes: mission, environment, phased steps, file paths, acceptance criteria, and explicit non-goals. See [[prompt-engineering/prompt-design]] for the brief template.

## Structure work as phase-and-verify

Break the work into numbered phases. Each phase ends with a verification command.

```
## Phase 2: build the content tree
Steps:
- Create content/tooling/github.md with full frontmatter.
- ...
Verify: `find content/tooling -name "*.md" | wc -l` returns 5.

## Phase 3: run the build
Verify: `npx quartz build` exits 0.
```

CC works one phase at a time. If a phase fails, the session stops there instead of finishing a broken build and unwinding it later.

## Isolate parallel work in worktrees

Subagents share the working tree by default. Multiple subagents in one tree means conflicting edits.

- Set `isolation: "worktree"` on subagents that touch files. Each subagent gets a private git worktree at `.claude/worktrees/<id>/`.
- Use worktree isolation when running parallel content tasks, parallel refactors, or any job that writes to disk.
- Skip worktree isolation only for read-only research subagents.

The parent agent merges results by branch, not by file. See [[ai-agents/multi-agent]] for the coordination patterns.

## Use the GitHub MCP for PR operations

The [[ai-agents/mcp-servers|GitHub MCP server]] gives CC first-class PR tools. Prefer it over the `gh` CLI inside CC sessions.

- Create draft PRs with `mcp__github__create_pull_request`. Set `draft: true` until verification passes.
- Read PR diffs and comments with `mcp__github__pull_request_read`.
- Merge with `mcp__github__merge_pull_request` after CI is green. Squash merge by default, per [[tooling/github]].

CLI fallback (`gh pr create`) still works, but MCP avoids shell quoting issues with multi-line PR bodies.

## Watch the common failure modes

Most CC mistakes fall into a handful of patterns. Each has a guardrail.

- **Unscoped find-replace.** CC runs a regex repo-wide and breaks unrelated files. Fix: scope every rename to a directory or file list in the brief.
- **Over-editing.** CC changes one line and rewrites three others. Fix: explicit non-goals ("do not modify any other section").
- **Helpful refactors.** CC notices an unrelated smell and "improves" it. Fix: name the file or feature as out of scope.
- **Skipped verification.** CC reports a phase complete without running the build. Fix: require the verification command in the brief.
- **Drifting voice.** CC starts in playbook voice and slides into marketing voice. Fix: pin voice rules in `CLAUDE.md`.

[[ai-agents/claude-code]] expands each failure mode and fix.

## Related

- [[ai-agents/claude-code]]
- [[prompt-engineering/prompt-design]]
- [[ai-agents/multi-agent]]
- [[tooling/github]]