CLAUDE.md

CLAUDE.md is a configuration file that provides project-specific context and instructions to Claude Code and other Claude-based AI agents. Placed at the root of a project directory, it tells the agent how to work within that specific codebase.

Think of CLAUDE.md as project onboarding for AI:

• Explains the project structure
• Defines coding conventions
• Lists key commands
• Sets behavioral expectations

When Claude Code enters a directory with a CLAUDE.md file, it reads and follows those instructions throughout the session.

Consistency Without CLAUDE.md, you'd repeat the same context every session. With CLAUDE.md, project context is always available.

Team alignment Every team member's Claude Code sessions follow the same guidelines.

Reduced errors By specifying patterns and anti-patterns, CLAUDE.md helps the AI avoid common mistakes.

Faster onboarding New AI sessions start productive immediately—no warm-up period explaining project basics.

A well-structured CLAUDE.md includes:

• Overview: Tech stack and project description
• Key Commands: Common development commands
• Project Structure: Directory layout explanation
• Coding Conventions: Style and pattern preferences
• Things to Avoid: Anti-patterns and common mistakes
• Current Focus: What you're working on now

CLAUDE.md is specifically for Claude Code; SOUL.md defines who the agent is across all projects.

Be specific ❌ "Use good coding practices" ✅ "Use async/await instead of .then() chains"

Include examples Show actual code patterns you want followed.

List actual commands Document the commands you use frequently with explanations.

Note project quirks Document known issues and workarounds so the AI doesn't get confused.

Evolve over time Start minimal, add guidance as you discover edge cases, review periodically as the project changes.