LLM Best Practices

Claude Code Workflow

4 min read

View markdown source

Overview

This page is the operational layer for working with Claude Code day to day. The deeper pattern guide is 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.

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-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 multi-agent for the coordination patterns.

Use the GitHub MCP for PR operations

The 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 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.

claude-code expands each failure mode and fix.

Graph View

Backlinks