How to set up Claude Code for your whole team (not just your own laptop)

Most developers trying Claude Code start by opening a repository, requesting a change, and receiving code that is almost correct. The issue is not the model, but the lack of context about the team. This context is provided in a file called CLAUDE.md. This guide explains what to include in that file when a team shares it, rather than just one person.

Claude Code reads CLAUDE.md automatically at the beginning of every session. You do not need to paste it, reference it, or remind the agent. If the file is in your project root, it is in context. There are three possible locations for CLAUDE.md: in the user's home directory (~/.claude/CLAUDE.md), in the root of the repository (repo/CLAUDE.md), or within a specific folder (repo/folder/CLAUDE.md).

For a team, the repository-level file is the one that matters, as it is checked in, reviewed like code, and read by every developer's agent.

When creating a CLAUDE.md, a team needs to include five sections:

1. Ownership: Specify who reviews different areas of code, such as payments, platform, or frontend teams, and the required number of reviewers.

2. Escalation: Define what the agent should do when a task crosses a line, such as stopping and asking, opening an issue, or proceeding. Write short imperatives for better consistency.

3. Commands: List the exact build, test, and lint commands character for character. Avoid providing plausible commands that may not be correct.

4. Standards: Document team standards, such as minimum test coverage, API response times, restrictions on new TypeScript types, and commit message formats.

5. Tools and systems: Specify issue trackers, CI systems, log locations, and available environments. The agent will reference these when providing instructions.

A single CLAUDE.md works well until your team has members with different defaults. In such cases, create short profiles for each role and load them when a session starts. This keeps the shared file short and focused on the common rules, while the profiles address role-specific differences.

Common mistakes that can render a CLAUDE.md ineffective include it growing too large, becoming outdated, or only describing team values instead of providing clear instructions. To keep it effective, review the file when making changes to the code it describes, treat a bad agent suggestion as a bug report against the file, and use tools like AI Workspace Builder to extract rules from existing documentation and generate the CLAUDE.md quickly.