Agent Ready Academy
Module 3: CLAUDE.md — Your Agent's Playbook

Annotated CLAUDE.md Patterns

Composite annotated examples showing effective CLAUDE.md patterns

~15 min readIncludes code

Overview

Theory is valuable, but seeing annotated CLAUDE.md files is where the concepts click. In this lesson, we walk through four annotated examples -- a Python API, a React web application, a Go CLI tool, and a monorepo. These are composite illustrations designed to demonstrate the patterns and principles from the previous lessons. They are not extracted from specific repositories, but each reflects conventions commonly found in production codebases of that type.

For each example, we highlight what makes it effective, why specific instructions are included, and patterns you can borrow for your own projects.

Pattern 1: Python API (FastAPI)

This example shows a CLAUDE.md for a production FastAPI backend with PostgreSQL, Alembic migrations, and a service-layer architecture.

CLAUDE.md

What makes this effective:

  • Multiple test commands with different scopes -- the agent can run fast unit tests during iteration and the full suite for final verification
  • Explicit Python version -- tells the agent to use modern syntax features
  • Architecture with data flow -- one line (Route → Service → Repository → Database) conveys the entire request lifecycle
  • Database section -- migration workflows are a common source of agent mistakes; documenting them prevents errors
  • Dependency guard -- "Do NOT add dependencies without mentioning it" prevents surprise additions in PRs

Pattern 2: React Web Application (Next.js)

This example shows a CLAUDE.md for a Next.js 14 application with App Router, Tailwind CSS, and a component library.

CLAUDE.md

What makes this effective:

  • Component guidelines section clearly separates Server vs Client component rules -- this is the most common source of Next.js agent errors
  • Data fetching rules prevent the agent from falling back to familiar patterns (fetch, React Query) that do not fit this architecture
  • "Do NOT create API route handlers" -- a strong, specific prohibition that prevents the agent from defaulting to a common Next.js pattern the team has deliberately rejected
  • Build vs tsc distinction -- explaining why pnpm build is required instead of just type-checking catches subtle issues

Pattern 3: Go CLI Tool

This example shows a CLAUDE.md for a Go CLI application built with Cobra, with a focus on the Go-specific conventions that agents sometimes get wrong.

CLAUDE.md

What makes this effective:

  • Go-specific patterns like error wrapping with %w, interface placement, and table-driven tests address the most common Go mistakes agents make
  • Step-by-step for adding commands -- Cobra commands follow a specific pattern, and spelling it out prevents structural mistakes
  • Explicit stdlib preference for logging -- without this, agents often reach for logrus or zap
  • internal/ vs pkg/ distinction -- a Go-specific convention that agents sometimes violate

Pattern 4: Monorepo

This example shows the root CLAUDE.md for a TypeScript monorepo using Turborepo, alongside one package-level CLAUDE.md.

CLAUDE.md

And the package-level CLAUDE.md for the API:

apps/api/CLAUDE.md

What makes this effective:

  • Clear separation between root-level and package-level concerns
  • Root CLAUDE.md focuses on monorepo-wide rules: cross-package imports, build orchestration, and dependency management
  • Package CLAUDE.md provides the specific tooling, architecture, and conventions for that package alone
  • --filter syntax documented in the root so agents know how to build a single package
  • Package names (@myorg/api, @myorg/types) used consistently so agents use the correct import paths

Comparing the Patterns

Let us look at what these four examples have in common and where they differ:

Two groups of CLAUDE.md patterns: Shared across all patterns — build and test commands listed first, language-specific code style rules, architecture section with directory explanations, explicit 'Do NOT' rules for known failure modes, and dependency management policy. Varies by project type — framework-specific patterns (Cobra commands, Server Components, migration workflows), data layer conventions (ORM choice, query patterns), and testing scope commands (single file, single package, single pattern).

Every effective CLAUDE.md, regardless of language or framework, shares these traits:

  • Commands first -- the agent's verification loop depends on knowing the right commands
  • Language-idiomatic style rules -- not generic advice but specific patterns for the language
  • Explicit prohibitions -- preventing known agent mistakes is more reliable than hoping for correct defaults
  • Dependency awareness -- agents frequently try to install packages; a policy prevents surprise additions

Patterns to Borrow

Here is a reference table of reusable patterns you can adapt for your own CLAUDE.md:

PatternExampleWhy It Works
Scoped test commandspytest tests/unit/Lets the agent iterate fast on focused tests
Step-by-step for adding features"1. Create file. 2. Register it. 3. Add test."Prevents structural mistakes in repetitive tasks
Framework-specific prohibitions"Do NOT use useEffect for data fetching"Prevents falling back to familiar but wrong patterns
Explicit stdlib preferences"Use log/slog, not logrus"Prevents unnecessary dependency additions
Migration workflow"Create with X. Never edit existing."Prevents database-breaking changes
Response pattern enforcement"Use sendSuccess(), not res.json()"Ensures consistency across the codebase
Dependency policy"Do NOT add deps without discussion"Keeps the dependency tree intentional

Building Your Own CLAUDE.md

After seeing these examples, here is a practical approach to building your own:

  1. Start with the template -- Copy the build/test/lint commands section from whichever example most closely matches your project
  2. Add your language's gotchas -- What mistakes do developers new to your codebase make in the first week? Those are your "Do NOT" rules
  3. Document the architecture -- List the top-level directories with one-line descriptions and the data flow pattern
  4. Run an agent session -- Use the CLAUDE.md in a real task. Note where the agent stumbles
  5. Iterate -- Add missing context after each session. Remove instructions that proved unnecessary

Remember: The best CLAUDE.md is one that evolves with your project. The four examples above were not written in one sitting -- they grew through dozens of agent sessions, each one surfacing a missing instruction or an unnecessary rule.

Summary

  • Real-world CLAUDE.md files share common patterns: commands first, language-specific style rules, architecture maps, and explicit prohibitions
  • Python APIs benefit from documenting migration workflows, the service-layer pattern, and typing requirements
  • React apps need clear Server vs Client component rules, data fetching conventions, and component organization guidelines
  • Go CLIs should document error handling patterns, interface placement, and step-by-step instructions for adding commands
  • Monorepos use nested CLAUDE.md files: root for cross-package rules, subdirectories for package-specific conventions
  • Build your own CLAUDE.md by starting with commands, adding language gotchas, mapping the architecture, and iterating through real agent sessions