Claude Code configuration standard¶

Claude Code is configured at two scopes — user-level (machine-wide) and repo-level (per project) — with three physical layers that work together: CLAUDE.md context files, settings.json permission/behavior files, and agent definition files.

The full configuration structure¶

~/.claude/                           ← user-level (machine-wide, never committed)
├── CLAUDE.md                        ← context: identity, universal conventions
├── settings.json                    ← permissions, env vars, hooks, status line
├── statusline.ps1                   ← custom status bar script
├── agents/
│   ├── triage-lookup.md             ← 6 user-level agents available in every repo
│   ├── markdown-prose-editor.md
│   ├── azurelocal-domain-expert.md
│   ├── mkdocs-material-doctor.md
│   ├── turner-module-scaffold-engineer.md
│   └── mms-2026-demo-presenter.md
└── hooks/
    └── check-context.ps1            ← fires on every prompt; triggers memory dump at 90k tokens

<repo>/                              ← repo-level (committed to the repo)
├── CLAUDE.md                        ← context: repo purpose, structure, standards links
└── .claude/
    ├── agents/
    │   └── <repo-name>-engineer.md  ← one repo-specific agent (most repos)
    ├── settings.json                ← repo-specific pre-approved tool patterns
    └── settings.local.json          ← machine-specific overrides (gitignored)

The two scopes¶

User-level (`~/.claude/`)¶

Applies to every repo on the local machine. Nothing in this directory is committed anywhere.

The CLAUDE.md here contains owner identity, preferred language and tooling, the Azure environment (ADO org, Key Vault), and universal coding conventions. See user environment for the full reference and recommended template.

The settings.json here contains: - env — CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (required for multi-agent parallelism) - permissions.allow — the cumulative pre-approved tool call patterns built up across all sessions - hooks — the UserPromptSubmit hook that runs check-context.ps1 - statusLine — wires statusline.ps1 to the Claude Code terminal status bar - effortLevel, verbose, and other behavioral settings

Repo-level (`<repo>/` and `<repo>/.claude/`)¶

Committed to the repo. Applies to anyone who opens Claude Code in that directory.

CLAUDE.md at the repo root contains the project-specific context: what the repo is, ADO area path, standards references, repo structure, key facts, and allowed/confirm actions. It must exist before any Claude Code session in a repo.

.claude/agents/ contains one repo-specific agent definition. This agent has deep knowledge of the project's structure, conventions, and constraints that would not be appropriate in a user-level agent.

.claude/settings.json contains repo-specific pre-approved tool patterns that would generate permission prompts otherwise. Common patterns: specific PowerShell invocations, test runners, build commands.

.claude/settings.local.json is gitignored and handles machine-specific overrides — useful for paths or commands that differ per developer machine.

Agent definitions¶

Every agent is a Markdown file with a YAML frontmatter block followed by plain-text system instructions.

Format¶

---
name: agent-name
description: One-line description — used by the harness to match spawn requests. Be specific.
model: haiku|sonnet|opus
tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - WebFetch
  - WebSearch
  - mcp__claude_ai_Microsoft_Learn__microsoft_docs_search
---

Plain-text system prompt for this agent.
Explain what it is, what it knows, what it does, and any hard constraints.

The description field is what Claude Code shows in the agent list and what you write in Agent tool calls — make it precise enough to be unambiguous.

Model assignment strategy¶

Tier	Model	When to use	Approx cost vs opus
Cheap	`haiku`	Fast read-only lookups, log triage, cheap one-shots	~20%
Default	`sonnet`	Most agents — code, writing, research, planning	~60%
Heavy	`opus`	Deep cross-repo research; the only legitimate Opus agent is `azurelocal-domain-expert`	100%

Default to sonnet. Opus is 5× more expensive than sonnet per output token. Reserve it for the one agent that genuinely needs deep synthesis across many sources.

Agent roster¶

The complete agent roster — including which repos have agents, what model each uses, and the rationale — is documented in:

