CLAUDE.md: The Complete Setup Guide for Claude Code Projects

Summary

Use this guide to set up CLAUDE.md correctly once, so Claude Code starts every session with the right context.

Execution paths from this guide

Move from reading to action: validate by task intent, compare alternatives, then open tool reviews for final checks.

Browse by task • Compare • Tools • Deals

Priority tasks: Content writing tasks • Code generation tasks • Video generation tasks • Meeting notes tasks

Priority tool reviews: ChatGPT review • Claude review • Perplexity review • Gemini review

What CLAUDE.md actually does

CLAUDE.md is persistent project context that Claude Code reads automatically when work starts in a repository. That makes it different from ad hoc prompts, which disappear after the conversation and rely on the next user remembering to restate the same constraints. A good CLAUDE.md reduces drift by giving the agent stable instructions about project intent, command conventions, and quality bars before it takes action. The practical result is less repeated setup, fewer avoidable mistakes, and better first-pass behavior across sessions.

The three-layer hierarchy

Claude Code setups usually become easier to manage once you separate global, project, and subdirectory guidance. A global file in your home directory should hold personal defaults, editor habits, and cross-project preferences that do not belong in version control. The project-root CLAUDE.md should capture shared team rules such as build commands, architecture boundaries, and review expectations. Subdirectory-level CLAUDE.md files are best reserved for places where the local rules genuinely differ, such as a generated-code area, a docs folder, or a deployment subtree with separate constraints.

What to put in CLAUDE.md

The highest-value content is operational context: what the product is, how the repository is organized, and which commands are safe and normal to run. Include coding conventions, validation commands, important paths, and the boundaries that should not be crossed without explicit review. If the team already has recurring workflows such as release QA, schema changes, or content audits, summarize the rules and point to the relevant docs instead of embedding huge manuals. Think of the file as a compact operating brief that helps an agent make better decisions under uncertainty.

What NOT to put in CLAUDE.md

Never store secrets, personal tokens, or anything you would not want committed to source control or echoed in a prompt. Avoid unstable details such as temporary branch names, daily to-do lists, or fast-changing operational data that will go stale and quietly mislead future sessions. Do not turn the file into a dumping ground for full architecture docs, onboarding manuals, or raw meeting notes, because long files dilute the signal and increase token cost every time they are read. If a detail changes often or requires nuance, reference a source document instead of duplicating it in CLAUDE.md.

Skill routing in CLAUDE.md

Skill routing rules are one of the highest-leverage uses of CLAUDE.md because they convert vague intent into repeatable workflows. Instead of hoping the agent remembers when to run a QA loop, SEO audit, or deployment checklist, define the trigger conditions directly in the file. Good routing language names the task shape, the correct skill, and the situations where the skill should not be used. That structure keeps automation predictable and makes it easier for new contributors to understand why Claude Code chose a given workflow.

Team CLAUDE.md vs personal CLAUDE.md

Team context and personal preferences should not fight for the same file. Shared project instructions belong in the repository so every contributor and every session starts from the same operational baseline. Personal productivity habits, shell preferences, or private helper rules belong in a global user-level CLAUDE.md so they do not leak into team policy. This split keeps the repo trustworthy for collaborators while still letting each developer tailor how Claude Code behaves in their own environment.

Frequently asked questions

Related Guides

• AI Writing Tools: How to Choose the Right Stack
• AI Image Tools: A Practical Selection Guide
• AI SEO Tools: Evaluation Framework for Content Teams
• AI Video Tools: How to Select a Production-Ready Stack

Explore related tools

Use the directory to compare tools, evaluate offers, and browse by task.