Every Sydney engineering team I have seen adopt Claude Code at scale hits the same wall around week six. Not a technical wall. An invisible one.
The senior engineer's config allows the Bash tool in CI. A junior's doesn't. The team lead's MCP server points at the production instance. Two contractors' configs point at a stale staging environment. One engineer has hooks that enforce commit formatting; three others don't. Nobody's settings.json is the same. The first time it shows up is in a code review, when one engineer's post-write hook fired and nobody else's did. Six weeks of Claude Code adoption and the team is already managing invisible config debt. The usual response is to write it down in a Notion doc. That doc is out of date within a fortnight.
The fix is one file: .claude/settings.json, checked into the repo, owned by the platform team.
What settings.json actually controls
Claude Code's settings.json is the boundary between the CLI's default behaviour and your team's behaviour. It controls four categories of things at the workspace level.
Allowed and blocked tools. The explicit list of what Claude can and can't invoke: Bash, Read, Write, MCP tools. Also what it should never attempt in your CI environment.
MCP server connections. The workspace-level MCPs your team uses, connection strings referenced through env vars, not pasted directly into the file.
Hook commands. Shell scripts that fire on pre-tool, post-write, session-start, and session-end events. These are where convention checks and safety gates live.
Model selection rules. Which model runs for which task: Opus for plan mode, Sonnet for most editing tasks, Haiku for short completions where cost per session matters.
Engineers' personal preferences (colour scheme, personal MCPs, per-prompt style adjustments) live in their per-user config at ~/.claude/settings.json. The team file is for the things that should behave identically across every engineer on the project.
The five-layer settings.json structure
A working reference file for a mid-market Australian team organises into five layers. I call this the five-layer settings.json structure. Not Anthropic's terminology, but it maps cleanly to how the file is actually maintained in a team context.
Tool permissions. The allow list for standard Claude Code tools plus explicit denies for anything the team wants blocked outright.
MCP server block. Workspace MCPs with env-var references for all credentials. No inline tokens, ever.
Hooks block. Named hook commands for each lifecycle event. Each hook points at a script in the repo, not an inline shell command. Inline commands are hard to review and hard to rotate when something goes wrong.
Model selection block. Model choice per mode: Opus for planning sessions, Sonnet for interactive editing, Haiku for short-context tasks where cost per session matters at scale.
Environment declarations. The list of env var names the file expects — not their values, just their names. This is what drives the .env.example file that every onboarding engineer copies on day one.
The file checks into the repo at .claude/settings.json. Changes go through PR review. When you need to update a hook command, add an MCP server, or change the model selection rules, the team sees the diff before it ships. That's the whole governance model. No separate config management system, no out-of-band changes. The same PR process that governs code changes governs Claude Code behaviour.
Secret management: the most common mistake
The single most common settings.json mistake is committing credentials directly into the file. It happens because MCP server connection strings often carry API keys and bearer tokens, and pasting them in is fast when you're configuring under pressure. A new team member joins, gets the file from the repo, fills in their local env, and it works. The problem surfaces three months later when you try to rotate the shared token and discover it was committed to the file directly, bypassed the .env convention, and has been sitting in git history ever since.
The fix is a per-engineer .env file with the actual values, and env-var references inside settings.json. The team file knows which secrets exist by name. The values stay on the engineer's machine.
All secrets are env-var references. Never an inline value. A pre-commit hook catches any string matching common credential patterns before the commit lands.
A .env.example file in the repo root lists every variable name the team file expects. Onboarding engineers copy it, populate it locally, and get a working config in under ten minutes.
Rotate shared MCP credentials quarterly. Not because they're likely to be compromised. Rotation processes only work reliably if they've been tested before they matter.
When a reference config is the wrong move
Not every team should have one. Three situations where the overhead exceeds the alignment benefit:
Teams under five engineers. Implicit config knowledge spreads naturally when you pair frequently. The maintenance overhead of a reference file isn't justified at this scale.
Early experimental phases. If the team is still figuring out which MCP servers they actually need, locking a reference file produces a config nobody trusts after week two.
Meaningfully different workstreams. A data engineer using Claude Code for pipeline work has a different optimal config from a frontend engineer. One file that covers both usually serves neither well.
For teams where 20 or more engineers are using Claude Code as their primary interface for similar work, the calculus flips. At that scale, config divergence is a tax that compounds weekly. A 30-engineer Sydney scale-up running misaligned configs typically loses around $40,000 a year in support overhead and review variance, based on senior engineer time at $150/hr fully loaded.
Rolling out the reference config
The wrong rollout: push to main, update the onboarding doc, send a Slack message. Half the team adopts it. The other half doesn't notice. Six months later you have two cohorts with different behaviour and nobody's confident which config is the correct one.
The right pattern is incremental. Three senior engineers run the reference config for a week. They surface the issues — usually an overaggressive hook, or an MCP server the reference file assumes but a contractor environment doesn't have. You fix those in week two. You roll to the full team in week three with a clear diff and a brief note on what changed and why. Feedback in that third week is minimal because the file has already been stress-tested against real conditions.
For a 30-engineer team, this is roughly one week of platform engineering to build the reference file, plus two weeks of iteration based on feedback. At $150/hr fully loaded for a senior platform engineer, that's $15,000–$25,000 in total investment. The recovery on $40,000/year in alignment overhead is straightforward. If you want a second set of eyes on what should and shouldn't be in your file, our AI Automation Services team has run this exercise for a dozen Australian mid-market engineering organisations.
The teams that get the most from Claude Code at scale aren't the ones with the most sophisticated configs. They're the ones where every engineer's Claude behaves the same way when it matters: in CI, in code review, in a production incident at 11pm on a Tuesday. Consistency is more valuable than cleverness here. That's a settings.json problem. It has a settings.json solution. If your team is still figuring out how mature your AI tooling needs to be before standardising, start with the AI Readiness Assessment.
