How to roll out Claude Code to an engineering team
A Claude Code rollout plan for engineering leaders: pilot, shared repo config, organization-wide managed settings, plugins, and how to tell it's working.
Six months after a company adopts Claude Code, a familiar picture appears. Every squad has its own CLAUDE.md, and two of them contradict each other. Senior engineers leave the same review comment for the tenth time. A rule the security team asked for exists in one repository. Nobody can say what the agents across the company are being told.
None of that is a model problem. It's a rollout problem. This guide is a four-step plan for engineering leaders, built on Anthropic's documentation for memory, settings, best practices, and plugin administration, checked on 16 November 2026.
Step 1: pilot with one squad and one repository
Pick a squad that already wants to use Claude Code, and one repository it owns. For two to four weeks, the goal is not speed. It is to find out what Claude can't see in your codebase.
Anthropic's best practices put it plainly: Claude reads code well and will find your file layout, conventions, and test framework on its own. What it can't find is information that was never in the repository, such as a decision made in a meeting, a deploy process in one person's head, or the environment variable integration tests need. Ask the pilot squad to write down every time Claude gets something wrong, and why. That list becomes your shared setup.
Step 2: commit a shared setup to the repository
Everything a teammate's Claude Code needs should come with git clone. Four files do most of the work:
| File | Holds | Guide |
|---|---|---|
CLAUDE.md | Commands, environment, gotchas, a few long-lived decisions. Under 200 lines | CLAUDE.md examples |
.claude/settings.json | Shared permission rules and hooks | settings.json |
.mcp.json | The MCP servers the team uses, with secrets as ${VAR} | MCP setup |
.claude/skills/ | Repeatable procedures: release, migrations, PR descriptions | skills examples |
Two rules keep this setup healthy. Review changes to these files in pull requests like code, because they are code for the agent. And put anything that must never happen in a hook or a deny rule, not in CLAUDE.md, because Claude treats CLAUDE.md as context rather than enforced configuration. Examples are in Claude Code hooks: 6 examples.
Step 3: move company-wide rules into managed settings
Repository files work per repository. Rules that apply to every repository belong in managed settings, which override every other settings file and which users can't override.
They are delivered three ways: server-managed settings from the claude.ai admin console, an MDM policy, or a managed-settings.json file. Use them for:
- Permission deny rules for things no agent should do anywhere, such as pushing directly to protected branches.
- A managed CLAUDE.md for company guidance, as a file deployed to each machine or through the
claudeMdkey. Developers can't exclude it. Anthropic's documentation recommends managed CLAUDE.md for guidance and managed settings for enforcement. allowManagedHooksOnlyif only admin-approved hooks should run.- Required plugins, with
extraKnownMarketplacesandenabledPlugins, so every machine gets the team's skills, subagents, and hooks. Details in Claude Code plugins and marketplaces.
Keep the managed layer small. Paths, delivery options, and keys are in Claude Code managed settings. A short list of company-wide rules is followed more reliably than a long one, and every squad still needs room for its own repository setup.
Step 4: expand team by team, and measure the right things
Expand one or two squads at a time, starting from the pilot's setup rather than a blank repository. Measure what reviewers and engineers can see:
| Signal | Why it matters |
|---|---|
| Repeated review comments | Should fall as rules move into CLAUDE.md, skills, and hooks |
| Time from ticket to merged PR | The outcome speed is supposed to improve |
| Engineers using the shared setup | A setup only helps the people who have it |
| Agents building against outdated decisions | The failure files can't catch on their own |
Avoid "lines of code generated." It rewards volume, not correctness.
The four ways rollouts go wrong
- Every squad writes its own rules. Contradictory CLAUDE.md files across repositories, with nobody owning the differences. Fix: shared repository templates and a small managed layer.
- Rules live only as guidance. "Never touch the payments schema" in CLAUDE.md is followed most of the time. Fix: hooks and deny rules for anything absolute.
- Updates don't propagate. A skill improves in one repository and the copies in twenty others don't. Fix: plugins and a marketplace.
- Decisions never reach the agents. The team decides in a meeting to stop supporting a payment provider. Nobody edits twenty CLAUDE.md files. Agents keep building against the old rule for weeks.
The first three have native fixes. The fourth is the one most teams discover last.
Where Lockstep fits
Lockstep handles the parts of a rollout that files and settings don't. Standards & Skills lets an engineering lead publish versioned standards and skills once and roll them out by team, repository, path, or task type, with a preview, a pilot, expansion, and rollback. An adoption view shows which version reached which checkout and which sessions started with it; whether Claude actually invoked a skill is reported as unobservable, not guessed. Exceptions are approved per requirement, tied to a version, and expire on their own.
For decisions, Lockstep captures them from PRDs, Slack, and pull requests, makes each binding when its owner approves it, and briefs every Claude Code session on the ones that apply. It supports Claude Code today; Codex isn't supported yet. See how it works.
Sources checked 16 November 2026
- https://code.claude.com/docs/en/best-practices
- https://code.claude.com/docs/en/memory
- https://code.claude.com/docs/en/settings
- https://code.claude.com/docs/en/plugins/org
- https://code.claude.com/docs/en/hooks-guide
- https://github.com/lockstep-team-agent/lockstep
Related reading
For the CTO's view of decisions and agents, see the CTO's playbook for AI coding agents. For sharing what agents learn, see Claude Code team memory. For choosing between extensions, see CLAUDE.md vs skills vs hooks vs subagents. For the individual habits behind a good rollout, see Claude Code best practices. For choosing a front end, see Claude Code desktop vs CLI vs VS Code. For keeping agent-written code maintainable, see technical debt from AI coding. For admin controls and analytics, see Claude Code for enterprise. For onboarding new engineers, see the engineering onboarding checklist. For measuring the effect on delivery, see DORA metrics.
Frequently asked questions
- How should a company roll out Claude Code?
- Start with one squad and one repository, commit a shared setup to that repository, then move company-wide rules into managed settings and package reusable skills as plugins. Expand team by team, and measure review quality and adoption rather than lines of code.
- How do I make every engineer's Claude Code follow the same rules?
- Commit a project CLAUDE.md, .claude/settings.json, and .mcp.json to each repository. For rules across every repository, use managed settings, which users can't override, and a managed CLAUDE.md. Use permissions.deny and hooks for rules that must never be broken, because CLAUDE.md is guidance, not enforcement.
- How do I control what Claude Code can do across the company?
- Managed settings, delivered from the claude.ai admin console, through MDM, or with a managed-settings.json file. They override every other settings file. Use them for permission deny rules, required plugins, and allowManagedHooksOnly if only admin-approved hooks should run.
- How do I measure whether a Claude Code rollout is working?
- Look at outcomes engineers and reviewers can see: repeated review comments going down, time from ticket to merged pull request, how many engineers use the shared setup, and how often agents build against outdated decisions. Lines of code generated is a poor signal.
- What goes wrong in Claude Code rollouts?
- Every squad writes its own CLAUDE.md and they contradict each other, rules live only in files Claude treats as guidance, updates never reach half the laptops, and decisions made in meetings or Slack never reach the agents at all.
Keep reading