Skip to content

Repo settings — per-repo Claude Code configuration

Every repo has two layers of Claude Code configuration: a CLAUDE.md at the root (the context file) and a .claude/ folder (the behavior layer). Both are committed. A settings.local.json in .claude/ is gitignored for machine-specific overrides.

Full repo-level structure

<repo>/
├── CLAUDE.md                        ← context: purpose, structure, standards, actions
└── .claude/
    ├── agents/
    │   └── <repo-name>-engineer.md  ← repo-specific agent definition
    ├── settings.json                ← CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, pre-approved patterns
    └── settings.local.json          ← machine-specific overrides (gitignored)

CLAUDE.md — mandatory sections

Every repo's CLAUDE.md must include these sections. The template at templates/CLAUDE.md.template has all of them with {{PLACEHOLDER}} markers.

1. What this repo is

One to three paragraphs: what it does, why it exists, what it is not. Scope boundaries matter — be explicit.

2. ADO project details

- **ADO org:** https://dev.azure.com/hybridcloudsolutions
- **ADO project:** <Project Name>
- **Area path:** <Area Path>
- **Work item format:** AB#<id> in commit messages

3. Standards references

Link to platform standards — do not copy them. Example:

## Standards

This repo follows all HCS platform standards:
- Scripting: [docs/standards/scripting.md](<platform-repo-url>/docs/standards/scripting.md)
- Governance: [docs/standards/governance.md](<platform-repo-url>/docs/standards/governance.md)
- Documentation: [docs/standards/documentation.md](<platform-repo-url>/docs/standards/documentation.md)

4. Key facts

Facts Claude Code needs that are not derivable from the code: - Primary language and runtime version - Environment variables the repo expects (names only, never values) - Build, test, and serve commands - External dependencies or integration points

5. Repo structure

Top-level tree — two levels of depth is sufficient.

6. Claude Code actions

## Claude Code actions

**Run autonomously:**
- Read, search, grep any file in this repo
- Write and edit files in this repo
- Run scripts already committed to `scripts/`
- `git add`, `git commit`, `git push`
- <repo-specific additions>

**Always confirm before:**
- Creating or deleting Azure resources
- Any az CLI write operation
- Destructive operations
- <repo-specific additions>

7. Subagents available in this repo

End with this stanza so Claude Code knows which agents are available:

## Subagents available in this repo

- `<repo-name>-engineer` (model: sonnet) — <one-line purpose description>

User-level agents (available in every repo): triage-lookup, markdown-prose-editor,
azurelocal-domain-expert, mkdocs-material-doctor, turner-module-scaffold-engineer,
mms-2026-demo-presenter.

8. Owner

Name and email. Helps Claude Code calibrate tone and detail level.

.claude/settings.json — minimum content

Every repo .claude/settings.json must have at minimum:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "permissions": {
    "allow": [
      "Bash(git add:*)",
      "Bash(git commit -m ':*)",
      "Bash(git push:*)",
      "Bash(gh issue:*)",
      "Bash(gh pr:*)",
      "Bash(pwsh -NoProfile -Command ':*)",
      "Bash(pwsh -NoProfile -File ':*)"
    ]
  }
}

Add repo-specific patterns for build commands, test runners, and any other operations that would otherwise generate permission prompts. Patterns accumulate — add new ones as sessions surface permission prompts you want to pre-approve.

See templates/claude/settings.json.template for the full starting template.

.claude/settings.local.json — machine-specific overrides

This file is gitignored. Use it for: - Paths that differ per developer machine - Patterns for commands only you run locally (not part of the shared workflow) - Overriding behaviors that the committed settings.json sets

Do not put credentials or secrets here. Gitignored ≠ safe to commit sensitive values — gitignore can be overridden or misconfigured.

{
  "permissions": {
    "allow": [
      "Bash(pwsh -NonInteractive -File 'E:\\tmp\\my-local-script.ps1')"
    ]
  }
}

See templates/claude/settings.local.json.template for the structure.

.claude/agents/ — repo-specific agent

Most repos have one agent definition in .claude/agents/. The agent has deep knowledge of the repo's specific structure, conventions, and constraints that would be out of place in a user-level agent.

Agent files follow the format documented in agents. See templates/claude/agent.md.template for the starting template.

The agent name should follow the pattern <repo-name>-engineer for product repos or <repo-name>-curator for lightweight content/scratchpad repos. Use haiku for lightweight read-only agents; sonnet for everything else.

What must never appear in any CLAUDE.md

  • Secret values, tokens, passwords, connection strings
  • Subscription IDs (the platform repo CLAUDE.md is the only exception)
  • Tenant IDs, client IDs, client secrets
  • API keys
  • Any value that would cause harm if the repo became public

settings.local.json is gitignored but still must not contain credentials.

Template breakdown

The mandatory section order in templates/CLAUDE.md.template:

# {{REPO_NAME}} — Claude Code Context        ← H1: always this format

## What this repo is                          ← mandatory
## ADO project details                        ← mandatory
## Standards                                  ← mandatory (link to platform)
## Key facts                                  ← mandatory
## Repo structure                             ← mandatory
## Claude Code actions                        ← mandatory
## Subagents available in this repo           ← mandatory
## Owner                                      ← mandatory

Optional sections after the mandatory ones:

## Architecture notes                         ← non-obvious design decisions
## Known issues                               ← in-flight bugs or limitations
## External integrations                      ← if complex enough to need explanation

Using the template

  1. Copy templates/CLAUDE.md.template to the repo root as CLAUDE.md
  2. Replace every {{PLACEHOLDER}} with the correct value
  3. Copy templates/claude/settings.json.template to .claude/settings.json
  4. Copy templates/claude/agent.md.template to .claude/agents/<repo-name>-engineer.md
  5. Fill in the agent's system prompt
  6. Commit all three files before the first Claude Code session

Do not leave any {{PLACEHOLDER}} unfilled in a committed file — that is a defect.