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.

File	Size	Contains	Best for
CLAUDE.md.FULL	36,610 chars	All rules plus BAD/GOOD code examples	Teams that want rules plus concrete patterns — Claude follows rules-with-examples more reliably
CLAUDE.md.SHORT	26,435 chars	All rules, no code examples	Token-constrained setups, or projects that just need guardrails without inline samples

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.

What's inside (click to expand)

Area	Key rules
TypeScript	Strict mode, no any, discriminated unions, exhaustive switch guards
Components	Single responsibility, composition over configuration, stable list keys
State Management	Decision tree: SWR/Query → useState → Context → Zustand; never store derived state
Hooks	useEffect only for external sync, mandatory cleanup, async safety
Data Fetching	SWR/TanStack Query only, conditional fetching, typed wrapper hooks
Error Handling	Error boundaries at app/feature/list level, try/catch for async
Performance	Route-level code splitting, strategic React.memo, no premature optimization
Accessibility	Semantic HTML, ARIA labels, headless UI libraries, eslint-plugin-jsx-a11y
Security	No unsafe HTML, no tokens in localStorage, CSP headers
Testing	Integration tests for critical flows, role-based queries, Playwright E2E
Styling	Tailwind + cn(), CSS Modules, no runtime CSS-in-JS
Tooling	ESLint (6 plugins), Prettier, Husky, lint-staged
Project Structure	Feature-based layout, colocation, import cycle prevention
Build & Deployment	Env var safety, bundle budgets, source map policy, CI/CD guardrails
Large Projects	Dep management, dead code removal, incremental migration, monorepo rules

Both versions also include token-efficient output rules, a new-project setup checklist, an existing-project onboarding checklist, a pre-completion verification checklist, and a customizable Project-Specific Overrides section at the bottom.

Installation

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

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

How scope works

Placement	Effect
Project root	Applies to all work in the project
src/ subdirectory	Applies only when working in src/
Multiple levels	Rules stack — deeper files add to (or override) parent rules

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.

Example: Project-Specific Overrides

## 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

File	Description
docs/REACT_BEST_PRACTICES_GUIDE.md	~1,700-line tutorial covering each rule in depth with explanations, alternatives, and gotchas. For learning or onboarding — not meant to be loaded as CLAUDE.md.

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.

  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.

  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