Claude Code setup guide for teams: CLAUDE.md, MCP, and standards that hold

An individual install is one engineer, one terminal, one set of habits. A team setup is a repository that carries its own instructions, so any engineer, and any future session, starts from the same place. It has four layers:

1. Install and authentication. Everyone signs in the same way so usage is visible in one place.
2. CLAUDE.md. The standing instructions the model reads at the start of every session.
3. MCP configuration. The tools and data the model is allowed to reach, and with which credentials.
4. Working norms. How the team plans, reviews and merges what the agent writes.

Skip any one layer and the other three lose most of their value. The rest of this guide takes them in order.

Install the Claude Code CLI following Anthropic's current instructions for your platform, then run it once inside a repository to authenticate. Two paths exist: an API key from the Anthropic Console, which bills usage to that organization, or a Claude subscription login. Pick one for the whole team. Mixed billing makes cost impossible to read later.

Before anyone writes a CLAUDE.md, run the agent on a small, real task and watch what it does with no instructions. The gaps you see, wrong test command, wrong package manager, edits in a generated folder, are the first lines of the file you are about to write.

CLAUDE.md lives at the repository root and is read at the start of every session. Nested CLAUDE.md files in subfolders add context for that part of the tree. The single most common mistake is treating it as documentation. It is an operating manual, and it should be short enough to be followed in full.

• Commands. How to install, build, test, lint and typecheck. Exact commands, not prose.
• Conventions that are not obvious from the code. Naming, error handling, where side effects live, what a finished change includes.
• An architecture map. Five to fifteen lines on where things live and how requests flow.
• No-go zones. Generated files, migrations, auth code, anything that needs a human before it changes.
• Definition of done. Tests pass, types check, the change is explained in the commit.

Commit CLAUDE.md with the code. When the agent gets something wrong twice, the fix is a line in the file, not a longer prompt. Review it in pull requests like any other source file.

The Model Context Protocol is how Claude Code reaches tools and data outside the repository: issue trackers, databases, internal APIs. A project-scoped .mcp.json at the repository root lists each server, its transport and its credentials, so the whole team shares one configuration under version control.

• Start read-only. Search, fetch and query tools first. Add write-capable tools only once the team has a review step for them.
• Narrow the credentials. Each server gets a token scoped to what it needs, never a personal admin token.
• Keep production out of reach. Point database servers at a replica or a staging copy.
• Prefer servers you can read. An MCP server is code running with real credentials. Treat third-party servers the way you would treat any dependency with access to your data.

If you are building your own server, the end-to-end MCP server guide and the MCP security checklist cover transport, auth and the mistakes that keep servers out of production.

The Claude Code extension for VS Code uses the same account, the same CLAUDE.md, the same permission settings and the same MCP configuration as the terminal. That is the point of doing the setup in the repository: nothing has to be repeated per editor or per machine.

Headless mode, running the CLI with a prompt and no interactive session, is the right shape for repeatable jobs in CI: summarizing a failing test run, drafting a first-pass review, labelling an issue. Keep CI runs read-only. A pipeline with credentials that can write to a real system is exactly the setup the permission model exists to prevent.

• Plan before edits. Ask for a plan, read it, then approve. Most bad diffs were bad plans first.
• Small tasks, small diffs. One change per session where possible. Clear the context between unrelated tasks.
• Tests are acceptance. The agent runs the commands in CLAUDE.md before it reports done.
• Review like a pull request. AI-written changes get the same review a new team member's work would get.
• One owner. A named engineer owns CLAUDE.md, the MCP config and the permission policy, and updates them when the agent misbehaves.

For the longer list of habits that hold up under production pressure, read Claude Code best practices for teams that ship.

• Chatbot usage. Pasting snippets into a session instead of letting the agent work in the repository with the right instructions.
• CLAUDE.md as a wiki. Pages of background the model skims. Keep the manual, move the history elsewhere.
• Production credentials in MCP. A convenient token that turns a wrong tool call into an incident.
• No verification loop. Without runnable tests and typechecks in the file, the agent cannot tell whether it finished.
• No owner. Configuration that nobody maintains decays within a quarter.

The disciplines in this guide, scoped tools, verification, ownership, are the same ones the Systems Decision Audit checks when it takes an AI workflow through the Production Gate. A team that has set Claude Code up properly usually already has half the evidence the audit asks for. If the workflow you are building with it is the one your operation depends on, the audit is how you find out whether it can be trusted there.