LLM Best Practices

Claude Code: Workflow Patterns

4 min read

View markdown source

Overview

Claude Code is at its best when given a complete written brief and clear acceptance criteria. It is at its worst when given a one-line ask and asked to interpret. These are the patterns that produce shippable work consistently.

The brief pattern

Write the brief in a chat session, paste it into Claude Code, let CC execute, then verify back in chat.

  1. Draft the brief in conversation with another Claude instance (or by hand). The brief includes mission, environment, phased steps, file paths, acceptance criteria, and explicit non-goals.
  2. Paste the brief into a Claude Code session. CC executes phase by phase.
  3. Verify the output: run the build, open the rendered output, check the acceptance criteria. Report back to the briefing session.

The split exists for a reason. The briefing session has cheap context: you can iterate on the brief without paying for tool calls. The CC session has expensive context: every tool call counts. Move expensive work to CC, cheap work to chat.

The anchor file pattern

Multi-session work needs files CC can re-read. Three files, all at the repo root.

  • CLAUDE.md: mission, schema, voice rules, folder structure, how to add to the project. CC reads this first on every session.
  • TODO.md: the open list of work, with checkboxes. CC updates it as items ship.
  • SESSION_LOG.md: dated entries describing what each session did and what was deferred.

These files are durable context. The chat history is not; it ages out. When a new session starts, CC reads the anchor files and is back to speed in seconds.

Acceptance criteria over vibes

Every brief ends with a checklist. Each item is verifiable.

## Acceptance criteria
- [ ] `npm run build` exits 0.
- [ ] Page `/foo/bar` renders with frontmatter title "Bar".
- [ ] `/llms.txt` is served at the site root.
- [ ] All 10 category MOCs render and link correctly.

“Looks good” is not a criterion. “Build is green” is. Write criteria that a script could check, even if no one will write that script.

Phase-and-verify structure

Break the work into numbered phases. After each phase, state what to verify before moving on.

## Phase 3 — Build the content tree
[steps...]
Verify: `find content -name "*.md" | wc -l` returns 65.

## Phase 4 — Configure routing
[steps...]
Verify: `curl localhost:8080/foo` returns 200.

CC works phase by phase. If a phase fails, you stop there instead of finishing a broken build and unwinding it.

When to specify file paths

Specify paths when the file already exists or when its location is load-bearing (config files, route files, schema files). Let CC choose paths for new files where the location is conventional and obvious (a new React component, a new test file).

Rule of thumb: if a path mistake would break the build or violate a framework convention, specify it. Otherwise let CC pick.

Voice and YAML conventions

CC writes in whatever voice the surrounding code uses. To get a consistent voice across sessions, write the rules into CLAUDE.md and reference them in the brief.

## Voice rules (apply to all written content)
- Neutral playbook voice. Lead with the rule.
- No em-dashes. Use periods or commas.
- No "It's not X, it's Y" construction.
- No slop preambles ("Let's dive in," etc.).

Same for YAML schemas. Pin the schema in CLAUDE.md; refer to it from the brief. CC will copy the schema field-for-field if it can see it.

Common failure modes

These are the ways CC commonly goes wrong. Each one has a fix.

  • Unscoped find-replace. CC runs a regex over the whole repo and breaks unrelated files. Fix: specify the file or directory in the brief; never write “rename X to Y” without a scope.
  • Over-editing existing files. CC opens a file to make one change and rewrites three other things along the way. Fix: explicitly tell it “only change the section between line A and line B” or “do not modify any other file.”
  • Inventing dependencies. CC adds a package that does not exist, or pins a version that does not match what is installed. Fix: pin the version in the brief, or tell CC to run npm ls <pkg> first and only proceed if it is already present.
  • Skipping verification. CC reports a phase complete without running the build. Fix: phase-and-verify; require the verification command in the brief.
  • Drifting voice mid-document. CC starts in playbook voice and slides into marketing voice by section three. Fix: put the voice rules in CLAUDE.md and call them out at the top of each writing brief.
  • Helpful refactors. CC notices an unrelated smell and “fixes” it. Fix: explicit non-goals in the brief. “Do not refactor X. Do not rename Y. Do not touch Z.”

Graph View

Backlinks