Skip to content

ADR-0004 — Add Project-Level .claude/settings.json to Prevent Global Settings Corruption

Status: accepted Deciders: IA Agent Guild Date: 2026-03-18 Issue: #5 — Settings Error: invalid defaultMode

Context

When a user opens a generated project in Claude Code, the agent reads AGENTS.md section 4 ("Execution Directives & Permissions"), which states "The following actions are assumed granted. NEVER block progress waiting for confirmation on these." This language caused agents to call the update-config skill to configure ~/.claude/settings.json (the user's global Claude Code settings) with a defaultMode value. In some versions this value was invalid or deprecated, producing the following error on the next startup:

C:\Users\aluna\.claude\settings.json
  └ permissions
    └ defaultMode: Invalid value. Expected one of: "acceptEdits", "bypassPermissions",
      "default", "delegate", "dontAsk", "plan"

A second contributing cause was setup/install.bat and setup/install.sh using claude /plugin marketplace add anthropics/skills — note the /plugin with a leading slash. claude plugin marketplace add IS a valid CLI command, but the /plugin variant is not: on Linux/macOS the shell interprets /plugin as a filesystem path; on Windows it may also be mishandled. This means the marketplace install step was silently failing for most users.

Decision

  1. Add {{cookiecutter.project_slug}}/.claude/settings.json to the template with a valid, conservative defaultMode: "default". A project-level settings file takes precedence for project-scoped sessions and signals to agents that permissions are already configured, removing any motivation to touch ~/.claude/settings.json.

  2. Fix the syntax in setup scripts — change claude /plugin marketplace add anthropics/skills → claude plugin marketplace add anthropics/skills (remove the leading /).

Considered Options

Option Rejected reason
Patch ~/.claude/settings.json in setup scripts Writes to the user's global settings — the exact problem we're solving
Update AGENTS.md to list valid defaultMode values Mitigation only; does not prevent the root cause
Remove the Permissions section from AGENTS.md Loses useful documentation for project agents

Consequences

Positive: - Generated projects ship with a valid, project-scoped settings.json out of the box. - Agents no longer need to call update-config for basic permission bootstrap. - Setup scripts now correctly install the Claude Code skills marketplace.

Negative: - Every generated project will include a .claude/settings.json; teams that prefer a different defaultMode will need to adjust it manually.

Implementation

  • {{cookiecutter.project_slug}}/.claude/settings.json — new file
  • {{cookiecutter.project_slug}}/setup/install.bat — fix claude /plugin ... → claude plugin ...
  • {{cookiecutter.project_slug}}/setup/install.sh — fix claude /plugin ... → claude plugin ...