Advanced CLAUDE.md Patterns

Beyond Basic Configuration

Most CLAUDE.md files are a handful of bullet points: "use TypeScript," "prefer functional components." That is Level 101 territory. A professional CLAUDE.md is a complete operating system that shapes how Claude thinks, reasons, and makes decisions in your codebase.

The key insight is that CLAUDE.md is not a suggestion box — it is an identity document. When you write "You are a Senior Full-Stack Developer specializing in Next.js App Router, React 19, and TypeScript," Claude adopts that persona and filters every response through it. This is called persona injection, and it dramatically improves output quality compared to generic instructions.

Start your CLAUDE.md with a clear identity block: who Claude is, what it specializes in, and how it communicates. Follow it with a product summary so Claude understands the business context behind every code decision.

Guardrails and Non-Negotiable Rules

Rules fall into two categories: preferences (nice-to-have) and non-negotiables (must always follow). The difference matters because Claude prioritizes explicit non-negotiable rules over general patterns.

Write your non-negotiables as a clearly labeled section with direct, imperative language:

• Never hardcode secrets, API keys, or credentials in source code
• Always use the @/ path alias for imports
• Never use the any type — use proper TypeScript interfaces
• All database queries must use parameterized statements — never string interpolation

The words "never," "always," and "must" signal to Claude that these rules have zero tolerance. Vague guidance like "try to avoid hardcoding secrets" gets ignored under pressure. Be absolute.

Team Conventions

Conventions eliminate the most common source of friction in AI-generated code: inconsistency. Define your naming conventions, git workflow, and code organization in explicit tables or lists:

• Components: PascalCase, one per file, under 150 lines
• Utility files: camelCase (db.ts, auth.ts)
• Database columns: snake_case (created_at, is_premium)
• Commits: type: short description (feat, fix, refactor, docs)

When Claude knows the exact format you expect, it produces code that passes review on the first attempt instead of requiring style corrections.

Architecture Decision Records

One of the most powerful sections in a professional CLAUDE.md is the Architecture Decisions block. This tells Claude not just what tools you use, but why you chose them and what patterns to follow.

For example, documenting "Database: sql.js (SQLite WASM in-memory) — zero-infrastructure development" tells Claude to never suggest installing PostgreSQL or MongoDB. Documenting "Auth: JWT + bcrypt — stateless auth with cookie storage" prevents Claude from recommending session-based auth or third-party providers.

Include your tech stack decisions, the patterns you follow (singleton initialization, wrapper classes, server-first components), and any known tradeoffs. This context prevents Claude from constantly suggesting alternatives to decisions you have already made.

Retrieval Maps

As your project grows, Claude needs to know where to look for specific information. A retrieval map is a lookup table that matches questions to file locations:

• "What am I working on?" → Check memory.md
• "How do I do this procedure?" → Check .claude/commands/
• "What went wrong before?" → Check knowledge-base.md
• "What happened on a specific day?" → Check daily notes archive

Without a retrieval map, Claude guesses where to find context. With one, it goes directly to the right file every time. This is the difference between a tool that searches randomly and a colleague who knows the codebase.

Practical Exercise