React-with-AI

A CLAUDE.md template that teaches Claude Code modern React best practices. Drop it into any React project and Claude will follow production-grade conventions for TypeScript, state management, accessibility, security, testing, and more — automatically, on every interaction.

Why

Claude Code reads CLAUDE.md from your working directory and applies its rules to every conversation (including sub-agents). Without guardrails, AI-generated React code can drift: any types, raw useEffect data fetching, missing error boundaries, inaccessible markup, tokens in localStorage, and more. This template codifies the conventions experienced React teams enforce in code review, so Claude follows them from the first line.

Two Versions

Pick the one that fits your project.

Both files cover the same rules — the only difference is whether each rule is illustrated with a BAD/GOOD code block. SHORT is ~28% smaller because it strips all fenced code blocks while preserving every rule, table, and checklist.

Installation

1. Download the version you want into your React project root:

   hljs language-bash

   Copy

   # FULL (with code examples)
   curl -o CLAUDE.md https://raw.githubusercontent.com/maxart/React-with-AI/main/CLAUDE.md.FULL
   
   # Or SHORT (rules only)
   curl -o CLAUDE.md https://raw.githubusercontent.com/maxart/React-with-AI/main/CLAUDE.md.SHORT
   

   The curl commands above already rename the file to CLAUDE.md — if you download manually, rename it yourself.

2. Customize the Project-Specific Overrides section at the bottom of CLAUDE.md with your stack details — state management choice, styling approach, API conventions, testing thresholds, deployment rules.

Claude Code picks it up automatically on every conversation. No slash commands, no configuration.

How It Works

your-react-project/
  CLAUDE.md          <-- Claude reads this automatically
  src/
  package.json

Claude Code loads CLAUDE.md from the working directory (and parent directories) at the start of every conversation. The instructions become part of Claude's system context and apply to the main agent and all sub-agents.

Customization

The template is a starting point, not a straitjacket.

• Remove rules that conflict with your project (e.g., delete the Tailwind section if you use CSS Modules).
• Add project-specific rules anywhere — API conventions, git strategy, design system usage, feature flag patterns.
• Override defaults in the Project-Specific Overrides block at the bottom.

Rules with code examples (FULL version) are followed more reliably than abstract guidelines. If Claude keeps missing a rule, make it more specific or add an example.

## Project-Specific Overrides

### State Management
- This project uses Zustand for global state
- Server state uses TanStack Query with 10-minute staleTime

### Styling
- CSS Modules, not Tailwind
- Class names follow BEM convention

### API
- All API calls go through src/api/client.ts
- Use the createDataHook factory for new endpoints

### Testing
- Minimum 80% coverage on new code
- E2E tests required for all user-facing flows

Companion File

Compatibility

• Claude Code: CLI, desktop app, web app, IDE extensions (VS Code, JetBrains)
• React: 18.x and 19.x
• TypeScript: 5.x
• Build tools: Vite, Next.js, Remix, any bundler
• Styling: Tailwind, CSS Modules, or any approach

FAQ

Which version should I pick? Start with FULL if you're unsure. The BAD/GOOD examples make Claude more consistent at applying each rule, especially on unfamiliar patterns. Switch to SHORT if context size matters (large monorepo, heavy sub-agent use) or once your team has settled on conventions and Claude reliably follows them.

Does this work with Next.js or Remix? Yes. Rules are React-focused and framework-agnostic. Add framework-specific rules (server components, loaders, route conventions) to the overrides section.

Will this slow Claude down? No. CLAUDE.md is loaded once per conversation and is negligible in the context window.

Can I use this with other AI coding tools? The file targets Claude Code, but the content is standard React best practices and portable to other agents:

• Agents that read AGENTS.md (Codex, OpenCode, and others adopting that convention): download it directly as AGENTS.md.

  hljs language-bash

  Copy

  curl -o AGENTS.md https://raw.githubusercontent.com/maxart/React-with-AI/main/CLAUDE.md.FULL
  

• Both Claude Code and an AGENTS.md-based agent in the same repo: save the file as AGENTS.md, then create a one-line CLAUDE.md that imports it. Claude Code expands @path imports into context at session start, so both tools read identical instructions from a single source — no duplication, no drift.

  hljs language-bash

  Copy

  curl -o AGENTS.md https://raw.githubusercontent.com/maxart/React-with-AI/main/CLAUDE.md.FULL
  echo '@AGENTS.md' > CLAUDE.md
  

• Cursor, Windsurf, Copilot: adapt the rules into .cursor/rules/, .windsurfrules, or .github/copilot-instructions.md.

Claude is ignoring a rule. CLAUDE.md is high-priority but not absolute. If a rule is consistently ignored, make it more specific or add an example. Rules with code examples are followed more reliably — the main reason to prefer FULL over SHORT.

Further Reading

• Bulletproof React — reference architecture for production React apps
• React docs: You Might Not Need an Effect — when to reach for useEffect and when not to
• TanStack Query docs — authoritative data-fetching patterns
• Testing Library docs — query priority and best practices
• claude-token-efficient — the rules behind our "Output and Efficiency" section

License

MIT