Three engineers. One repo. One Claude Code project directory committed to the version-controlled root. Within a week, all three were getting different results from the same agent: different models, different shell permissions, different MCP servers loading on startup. The settings.json they assumed was shared was not actually controlling what they thought, because no one had agreed on what project settings should contain or how they differed from user settings.
That is a config problem, not a tooling problem. And it is common enough across Australian engineering teams running Claude Code that it is worth treating as a first-class platform concern before any rollout scales past two or three developers.
The five-field convention
The project-level settings.json should contain exactly what the team has agreed belongs there and nothing else. The convention that holds across frontend, backend, data pipeline, and infrastructure repos reduces to five fields. These five are enough to cover model behaviour, security boundaries, tooling scope, and cost visibility without turning the file into something only one engineer understands.
Model. Pin the Claude version per repo. A model rollover mid-release-window can silently change agent behaviour. You will not know until someone files a bug.
Permissions. An explicit allow-list of shell commands, not a wildcard. Overly permissive defaults are how production accidents happen.
MCP servers. Scope the list to what the repo actually uses. A frontend project loading eight backend MCPs adds noise and increases token overhead on every agent session.
Statusline. Surface current branch, git status, and token usage. Real-time visibility on cost is the cheapest cost control available.
Hooks. A minimal automation block for project-level triggers. Relative paths only; absolute paths break portability.
What to leave out
The portability test is straightforward: clone the repo into a fresh container and run Claude Code without touching anything outside the project directory. If something breaks or behaves differently, you have committed something that belongs in user settings, not project settings.
API keys. Project settings.json is committed to version control. Your API key is not project configuration.
Absolute filesystem paths. A hooks block pointing to /Users/yourname/ breaks the moment someone else clones the repo.
Your username or local aliases. These belong in user-level settings. The project file should have no knowledge of who is running it.
The ownership boundary matters as much as the content boundary. The platform engineer who owns the project settings.json can push a change and every developer on the team benefits without touching their local config. A file that only works on its author's machine is not a team convention — it is a personal config with social anxiety. One person owns the project-level file; everyone else owns their own user settings. These should not collide.
A reference settings.json shape
Keep the file under 80 lines. If it grows past that, the work belongs in a CLAUDE.md file or a dedicated plugin, not in settings.json. Settings is configuration: it tells Claude Code how to behave in this repo. CLAUDE.md is instruction: it tells the agent what to do and why. They are different things, and conflating them makes both harder to maintain.
A Sydney mid-market development team running this convention across 12 repos cut their Claude Code support tickets from around 35 a week to 8. That is worth roughly $40,000 a year in avoided debugging: one senior developer at $120 per hour, reclaiming about 30 hours of issue triage per month. You can model the payback figures for your own team with our ROI Calculator.
The platform engineer who owns that settings.json now fields questions in code review comments, not in Slack DMs at 4pm on a Friday. That shift does not sound significant until you realise that code review questions leave a searchable, auditable trail and DMs do not. Onboarding new developers becomes faster when the settings are documented by convention rather than institutional memory.
When to skip it
Not every project justifies a committed project settings.json. A solo prototype you are running for a week, a throwaway repo with no second developer, a personal project where you change your own workflow monthly. None of these need the overhead. The convention is designed for coordination problems. If there is no coordination problem, there is no convention needed.
More than one developer running Claude Code against the same codebase.
A CI/CD pipeline where agent behaviour could affect deployments or test runs.
Multiple environments where consistent agent behaviour matters: dev, staging, production.
If none of those apply, user-level settings are sufficient. Do not add process overhead for a problem you do not have. If you are at the early stage of mapping which repos and workflows to prioritise for Claude Code, our AI Readiness Assessment is a useful starting point before you lock in any conventions.
Measurement closes the loop
Standardised config is the foundation. Measurement is what tells you whether the foundation is working. Add three numbers to a shared dashboard from the first week: time-to-first-result on the agent flow, cost-per-task in tokens, and acceptance rate — how often an engineer takes the agent's output without significant edits. Without those three, the conversation with your engineering manager or finance team is a faith argument. With them, it is a numbers argument. Those are very different conversations.
A Sydney engineering platform team running this measurement discipline attributes around $120,000 a year of additional savings to the dashboard alone. The reason was not the dashboard itself but what it made visible: two agent flows were consuming roughly 40 percent of the token budget while delivering about 10 percent of the value. Cutting them was a one-day decision once the data existed. Without the dashboard, both flows would still be running.
The second discipline is a quarterly settings review. MCP servers that no developer is actively using get removed. Hooks written for workflows that no longer exist get retired. Permissions added for a one-off task get audited. Australian engineering teams that treat this review as a fixed calendar item build Claude Code setups that compound rather than decay. Automata AI supports teams through this configuration and review work as part of our Claude Code automation services.
Pick the repos where developer time is most expensive and agent failure has the highest cost. Commit a settings.json that passes the portability test. Add the dashboard. In 90 days you will know exactly which parts of the setup are pulling their weight.