E:\git\demo-repository\AGENTS-PLAN.md

That is the canonical living document for agent topology across all HCS repos. Update it when adding, archiving, or changing agents.

Current user-level agents (available in every repo):

Agent	Model	Purpose
`triage-lookup`	haiku	Fast read-only: "what does this file say", find references, summarize logs
`markdown-prose-editor`	sonnet	Markdown/MDX editing — runbooks, READMEs, ADRs, blog drafts
`azurelocal-domain-expert`	opus	Deep cross-repo research on Azure Local, Hyper-V, S2D, Network ATC
`mkdocs-material-doctor`	sonnet	MkDocs Material theme, plugins, nav config, mike versioning (14 repos)
`turner-module-scaffold-engineer`	sonnet	Turner Legacy scaffold modules (board, budget, calendar, finance, travel)
`mms-2026-demo-presenter`	sonnet	MMS 2026 session demos

settings.json — permission model¶

The permissions.allow array in settings.json pre-approves specific tool calls so Claude Code does not prompt for every operation. Patterns are matched literally or with wildcards.

Pattern formats¶

"permissions": {
  "allow": [
    "Bash(git add:*)",
    "Bash(git commit -m ':*)",
    "Bash(git push:*)",
    "Bash(gh issue:*)",
    "Bash(gh pr:*)",
    "Bash(gh run:*)",
    "Bash(gh api:*)",
    "Bash(pwsh -NoProfile -Command ':*)",
    "Bash(pwsh -NoProfile -File ':*)",
    "Bash(pwsh -NonInteractive -Command ':*)",
    "Bash(pwsh -NonInteractive -File ':*)",
    "Read(//e/git/**)",
    "WebSearch",
    "WebFetch(domain:github.com)",
    "WebFetch(domain:raw.githubusercontent.com)",
    "WebFetch(domain:learn.microsoft.com)"
  ]
}

The :* suffix matches any trailing arguments. domain: restricts WebFetch to a specific host. Patterns accumulate — the user-level list grows as new operations are approved in sessions.

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS¶

Every repo and the user-level settings must include this env var to enable multi-agent parallelism:

"env": {
  "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}

Without it, the Agent tool works but teams (multiple agents spawned in parallel) may not. Check the repo's .claude/settings.json and ensure it is present.

Context-watch hook¶

The UserPromptSubmit hook fires on every user prompt. It reads the session transcript, calculates the current context token count (input + cache_creation + cache_read), and injects a [CONTEXT-WATCH] system reminder when the total exceeds 90,000 tokens.

When the reminder fires, Claude Code writes a comprehensive memory dump to the project's auto-memory directory before responding to the user's message. The user then runs /clear to reset the session. Session compaction is explicitly disabled — /clear plus structured memory is the preferred approach because compaction produces lossy summaries.

The hook script is at scripts/hooks/check-context.ps1 in this repo. The canonical running copy lives at ~/.claude/hooks/check-context.ps1. The two should be kept in sync.

Status line¶

A custom PowerShell script (~/.claude/statusline.ps1) provides the Claude Code terminal status bar. It displays:

Active model name
Context window usage percentage with a color-coded bar (green → yellow → red)
Active agent name (when an agent is running)
Total session tokens (cumulative input + output)

The script is at scripts/statusline.ps1 in this repo. The canonical running copy lives at ~/.claude/statusline.ps1.

Every repo must have a CLAUDE.md¶

No Claude Code session should be opened in a repo that does not have a CLAUDE.md. Use templates/CLAUDE.md.template as the starting point. Fill in all {{PLACEHOLDER}} values. Commit it before the first session.

See repo settings for the full standard.

Never in any CLAUDE.md or settings file¶

Secret values, tokens, API keys, passwords
Subscription IDs in settings files (the platform repo's CLAUDE.md is the only exception — it is the documented source of truth)
Tenant IDs
Connection strings
Any value that would cause harm if the repo were made public

settings.local.json is gitignored and may contain machine-specific paths, but still no credentials.