How to Set Up a CLAUDE.md File for AI Assistant Instructions

Step by step

1. Create the CLAUDE.md file in your project root

   Navigate to your project's root directory and create a new file named CLAUDE.md. Place it at the same level as your README.md, package.json, or other top-level project files. This location ensures Claude can easily reference it when analyzing your project structure.

   Note: Use all caps for CLAUDE.md to make it easily distinguishable from other markdown files and ensure it appears near the top in alphabetical file listings.

2. Define your project context and overview

   Start the file with a clear project description, technology stack, and purpose. Include the programming languages, frameworks, databases, and key dependencies. Specify whether it's a web app, mobile app, CLI tool, or library. This section should give Claude immediate understanding of what you're building.

   Note: Include version numbers for major dependencies and frameworks, as Claude's responses can vary significantly based on different versions' APIs and best practices.

3. Specify your coding standards and preferences

   Document your preferred coding style, naming conventions, file organization patterns, and architectural decisions. Include details like whether you use TypeScript or JavaScript, your preferred state management approach, CSS methodology, or testing frameworks. Be specific about formatting preferences, such as semicolons, quotes, and indentation.

   Note: Reference existing configuration files like .eslintrc, prettier.config.js, or tsconfig.json to avoid duplicating rules that are already defined in your project.

4. Document your file structure and important directories

   Provide a clear overview of your project's directory structure and the purpose of key folders. Explain where components, utilities, tests, and configuration files are located. Include information about any custom organizational patterns or monorepo structures you're using.

   Note: Use a tree structure or bulleted list format to make the directory layout immediately scannable for Claude when it needs to understand file relationships.

5. Include development workflow and environment details

   Specify how to run the project locally, including installation commands, environment variables, and development scripts. Document your testing approach, build process, and deployment procedures. Include any special setup requirements or external services the project depends on.

   Note: Add common troubleshooting steps or gotchas that new developers typically encounter when setting up the project.

6. Add specific instructions for Claude interactions

   Include a section with direct instructions for how you want Claude to behave when working on this project. Specify whether you prefer detailed explanations or concise code, how to handle error scenarios, and any particular communication style preferences. Define what level of context to assume about your technical knowledge.

   Note: Use imperative language like 'Always include TypeScript types' or 'Explain breaking changes when suggesting library updates' to give Claude clear, actionable guidelines.

7. Reference the CLAUDE.md file in your conversations

   When starting new conversations with Claude, mention that there's a CLAUDE.md file in your project and ask Claude to read it for context. You can simply say 'Please review the CLAUDE.md file for project context' or reference specific sections when asking questions about particular aspects of your project.

   Note: Update the CLAUDE.md file as your project evolves and remind Claude to re-read it when you've made significant changes to project structure or requirements.