What Each Common Claude Code Setting Does

The "recommended Claude Code settings" people share online tend to be long: a default model, an output style, a string of allow rules, a switch that auto-approves every MCP server in the project, and CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80 for good measure.

You paste the whole thing into settings.json and use it for a while. The model's answers change, an MCP tool won't connect, and you can't say which line is responsible.

The trouble with copied configuration is that every field changes how Claude Code runs, and you don't know what each one changed. Some fields are interface preferences. Some auto-approve external servers. Some environment variables do nothing at all with your model and setup. Change several at once and you lose any basis for judging what went wrong.

A steadier approach works the other way around:

• separate project guidance from runtime configuration;
• start from a minimal configuration you can explain line by line;
• add one field at a time to solve the problem in front of you, and check the result.

The rest of this post goes through the common fields in that order: what each one solves and what to watch for.

01 Keep Project Guidance and Runtime Settings Apart

CLAUDE.md describes team requirements. Settings change runtime behavior such as the model, permissions, and environment variables. Writing "use a particular model by default" in a natural-language instruction doesn't change the runtime configuration.

Use this table to decide where something belongs:

The two work together: project instructions give Claude a basis for action, Settings decide how things run, and each needs its own verification.

02 Start from a Minimal Configuration You Can Explain

Start with a simple configuration you can explain. Understand the sources and how they merge, then check that the JSON is valid. The fields below set the model, output, and read restrictions, and you should know what problem each one solves:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "outputStyle": "Explanatory",
  "respectGitignore": true,
  "permissions": {
    "allow": [
      "Bash(pnpm lint)",
      "Bash(pnpm typecheck)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

$schema lets the editor suggest fields and types and run basic validation. It can lag behind new releases, so when a new field gets flagged, check the current official field reference. The settings documentation also points out that settings files are strict JSON: a // comment or a trailing comma is a syntax error.

Change only the fields that solve the current problem. If you want more detailed explanations, try the output style first and check the result. Swapping the model, permissions, and plugins all at once makes changes hard to trace. This file also merges with your user and local settings, and working out the final values is covered in which Claude Code settings file takes effect.

03 Model and Output Style

model sets the default model for new sessions. The example uses the stable alias sonnet, which is usually easier to maintain than a pinned version.

To switch models in the current session, use /model. The docs say /model saves your choice as the default for new sessions; for a one-off try, press s in the /model picker to switch only the current session. If you edit model in the file directly, start a new session or restart, then confirm the current model with /model.

outputStyle changes how the system prompt asks Claude to express itself, which goes beyond answer length; project requirements still belong in project instructions. When a switch takes effect depends on your version:

That table comes from the output styles documentation. Check your version first, and keep the history the current task still needs.

04 Permissions, Environment Variables, and File Suggestions

permissions decides whether a tool call is allowed, asked about, or denied. Before adopting someone else's configuration, review each entry's tool, arguments, and reach so you don't accidentally open up all of Bash. For tightening the rules, see 5 common gaps in Claude Code permission rules.

env injects environment variables into Claude Code sessions and the subprocesses they start:

{
  "env": {
    "MY_PROJECT_MODE": "development"
  }
}

Put only non-secret team switches in shared configuration. Supply API keys and tokens through a secrets manager, Claude Code authentication, or a controlled launch environment. Local settings.local.json is plain text too, so don't treat it as a vault.

MCP servers have their own connection configuration. Set the variables each server needs in its MCP config and check them there; the official docs pass variables to a local MCP server with --env when adding it.

Say your terminal can read JIRA_TOKEN, but the Jira MCP server still reports that it's unauthorized. Find out which process actually received the variable: the terminal can see it, and the MCP process may not. Check the MCP variable configuration, then make one minimal tool call to see whether authentication changes.

respectGitignore mainly affects @ file suggestions; per the official field reference, it controls whether the @ file picker leaves out files matching .gitignore. Protect secrets separately: use permissions.deny for built-in read tools and the sandbox for access from arbitrary subprocesses.

Interface tips only affect your experience and usually live in user or local settings. Set specific switches when you need them.

05 Plugins, Project MCP Servers, and Commit Attribution

enabledPlugins turns plugins on or off by their full plugin-name@marketplace-name.

The switch is easy to flip; the plugin's source and permissions deserve more attention. Confirm what it does and what it can reach before enabling it. The switch itself doesn't judge whether outside code is trustworthy.

enableAllProjectMcpServers automatically approves every MCP server defined in the project's .mcp.json. In a team repository where server sources are fully controlled, it cuts down on prompts, but it shouldn't be a default for every project. MCP servers connect to external systems and can gain sensitive capabilities. When you don't know where a repository's configuration came from, review and approve servers one at a time.

The settings reference adds a detail: in a folder whose trust dialog you haven't accepted, this switch is ignored in the shared project file, and only values from user settings, managed settings, and --settings count.

attribution sets the attribution on Git commits and pull requests. If your team has a disclosure policy, maintain it in project settings. Whether attribution stays should follow team and organization requirements, so if the team requires AI disclosure, leave it on regardless of personal preference.

06 Observe the Problem Before Copying a Threshold

Seeing CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80, you might want to copy it so compaction kicks in at 80% of context. But is compaction timing really your problem? And does your model and environment even support it?

The environment variables reference describes it like this: it sets the percentage of the auto-compact window at which compaction triggers, it can only lower the threshold to compact earlier, values above the default are ignored, and it applies only in sessions that compact before the model's context limit. Copying it may do nothing, or it may compact information you're still using.

Observe first, then work through these steps:

1. Use /context to see what's taking up context.
2. Use /clear between unrelated tasks.
3. When you need to keep the current task, run /compact and say what to preserve.
4. Set the threshold variable only once you understand how your model and environment handle compaction.

Make the smallest change that addresses what you observed, so you don't lose track after changing several parameters together.

For everyday upkeep, add plugins, MCP servers, and Hooks one at a time, remove dead fields, and run /doctor after upgrading. Note each setting's purpose and source, and when something feels off, you'll know which line to check first.