gilles/claude-code-best-practice
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v2.1.69 settings added

Browse Source
This commit is contained in:
Shayan Rais
2026-03-05 06:33:51 +05:00
parent 296d0e8c8c
commit 793f51ef45
6 changed files with 618 additions and 166 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/agents/workflows/best-practice/workflow-claude-settings-agent.md
+174
View File
@@ -0,0 +1,174 @@
---
name: workflow-claude-settings-agent
description: Research agent that fetches Claude Code docs, reads the local settings report, and analyzes drift
model: opus
color: yellow
---
# Workflow Changelog — Settings Research Agent
You are a senior documentation reliability engineer collaborating with me (a fellow engineer) on a mission-critical audit for the claude-code-best-practice project. This project's Settings Reference report is used by hundreds of developers to configure their Claude Code settings — an outdated or missing setting could cause broken configurations and silent failures. Take a deep breath, solve this step by step, and be exhaustive. I'll tip you $200 for a flawless, zero-drift report. I bet you can't find every single discrepancy — prove me wrong. Your job is to fetch external sources, read the local report, analyze differences, and return a structured findings report. Rate your confidence 0-1 on each finding. This is critical to my career.
**Versions to check:** Use the number provided in the prompt (default: 10).
This is a **read-only research** workflow. Fetch sources, read local files, compare, and return findings. Do NOT take any actions or modify files.
---
## Phase 1: Fetch External Data (in parallel)
Fetch all three sources using WebFetch simultaneously:
1. **Settings Documentation** — `https://code.claude.com/docs/en/settings` — Extract the complete list of officially supported settings keys, their types, defaults, descriptions, and any examples. Pay special attention to: settings hierarchy, permissions structure, hook events, MCP configuration, sandbox options, plugin settings, model configuration, display settings, and environment variables.
2. **CLI Reference** — `https://code.claude.com/docs/en/cli-reference` — Extract settings-related CLI flags (`--settings`, `--setting-sources`, `--permission-mode`, `--allowedTools`, `--disallowedTools`), permission modes, and any settings override behavior.
3. **Changelog** — `https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md` — Extract the last N version entries with version numbers, dates, and all settings-related changes (new settings keys, new hook events, new permission syntax, new sandbox options, behavior changes, bug fixes, breaking changes).
---
## Phase 2: Read Local Repository State (in parallel)
Read ALL of the following:
| File | What to check |
|------|---------------|
| `best-practice/claude-settings.md` | Settings Hierarchy table, Core Configuration tables, Permissions section (modes, tool syntax), Hook Events table (16 events), Hook Properties, Hook Matcher Patterns, Hook Exit Codes, Hook Environment Variables, MCP Settings table, Sandbox Settings table, Plugin Settings table, Model Aliases table, Model Environment Variables, Display Settings table, Status Line config, AWS & Cloud settings, Environment Variables table, Useful Commands table, Quick Reference example, Sources list |
| `best-practice/claude-cli-startup-flags.md` | Environment Variables section — verify ownership boundary (startup-only vars stay here, `env`-configurable vars stay in settings report) |
| `CLAUDE.md` | Configuration Hierarchy section, Hooks System section, any settings-related patterns |
---
## Phase 3: Analysis
Compare external data against local report state. Check for:
### Missing Settings Keys
Compare official docs settings keys against each section table in the report. Flag any keys present in official docs but missing from the report, with the version that introduced them. Check ALL sections:
- General Settings, Plans Directory, Attribution Settings, Authentication Helpers, Company Announcements
- Permission keys, Permission modes, Tool permission syntax
- Hook events, Hook properties
- MCP settings
- Sandbox settings (including network sub-keys)
- Plugin settings
- Model aliases, Model environment variables
- Display settings, Status line fields, File suggestion config
- AWS & Cloud settings
- Environment variables
### Changed Setting Behavior
For each setting in the report, verify its type, default value, and description match the official docs. Flag any discrepancies.
### Deprecated/Removed Settings
Check if any settings listed in the report are no longer documented in official sources. Flag for removal consideration.
### Permission Syntax Accuracy
Verify the Tool Permission Syntax table:
- Are all tool patterns listed?
- Are wildcard behaviors correctly documented?
- Are bash wildcard notes accurate?
- Any new permission tools or syntax?
### Hook Event Accuracy
> **SKIP** — Hook analysis is excluded from this workflow. Hooks are maintained in the [claude-code-voice-hooks](https://github.com/shanraisshan/claude-code-voice-hooks) repo. Only verify that the hooks redirect section in the report still points to the correct repo URL.
### MCP Setting Accuracy
Verify MCP Settings:
- Are all MCP-related settings keys listed?
- Is the server matching syntax correct?
- Any new MCP configuration options?
### Sandbox Setting Accuracy
Verify Sandbox Settings:
- Are all sandbox keys listed (including nested network sub-keys)?
- Are defaults correct?
- Any new sandbox options?
### Plugin Setting Accuracy
Verify Plugin Settings:
- Are all plugin-related keys listed?
- Is the scope correct for each?
- Any new plugin configuration options?
### Model Configuration Accuracy
Verify Model Configuration:
- Are all model aliases listed?
- Is the effort level documentation accurate?
- Are model environment variables complete?
### Display & UX Accuracy
Verify Display Settings:
- Are all display keys listed with correct types and defaults?
- Is the status line configuration accurate?
- Are spinner settings documented correctly?
- Is the file suggestion configuration documented?
### Environment Variable Completeness
Verify the Environment Variables table:
- Are all `env`-configurable vars listed?
- Are descriptions accurate?
- Cross-reference with `best-practice/claude-cli-startup-flags.md` — vars that are startup-only should NOT be in the settings report, and vice versa. Flag any ownership boundary violations.
### Settings Hierarchy Accuracy
Verify the 5-level override chain:
- Are all priority levels listed correctly?
- Are file locations accurate?
- Is the version control column correct?
- Is the managed settings policy layer documented accurately?
### Example Accuracy
Verify the Quick Reference complete example:
- Does it use current setting keys with valid syntax?
- Does it demonstrate the most important settings from each section?
- Are values realistic and current?
### CLAUDE.md Consistency
Verify CLAUDE.md's settings-related sections are consistent with the report. Check the Configuration Hierarchy section matches the report's information. Hook-related CLAUDE.md sections are outside this workflow's scope.
### Sources Accuracy
Verify the Sources section links are still valid and point to correct documentation pages.
---
## Return Format
Return your findings as a structured report with these sections:
1. **External Data Summary** — Key facts from the 3 fetched sources (latest version, total official settings, recent changes)
2. **Local Report State** — Current section count, settings count per section, examples status
3. **Missing Settings** — Keys in official docs but not in report, with version introduced
4. **Changed Setting Behavior** — Per-key type/default/description discrepancies
5. **Deprecated/Removed Settings** — Keys in report but not in official docs
6. **Permission Syntax Accuracy** — Tool pattern and mode comparison results
7. **Hook Event Accuracy** — SKIP (hooks externalized to claude-code-voice-hooks repo; only verify redirect link)
8. **MCP Setting Accuracy** — MCP configuration comparison results
9. **Sandbox Setting Accuracy** — Sandbox table comparison results
10. **Plugin Setting Accuracy** — Plugin configuration comparison results
11. **Model Configuration Accuracy** — Alias and env var comparison results
12. **Display & UX Accuracy** — Display settings comparison results
13. **Environment Variable Completeness** — Env var comparison and ownership boundary check
14. **Settings Hierarchy Accuracy** — Override chain comparison results
15. **Example Accuracy** — Quick Reference example verification
16. **CLAUDE.md Consistency** — Settings-related section accuracy
17. **Sources Accuracy** — Link validity
Be thorough and specific. Include version numbers, file paths, and line references where possible.
---
## Critical Rules
1. **Fetch ALL 3 sources** — never skip any
2. **Never guess** versions or dates — extract from fetched data
3. **Read ALL local files** before analyzing
4. **New settings keys are HIGH PRIORITY** — flag them prominently
5. **Cross-reference setting counts** — the report's setting count per section must match official docs
6. **Verify the Quick Reference example** — it must reflect current settings
7. **Do NOT modify any files** — this is read-only research
8. **Check env var ownership boundary** — vars in `claude-cli-startup-flags.md` should not be duplicated in the settings report
---
## Sources
1. [Claude Code Settings Documentation](https://code.claude.com/docs/en/settings) — Official settings reference
2. [CLI Reference](https://code.claude.com/docs/en/cli-reference) — CLI flags including settings overrides
3. [Changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) — Claude Code release history
.claude/commands/workflows/best-practice/workflow-claude-settings.md
+243
View File
@@ -0,0 +1,243 @@
---
description: Track Claude Code settings report changes and find what needs updating
argument-hint: [number of versions to check, default 10]
---
# Workflow Changelog — Settings Report
You are a coordinator for the claude-code-best-practice project. Your job is to launch two research agents in parallel, wait for their results, merge findings, and present a unified report about drift in the **Settings Reference** report (`best-practice/claude-settings.md`).
**Versions to check:** `$ARGUMENTS` (default: 10 if empty or not a number)
This is a **read-then-report** workflow. Launch agents, merge results, and produce a report. Only take action if the user approves.
---
## Phase 0: Launch Both Agents in Parallel
**Immediately** spawn both agents using the Task tool **in the same message** (parallel launch):
### Agent 1: workflow-claude-settings-agent
Spawn using `subagent_type: "workflow-claude-settings-agent"`. Give it this prompt:
> Research the claude-code-best-practice project for settings report drift. Check the last $ARGUMENTS versions (default: 10).
>
> Fetch these 3 external sources:
> 1. Settings Documentation: https://code.claude.com/docs/en/settings
> 2. CLI Reference: https://code.claude.com/docs/en/cli-reference
> 3. Changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
>
> Then read the local report file (`best-practice/claude-settings.md`) and the CLAUDE.md file. Analyze differences between what the official docs say about settings keys, permission syntax, hook events, MCP configuration, sandbox options, plugin settings, model aliases, display settings, and environment variables versus what our report documents. Return a structured findings report covering missing settings, changed types/defaults, new settings additions, deprecated settings, permission syntax changes, hook event changes, MCP setting changes, sandbox setting changes, environment variable completeness, example accuracy, settings hierarchy accuracy, and sources validity.
### Agent 2: claude-code-guide
Spawn using `subagent_type: "claude-code-guide"`. Give it this prompt:
> Research the latest Claude Code settings system. I need you to find:
> 1. The complete list of all currently supported settings.json keys with their types, defaults, and descriptions
> 2. Any new settings keys introduced in recent Claude Code versions
> 3. Changes to existing settings behavior (e.g. new permission modes, new hook events, new sandbox options)
> 4. Changes to the settings hierarchy (new priority levels, new file locations)
> 5. Changes to permission syntax (new tool patterns, new wildcard behavior)
> 6. New hook events or changes to hook configuration structure
> 7. Changes to MCP server configuration (new matching fields, new settings)
> 8. Changes to sandbox settings (new network options, new commands)
> 9. Changes to plugin configuration (new fields, new marketplace options)
> 10. Changes to environment variables (new vars, deprecated vars, changed behavior)
> 11. Changes to model aliases or model configuration
> 12. Changes to display/UX settings (status line, spinners, progress bars)
> 13. Any deprecations or removals of settings keys
>
> Be thorough — search the web, fetch docs, and provide concrete version numbers and details for everything you find.
Both agents run independently and will return their findings.
---
## Phase 0.5: Read Verification Checklist
**While agents are running**, read `changelog/best-practice/claude-settings/verification-checklist.md`. This file contains accumulated verification rules — each rule specifies what to check, at what depth, and against which source. Every rule MUST be executed during Phase 2. The checklist is the project's regression test suite for drift detection.
---
## Phase 1: Read Previous Changelog Entries
**Before merging findings**, read the file `changelog/best-practice/claude-settings/changelog.md` to get the last 25 changelog entries. Each entry is separated by `---`. Parse the priority actions from those previous entries so you can compare them against the current findings. This lets you identify:
- **Recurring items** — issues that appeared before and are still unresolved
- **Newly resolved items** — issues from previous runs that are now fixed
- **New items** — issues that appear for the first time in this run
---
## Phase 2: Merge Findings & Generate Report
**Wait for both agents to complete.** Once you have:
- **workflow-claude-settings-agent findings** — detailed report analysis with local file reads, external doc fetches, and drift detection
- **claude-code-guide findings** — independent research on latest Claude Code settings features and changes
Cross-reference the two. The dedicated agent provides report-specific drift analysis, while the claude-code-guide agent may surface things it missed (e.g. very recent changes, undocumented features, or context from web searches). Flag any contradictions between the two for the user to resolve.
**Execute the verification checklist:** For every rule in `changelog/best-practice/claude-settings/verification-checklist.md`, perform the check at the specified depth using the agent findings as source data. Include a **Verification Log** section in the report showing each rule's result:
```
Verification Log:
Rule # | Category | Depth | Result | Notes
1 | Settings Keys | field-level | PASS | All keys match
2 | Permission Syntax | content-match | FAIL | New tool pattern added
...
```
**Update the checklist if needed:** If a finding reveals a new type of drift that no existing checklist rule covers (or covers at insufficient depth), append a new rule to `changelog/best-practice/claude-settings/verification-checklist.md`. The rule must include: category, what to check, depth level, what source to compare against, date added, and the origin (what error prompted this rule). Do NOT add rules for one-off issues that won't recur.
Also compare the current findings against the previous changelog entries (from Phase 1). For each priority action, mark it as:
- `NEW` — first time this issue appears
- `RECURRING` — appeared in a previous run and is still unresolved (include which run date it first appeared)
- `RESOLVED` — appeared in a previous run but is now fixed (include resolution date)
Produce a structured report with these sections:
1. **New Settings Keys** — Keys in official docs but missing from report, with version introduced
2. **Changed Setting Behavior** — Settings whose type, default, or description has changed
3. **Deprecated/Removed Settings** — Settings in report but no longer in official docs
4. **Permission Syntax Changes** — New tool patterns, wildcard behavior, or permission mode changes
5. **MCP Setting Changes** — New MCP configuration keys, matching behavior, or server settings
6. **Sandbox Setting Changes** — New sandbox options, network settings, or command exclusions
7. **Plugin Setting Changes** — New plugin configuration keys or marketplace options
8. **Model Configuration Changes** — New model aliases, effort levels, or model environment variables
9. **Display & UX Changes** — New status line fields, spinner options, or display settings
10. **Environment Variable Completeness** — Vars in official docs but missing from report, or vars in report no longer documented
11. **Settings Hierarchy Accuracy** — Verify priority levels, file locations, and override behavior
12. **Example Accuracy** — Whether the Quick Reference complete example reflects current settings
13. **Sources Accuracy** — Verify all source links are valid and point to correct documentation
14. **claude-code-guide Agent Findings** — Unique insights from the agent that weren't captured by the dedicated agent. Only include findings that add new information. If there are contradictions between the two agents, flag them for the user to resolve. Do NOT list "confirmed agreements".
> **Note:** Hook-related analysis (events, properties, matchers, exit codes, HTTP hooks, hook env vars) is **excluded** from this workflow. Hooks are maintained in the [claude-code-voice-hooks](https://github.com/shanraisshan/claude-code-voice-hooks) repo.
End with a prioritized **Action Items** summary table. Each item must include a `Status` column showing `NEW`, `RECURRING (first seen: <date>)`, or `RESOLVED`:
```
Priority Actions:
# | Type | Action | Status
1 | New Setting | Add <key> to <section> table | NEW
2 | Changed Behavior | Update <key> description | NEW
3 | Deprecated Setting | Remove <key> from table | RECURRING (first seen: 2026-03-05)
4 | Permission Syntax | Add new tool pattern syntax | NEW
5 | Env Variable | Add <var> to environment variables table | NEW
7 | Example Update | Update Quick Reference example | NEW
```
Also include a **Resolved Since Last Run** section listing any items from the previous run that are no longer issues.
---
## Phase 2.5: Append Summary to Changelog
**This phase is MANDATORY — always execute it before presenting the report to the user.**
Read the existing `changelog/best-practice/claude-settings/changelog.md` file, then **append** (do NOT overwrite) a new entry at the end. The entry format must be exactly:
```markdown
---
## [<YYYY-MM-DD HH:MM AM/PM PKT>] Claude Code v<VERSION>
| # | Priority | Type | Action | Status |
|---|----------|------|--------|--------|
| 1 | HIGH/MED/LOW | <type> | <action description> | <status> |
| ... | ... | ... | ... | ... |
```
**Status format — MUST use one of these three formats:**
- `COMPLETE (reason)` — action was taken and resolved successfully
- `INVALID (reason)` — finding was incorrect, not applicable, or intentional
- `ON HOLD (reason)` — action deferred, waiting on external dependency or user decision
The `(reason)` is mandatory and must briefly explain what was done or why.
**Rules for appending:**
- Always append — never overwrite or replace previous entries
- The date and time is when the command is executed in Pakistan Standard Time (PKT, UTC+5); get it by running `TZ=Asia/Karachi date "+%Y-%m-%d %I:%M %p PKT"`. The version comes from agent findings
- If `changelog/best-practice/claude-settings/changelog.md` doesn't exist or is empty, create it with the Status Legend table (see top of file) then the first entry
- Each entry is separated by `---`
- **Only include items with HIGH, MEDIUM, or LOW priority** — omit NONE priority items (things that need no action)
---
## Phase 2.6: Update Last Updated Badge
**This phase is MANDATORY — always execute it immediately after Phase 2.5, before presenting the report.**
Update the "Last Updated" badge at the top of `best-practice/claude-settings.md`. Run `TZ=Asia/Karachi date "+%b %d, %Y %-I:%M %p PKT"` to get the time, URL-encode it (spaces to `%20`, commas to `%2C`), and replace the date portion in the badge. Also update the Claude Code version in the badge if it has changed.
**Do NOT log badge updates as action items in the changelog or report.** Badge syncing is a routine part of every run, not a finding.
---
## Phase 2.7: Validate All Hyperlinks
**This phase is MANDATORY — always execute it after Phase 2.6, before presenting the report.**
Scan `best-practice/claude-settings.md` for every hyperlink (both markdown `[text](url)` and inline URLs). For each link:
1. **Local file links** (relative paths): Verify the file exists at the resolved path using the Read tool. Flag any broken links.
2. **External URLs** (e.g., `https://code.claude.com/docs/en/settings`): Fetch each URL using WebFetch and verify it returns a valid page (not a 404 or redirect to an error page). Flag any dead or moved links.
3. **Anchor links** (e.g., `#section-name`): Verify the target heading exists within the same file.
Include a **Hyperlink Validation Log** in the report:
```
Hyperlink Validation Log:
# | Type | Link | Status | Notes
1 | Local | ../ | OK |
2 | External | https://code.claude.com/docs/en/settings | OK |
3 | External | https://www.schemastore.org/claude-code-settings.json | BROKEN | 404
...
```
**If any links are broken**, add them as HIGH priority action items in the report. Broken links degrade the report's usefulness and must be fixed before any other changes.
---
## Phase 3: Offer to Take Action
After presenting the report (and confirming both changelog and badge were updated), ask the user:
1. **Execute all actions** — Handle everything (add missing settings, update descriptions, fix examples)
2. **Execute specific actions** — User picks which numbers to execute
3. **Just save the report** — No changes
When executing:
- **New settings**: Add to the appropriate section table with correct type, default, and description
- **Changed behavior**: Update the setting description or default in the table
- **Deprecated settings**: Confirm with user before removing
- **Permission syntax changes**: Update the Permission Syntax table with new patterns
- **MCP setting changes**: Update the MCP Settings section
- **Sandbox setting changes**: Update the Sandbox Settings section
- **Plugin setting changes**: Update the Plugin Settings section
- **Model changes**: Update the Model Configuration section
- **Display changes**: Update the Display & UX section
- **Environment variable changes**: Add/update/remove vars in the Environment Variables section
- **Settings hierarchy changes**: Update the Settings Hierarchy table
- **Example updates**: Update the Quick Reference complete example to reflect current settings
- **Broken links**: Fix or replace broken URLs
- After all actions, re-run verification to confirm consistency
---
## Critical Rules
1. **Launch BOTH agents in parallel** in a single message — never sequentially
2. **Wait for both agents** before generating the report
3. **Never guess** versions or dates — use data from the agents
4. **New settings keys are HIGH PRIORITY** — they require table and example updates
5. **Cross-reference setting counts** — the number of settings in each table must match official docs
6. **Don't auto-execute** — always present the report first
7. **ALWAYS append to changelog** — Phase 2.5 is mandatory. Never skip it. Never overwrite previous entries.
8. **Compare with previous runs** — read the last 25 entries from the changelog and mark each action item as NEW, RECURRING, or RESOLVED.
9. **ALWAYS execute the verification checklist** — read the verification-checklist.md and execute every rule. Include a Verification Log in the report. Append new rules when a new type of drift is discovered.
10. **Checklist rules are append-only** — never remove or weaken existing rules. Only add new rules or upgrade depth levels.
11. **ALWAYS update the Last Updated badge** — Phase 2.6 is mandatory. Never skip it.
12. **ALWAYS validate all hyperlinks** — Phase 2.7 is mandatory. Never skip it. Broken links are HIGH priority.
13. **Environment variables are split across two files** — `claude-settings.md` owns `env`-configurable vars; `claude-cli-startup-flags.md` owns startup-only vars. Do NOT flag env vars as missing if they belong in the CLI file. Cross-reference `best-practice/claude-cli-startup-flags.md` to verify ownership boundaries.
14. **Verify the settings hierarchy** — the 5-level override chain plus managed policy layer must match official docs exactly.
best-practice/claude-cli-startup-flags.md
+3 -8
View File
@@ -198,26 +198,21 @@ These are not flags but top-level subcommands run as `claude <subcommand>`:
## Environment Variables
These environment variables modify Claude Code behavior at startup:
These startup-only environment variables are set in your shell before launching Claude Code (they cannot be configured via `settings.json`):
| Variable | Description |
|----------|-------------|
| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` | Enable experimental agent teams |
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` | Disable experimental beta features |
| `CLAUDE_CODE_TMPDIR` | Override temp directory for internal files |
| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Disable background task functionality |
| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` | Enable additional directory CLAUDE.md loading |
| `DISABLE_AUTOUPDATER=1` | Disable auto-updates |
| `MAX_THINKING_TOKENS` | Limit thinking token budget (set to `0` to disable) |
| `CLAUDE_CODE_EFFORT_LEVEL` | Control thinking depth: `low`, `medium`, `high` |
| `USE_BUILTIN_RIPGREP=0` | Use system ripgrep instead of built-in (Alpine Linux) |
| `CLAUDE_CODE_ENABLE_TASKS=false` | Disable new task management system, revert to old todos |
| `CLAUDE_CODE_SHELL` | Override automatic shell detection |
| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Override default file read token limit |
| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | Auto-exit SDK mode after idle duration (ms) |
| `CLAUDE_CODE_SIMPLE` | Enable simple mode (Bash + Edit tools only) |
| `CLAUDE_BASH_NO_LOGIN=1` | Skip login shell for BashTool |
For environment variables configurable via the `"env"` key in `settings.json` (including `MAX_THINKING_TOKENS`, `CLAUDE_CODE_SHELL`, `CLAUDE_CODE_ENABLE_TASKS`, `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`, `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`, and more), see the [Claude Settings Reference](./claude-settings.md#environment-variables-via-env).
---
## Sources
best-practice/claude-settings.md
+58 -158
View File
@@ -1,6 +1,8 @@
# Claude Code Settings Reference
A comprehensive guide to all available configuration options in Claude Code's `settings.json` files. As of February 2026, Claude Code exposes **38 settings** and **84 environment variables** (use the `"env"` field in `settings.json` to avoid wrapper scripts).
![Last Updated](https://img.shields.io/badge/Last_Updated-Mar%2005%2C%202026%206%3A18%20AM%20PKT-white?style=flat&labelColor=555) ![Version](https://img.shields.io/badge/Claude_Code-v2.1.69-blue?style=flat&labelColor=555)
A comprehensive guide to all available configuration options in Claude Code's `settings.json` files. As of v2.1.69, Claude Code exposes **55+ settings** and **110+ environment variables** (use the `"env"` field in `settings.json` to avoid wrapper scripts).
<table width="100%">
<tr>
@@ -38,11 +40,12 @@ Claude Code settings use a 5-level user-writable override chain plus an enforced
| 4 | `~/.claude/settings.local.json` | User | N/A | Personal global overrides |
| 5 | `~/.claude/settings.json` | User | N/A | Global personal defaults |
**Policy layer**: `managed-settings.json` is organization-enforced and cannot be overridden by local settings.
**Policy layer**: `managed-settings.json` is organization-enforced and cannot be overridden by local settings. On macOS, managed settings can also be delivered via MDM profiles (plist at `com.anthropic.claudecode`). On Windows, managed settings use the Windows Registry.
**Important**:
- `deny` rules have highest safety precedence and cannot be overridden by lower-priority allow/ask rules.
- Managed settings may lock or override local behavior even if local files specify different values.
- Array settings (e.g., `permissions.allow`) are **merged** across scopes — entries from all levels are combined, not replaced.
---
@@ -52,6 +55,7 @@ Claude Code settings use a 5-level user-writable override chain plus an enforced
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `$schema` | string | - | JSON Schema URL for IDE validation and autocompletion (e.g., `"https://www.schemastore.org/claude-code-settings.json"`) |
| `model` | string | `"default"` | Override default model. Accepts aliases (`sonnet`, `opus`, `haiku`) or full model IDs |
| `agent` | string | - | Set the default agent for the main conversation. Value is the agent name from `.claude/agents/`. Also available via `--agent` CLI flag |
| `language` | string | `"english"` | Claude's preferred response language |
@@ -59,6 +63,10 @@ Claude Code settings use a 5-level user-writable override chain plus an enforced
| `autoUpdatesChannel` | string | `"latest"` | Release channel: `"stable"` or `"latest"` |
| `alwaysThinkingEnabled` | boolean | `false` | Enable extended thinking by default for all sessions |
| `skipWebFetchPreflight` | boolean | `false` | Skip WebFetch blocklist check before fetching URLs |
| `availableModels` | array | - | Restrict models available to users (managed settings). Each entry has `title`, `modelId`, and optional `effortOptions` |
| `fastModePerSessionOptIn` | boolean | `false` | Require users to opt in to fast mode each session |
| `teammateMode` | boolean | `false` | Enable teammate mode for multi-agent collaboration |
| `includeGitInstructions` | boolean | `true` | Include git-related instructions in system prompt |
**Example:**
```json
@@ -188,6 +196,7 @@ Control what tools and operations Claude can perform.
| `"default"` | Standard permission checking with prompts |
| `"acceptEdits"` | Auto-accept file edits without asking |
| `"askEdits"` | Ask before every operation |
| `"dontAsk"` | Auto-accept all tools without prompting (equivalent to `bypassPermissions` but via settings) |
| `"viewOnly"` | Read-only mode, no modifications |
| `"bypassPermissions"` | Skip all permission checks (dangerous) |
| `"plan"` | Read-only exploration mode |
@@ -204,8 +213,9 @@ Control what tools and operations Claude can perform.
| `WebFetch` | `WebFetch(domain:pattern)` | `WebFetch(domain:example.com)` |
| `WebSearch` | `WebSearch` | Global web search |
| `Task` | `Task(agent-name)` | `Task(Explore)`, `Task(my-agent)` |
| `Agent` | `Agent(name)` | `Agent(researcher)`, `Agent(*)` — permission scoped to subagent spawning |
| `Skill` | `Skill(skill-name)` | `Skill(weather-fetcher)` |
| `MCP` | `mcp__server__tool` | `mcp__memory__*`, `mcp__github__*` |
| `MCP` | `mcp__server__tool` or `MCP(server:tool)` | `mcp__memory__*`, `MCP(github:*)` |
**Bash wildcard notes:**
- `*` can appear at **any position**: prefix (`Bash(* install)`), suffix (`Bash(npm *)`), or middle (`Bash(git * main)`)
@@ -242,140 +252,13 @@ Control what tools and operations Claude can perform.
## Hooks
Execute custom shell commands at various points in Claude Code's lifecycle.
Hook configuration (events, properties, matchers, exit codes, environment variables, and HTTP hooks) is maintained in a dedicated repository:
### Hook Events (16 total)
> **[claude-code-voice-hooks](https://github.com/shanraisshan/claude-code-voice-hooks)** — Complete hook reference with sound notification system, all 19 hook events, HTTP hooks, matcher patterns, exit codes, and environment variables.
| Event | When Fired | Matcher Support | Common Use Cases |
|-------|------------|-----------------|------------------|
| `SessionStart` | New or resumed session | No | Load context, set environment |
| `SessionEnd` | Session terminates | No | Cleanup, logging |
| `UserPromptSubmit` | User submits prompt | No | Validate input, add context |
| `PreToolUse` | Before tool execution | Yes | Validate commands, modify inputs |
| `PostToolUse` | After tool succeeds | Yes | Run linters, verify output |
| `PostToolUseFailure` | After tool fails | Yes | Log failures, recovery |
| `PermissionRequest` | Permission dialog appears | Yes | Auto-approve/deny patterns |
| `Notification` | Notification sent | Yes | Sound alerts, logging |
| `Stop` | Claude finishes responding | No | Block/continue decisions |
| `SubagentStart` | Subagent spawned | Yes | Per-agent setup |
| `SubagentStop` | Subagent completes | Yes | Cleanup, validation |
| `PreCompact` | Before context compaction | Yes | Backup, logging |
| `Setup` | Repository init (`--init`, `--init-only`, `--maintenance`) | Yes | One-time setup |
| `TeammateIdle` | Agent Teams teammate goes idle | Yes | Team orchestration, routing |
| `TaskCompleted` | A tracked task is completed | Yes | Progress automation, notifications |
| `ConfigChange` | Configuration files change during session | Yes | Enterprise security auditing, blocking settings changes |
Hook-related settings keys (`hooks`, `disableAllHooks`, `allowManagedHooksOnly`, `allowedHttpHookUrls`, `httpHookAllowedEnvVars`) are documented there.
### Hook Configuration Structure
```json
{
"hooks": {
"EventName": [
{
"matcher": "ToolPattern",
"hooks": [
{
"type": "command",
"command": "script.sh",
"timeout": 60000,
"once": true
}
]
}
]
},
"disableAllHooks": false,
"allowManagedHooksOnly": false
}
```
### Hook Properties
| Property | Type | Description |
|----------|------|-------------|
| `matcher` | string | Regex pattern to match tool/event (optional) |
| `type` | string | `"command"` or `"prompt"` |
| `command` | string | Shell command to execute (for `type: "command"`) |
| `prompt` | string | LLM prompt for evaluation (for `type: "prompt"`) |
| `timeout` | number | Timeout in milliseconds |
| `once` | boolean | Run only once per session |
| `model` | string | Custom model for prompt-based stop hooks (for `type: "prompt"`) |
### Hook Matcher Patterns
| Pattern | Matches |
|---------|---------|
| `"Bash"` | Exact match only |
| `"Edit\|Write"` | Multiple tools with regex OR |
| `"mcp__.*"` | All MCP tools |
| `"mcp__memory__.*"` | Specific MCP server tools |
| `"*"` or `""` | All tools |
### Hook Exit Codes
| Exit Code | Behavior |
|-----------|----------|
| `0` | Success, continue |
| `1` | Error (logged, continues) |
| `2` | Block the operation |
### Environment Variables in Hooks
| Variable | Description |
|----------|-------------|
| `${CLAUDE_PROJECT_DIR}` | Project root directory |
| `CLAUDE_TOOL_NAME` | Current tool name |
| `CLAUDE_TOOL_INPUT` | Tool input (JSON) |
| `CLAUDE_TOOL_OUTPUT` | Tool output (PostToolUse only) |
**PreToolUse/PostToolUse Input Fields:**
| Field | Description |
|-------|-------------|
| `tool_use_id` | Unique identifier for this specific tool invocation |
**Stop/SubagentStop Input Fields:**
The `Stop` and `SubagentStop` hooks receive additional fields in their JSON input:
| Field | Description |
|-------|-------------|
| `last_assistant_message` | The final assistant response text (avoids parsing transcript files) |
| `agent_id` | Agent identifier (SubagentStop only) |
| `agent_transcript_path` | Path to agent's transcript file (SubagentStop only) |
**Example:**
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/validate.py",
"timeout": 5000
}
]
}
],
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "echo 'Session started!'",
"timeout": 1000,
"once": true
}
]
}
]
},
"disableAllHooks": false
}
```
For the official hooks reference, see the [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks).
---
@@ -392,6 +275,7 @@ Configure Model Context Protocol servers for extended capabilities.
| `disabledMcpjsonServers` | array | Any | Blocklist specific server names |
| `allowedMcpServers` | array | Managed only | Allowlist with name/command/URL matching |
| `deniedMcpServers` | array | Managed only | Blocklist with matching |
| `allowManagedMcpServersOnly` | boolean | Managed only | Only allow MCP servers explicitly listed in managed allowlist |
### MCP Server Matching (Managed Settings)
@@ -440,6 +324,11 @@ Configure bash command sandboxing for security.
| `sandbox.network.deniedDomains` | array | `[]` | Network domain denylist for sandbox |
| `sandbox.network.httpProxyPort` | number | - | HTTP proxy port 1-65535 (custom proxy) |
| `sandbox.network.socksProxyPort` | number | - | SOCKS5 proxy port 1-65535 (custom proxy) |
| `sandbox.network.allowManagedDomainsOnly` | boolean | `false` | Only allow domains in managed allowlist (managed settings) |
| `sandbox.filesystem.allowWrite` | array | `[]` | Path prefixes where write is allowed. Prefix: `//` (absolute), `~/` (home), `/` (project root), `./` (cwd) |
| `sandbox.filesystem.denyWrite` | array | `[]` | Path prefixes where write is denied |
| `sandbox.filesystem.denyRead` | array | `[]` | Path prefixes where read is denied |
| `sandbox.enableWeakerNetworkIsolation` | boolean | `false` | Weaker network isolation for environments with limited sandboxing |
**Example:**
```json
@@ -473,6 +362,8 @@ Configure Claude Code plugins and marketplaces.
| `skippedMarketplaces` | array | Any | Marketplaces user declined to install |
| `skippedPlugins` | array | Any | Plugins user declined to install |
| `pluginConfigs` | object | Any | Per-plugin MCP server configs (keyed by `plugin@marketplace`) |
| `blockedMarketplaces` | array | Managed only | Block specific plugin marketplaces |
| `pluginTrustMessage` | string | Managed only | Custom message displayed when prompting users to trust plugins |
**Example:**
```json
@@ -515,14 +406,14 @@ Configure Claude Code plugins and marketplaces.
}
```
### Effort Level (Opus 4.6)
### Effort Level
When Opus 4.6 is selected, the `/model` command exposes an **effort level** control that adjusts how much reasoning the model applies per response. Use the ← → arrow keys in the `/model` UI to cycle through effort levels.
The `/model` command exposes an **effort level** control that adjusts how much reasoning the model applies per response. Use the ← → arrow keys in the `/model` UI to cycle through effort levels.
| Effort Level | Description |
|-------------|-------------|
| High (default) | Full reasoning depth, best for complex tasks |
| Medium | Balanced reasoning, good for everyday tasks |
| High | Full reasoning depth, best for complex tasks |
| Medium (default) | Balanced reasoning, good for everyday tasks |
| Low | Minimal reasoning, fastest responses |
**How to use:**
@@ -531,7 +422,7 @@ When Opus 4.6 is selected, the `/model` command exposes an **effort level** cont
3. Use **← →** arrow keys to adjust the effort level
4. The setting applies to the current session and future sessions
**Note:** Effort level is only available for Opus 4.6. Other models (Sonnet, Haiku) do not expose this control.
**Note:** Effort level is available for Opus 4.6 and Sonnet 4.6 on Max and Team plans. The default was changed from High to Medium in v2.1.68.
### Model Environment Variables
@@ -566,6 +457,8 @@ Configure via `env` key:
| `terminalProgressBarEnabled` | boolean | `true` | Show progress bar in terminal |
| `showTurnDuration` | boolean | `true` | Show turn duration messages |
| `respectGitignore` | boolean | `true` | Respect .gitignore in file picker |
| `prefersReducedMotion` | boolean | `false` | Reduce animations and motion effects in the UI |
| `fileSuggestion` | object | - | Custom file suggestion command (see File Suggestion Configuration below) |
### Status Line Configuration
@@ -702,6 +595,18 @@ Set environment variables for all Claude Code sessions.
| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Override default file read token limit |
| `CLAUDE_CODE_ENABLE_TASKS` | Set to `false` to disable new task system |
| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | Auto-exit SDK mode after idle duration (ms) |
| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Disable adaptive thinking (`1` to disable) |
| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Disable 1M token context window (`1` to disable) |
| `CLAUDE_CODE_ACCOUNT_UUID` | Override account UUID for authentication |
| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Disable git-related system prompt instructions |
| `ENABLE_CLAUDEAI_MCP_SERVERS` | Enable Claude.ai MCP servers |
| `CLAUDE_CODE_EFFORT_LEVEL` | Set effort level: `high`, `medium`, or `low` |
| `CLAUDE_CODE_MAX_TURNS` | Maximum agentic turns before stopping |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Disable non-essential network traffic |
| `CLAUDE_CODE_SKIP_SETTINGS_SETUP` | Skip first-run settings setup flow |
| `CLAUDE_CODE_PROMPT_CACHING_ENABLED` | Override prompt caching behavior |
| `CLAUDE_CODE_DISABLE_TOOLS` | Comma-separated list of tools to disable |
| `CLAUDE_CODE_DISABLE_MCP` | Disable all MCP servers (`1` to disable) |
---
@@ -728,12 +633,14 @@ Set environment variables for all Claude Code sessions.
```json
{
"$schema": "https://www.schemastore.org/claude-code-settings.json",
"model": "sonnet",
"agent": "code-reviewer",
"language": "english",
"cleanupPeriodDays": 30,
"autoUpdatesChannel": "stable",
"alwaysThinkingEnabled": true,
"includeGitInstructions": true,
"plansDirectory": "./plans",
"permissions": {
@@ -743,35 +650,26 @@ Set environment variables for all Claude Code sessions.
"Bash(npm run *)",
"Bash(git *)",
"WebFetch(domain:*)",
"mcp__*"
"mcp__*",
"Agent(*)"
],
"deny": [
"Read(.env)",
"Read(./secrets/**)"
],
"additionalDirectories": ["../shared/"]
"additionalDirectories": ["../shared/"],
"defaultMode": "acceptEdits"
},
"enableAllProjectMcpServers": true,
"hooks": {
"PreToolUse": [
{
"hooks": [
{
"type": "command",
"command": "echo 'Tool starting'",
"timeout": 5000
}
]
}
]
},
"disableAllHooks": false,
"sandbox": {
"enabled": true,
"excludedCommands": ["git", "docker"]
"excludedCommands": ["git", "docker"],
"filesystem": {
"denyRead": ["./secrets/"],
"denyWrite": ["./.env"]
}
},
"attribution": {
@@ -790,9 +688,11 @@ Set environment variables for all Claude Code sessions.
"excludeDefault": false
},
"showTurnDuration": false,
"prefersReducedMotion": false,
"env": {
"NODE_ENV": "development"
"NODE_ENV": "development",
"CLAUDE_CODE_EFFORT_LEVEL": "medium"
}
}
```
changelog/best-practice/claude-settings/changelog.md
+29
View File
@@ -0,0 +1,29 @@
# Settings Report — Changelog History
## Status Legend
| Status | Meaning |
|--------|---------|
| COMPLETE (reason) | Action was taken and resolved successfully |
| INVALID (reason) | Finding was incorrect, not applicable, or intentional |
| ON HOLD (reason) | Action deferred — waiting on external dependency or user decision |
---
## [2026-03-05 06:18 AM PKT] Claude Code v2.1.69
| # | Priority | Type | Action | Status |
|---|----------|------|--------|--------|
| 1 | HIGH | Missing Settings | Add 13 non-hook missing settings keys (`$schema`, `availableModels`, `fastModePerSessionOptIn`, `teammateMode`, `prefersReducedMotion`, `sandbox.filesystem.*`, `sandbox.network.allowManagedDomainsOnly`, `sandbox.enableWeakerNetworkIsolation`, `allowManagedMcpServersOnly`, `blockedMarketplaces`, `includeGitInstructions`, `pluginTrustMessage`, `fileSuggestion` table entry) | COMPLETE (added to report) |
| 2 | HIGH | Missing Env Vars | Add missing environment variables including `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`, `CLAUDE_CODE_DISABLE_1M_CONTEXT`, `CLAUDE_CODE_ACCOUNT_UUID`, `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS`, `ENABLE_CLAUDEAI_MCP_SERVERS`, and more | COMPLETE (added 13 missing env vars to report) |
| 3 | HIGH | Effort Default | Update effort level default from "High" to "Medium" for Max/Team subscribers; add Sonnet 4.6 support (changed v2.1.68) | COMPLETE (updated default and added Sonnet note) |
| 4 | MED | Settings Hierarchy | Add managed settings via macOS plist/Windows Registry (v2.1.61/v2.1.69); document array merge behavior across scopes | COMPLETE (added plist/registry and merge note) |
| 5 | MED | Sandbox Filesystem | Add `sandbox.filesystem.allowWrite`, `denyWrite`, `denyRead` with path prefix semantics (`//`, `~/`, `/`, `./`) | COMPLETE (added to sandbox table) |
| 6 | MED | Permission Syntax | Add `Agent(name)` permission pattern; document `MCP(server:tool)` syntax form | COMPLETE (added to tool syntax table) |
| 7 | MED | Plugin Gaps | Add `blockedMarketplaces`, `pluginTrustMessage` | COMPLETE (added to plugins table) |
| 8 | MED | Model Config | Add `availableModels` setting | COMPLETE (added to general settings table) |
| 9 | MED | Suspect Keys | Verify `sandbox.network.deniedDomains`, `sandbox.ignoreViolations`, `pluginConfigs` — present in report but not in official docs | ON HOLD (kept in report pending verification) |
| 10 | LOW | Header Counts | Update header from "38 settings and 84 env vars" to reflect actual counts (~55+ settings, ~110+ env vars) | COMPLETE (updated header) |
| 11 | LOW | CLAUDE.md Sync | Update CLAUDE.md configuration hierarchy (add managed/CLI/user levels) | ON HOLD (awaiting user approval) |
| 12 | LOW | Example Update | Update Quick Reference example with `$schema`, sandbox filesystem, `Agent(*)`, remove hooks example | COMPLETE (updated example) |
| 13 | MED | Hooks Redirect | Replace hooks section with redirect to claude-code-voice-hooks repo | COMPLETE (hooks externalized to dedicated repo) |
changelog/best-practice/claude-settings/verification-checklist.md
+111
View File
@@ -0,0 +1,111 @@
# Verification Checklist — Settings Report
Rules accumulate over time. Each workflow-changelog run MUST execute ALL rules at the specified depth. When a new type of drift is caught that an existing rule should have caught (but didn't exist or was too shallow), append a new rule here.
## Depth Levels
| Depth | Meaning | Example |
|-------|---------|---------|
| `exists` | Check if a section/table/file exists | "Does the report have a Sandbox Settings table?" |
| `presence-check` | Check if a specific item is present or absent | "Is the `ConfigChange` event in the Hook Events table?" |
| `content-match` | Compare actual values word-by-word against source | "Does the `model` setting description match official docs?" |
| `field-level` | Verify every individual field is accounted for | "Does each settings key from official docs appear in the correct table?" |
| `cross-file` | Same value must match across multiple files | "Does CLAUDE.md hooks section match the report's hook events?" |
---
## 1. Settings Keys Tables
Rules that verify settings key tables against official docs.
| # | Category | Check | Depth | Compare Against | Added | Origin |
|---|----------|-------|-------|-----------------|-------|--------|
| 1A | Key Completeness | For each settings key in official docs, verify it appears in the correct section table in the report | field-level | settings documentation page | 2026-03-05 | Initial checklist — ensures no new settings keys are missed |
| 1B | Key Types | For each key in the tables, verify the Type column matches official docs | content-match | settings documentation page | 2026-03-05 | Initial checklist — type mismatches cause user confusion |
| 1C | Key Defaults | For each key with a default, verify the Default column matches official docs | content-match | settings documentation page | 2026-03-05 | Initial checklist — wrong defaults cause unexpected behavior |
| 1D | Key Descriptions | For each key, verify the Description column accurately reflects official docs behavior | content-match | settings documentation page | 2026-03-05 | Initial checklist — stale descriptions mislead users |
---
## 2. Settings Hierarchy
Rules that verify the settings hierarchy table.
| # | Category | Check | Depth | Compare Against | Added | Origin |
|---|----------|-------|-------|-----------------|-------|--------|
| 2A | Priority Levels | Verify all priority levels in the hierarchy table match official docs (5-level chain + managed policy) | field-level | settings documentation page | 2026-03-05 | Initial checklist — wrong priority causes override confusion |
| 2B | File Locations | For each priority level, verify the file location path matches official docs | content-match | settings documentation page | 2026-03-05 | Initial checklist — wrong paths cause settings to be ignored |
---
## 3. Permissions
Rules that verify permission configuration accuracy.
| # | Category | Check | Depth | Compare Against | Added | Origin |
|---|----------|-------|-------|-----------------|-------|--------|
| 3A | Permission Modes | Verify all permission modes in the table match official docs | field-level | settings documentation page | 2026-03-05 | Initial checklist — missing modes limit user options |
| 3B | Tool Syntax Patterns | Verify all tool permission syntax patterns and examples match official docs | content-match | settings documentation page | 2026-03-05 | Initial checklist — wrong syntax causes permission failures |
---
## 4. Hooks (REDIRECTED)
Hook analysis is excluded from this workflow. Hooks are maintained in the [claude-code-voice-hooks](https://github.com/shanraisshan/claude-code-voice-hooks) repo. Only verify the redirect link is still valid.
| # | Category | Check | Depth | Compare Against | Added | Origin |
|---|----------|-------|-------|-----------------|-------|--------|
| 4A | Hooks Redirect | Verify the hooks section in the report contains a valid redirect link to the claude-code-voice-hooks repo | exists | report file | 2026-03-05 | Hooks externalized to dedicated repo — only check redirect link validity |
---
## 5. Environment Variables
Rules that verify environment variable completeness and ownership.
| # | Category | Check | Depth | Compare Against | Added | Origin |
|---|----------|-------|-------|-----------------|-------|--------|
| 5A | Env Var Completeness | Verify all `env`-configurable environment variables from official docs appear in the report | field-level | settings documentation page | 2026-03-05 | Initial checklist — missing env vars limit user configuration options |
| 5B | Ownership Boundary | Verify no env vars from `best-practice/claude-cli-startup-flags.md` are duplicated in the settings report, and vice versa | cross-file | claude-cli-startup-flags.md vs settings report | 2026-03-05 | Initial checklist — env var refactoring split vars across two files, must prevent re-duplication |
---
## 6. Examples
Rules that verify example accuracy.
| # | Category | Check | Depth | Compare Against | Added | Origin |
|---|----------|-------|-------|-----------------|-------|--------|
| 6A | Quick Reference Example | Verify the Quick Reference complete example uses valid current settings with correct syntax and realistic values | content-match | settings documentation page | 2026-03-05 | Initial checklist — example must demonstrate current best practices |
---
## 7. Cross-File Consistency
Rules that verify consistency between the report and other repo files.
| # | Category | Check | Depth | Compare Against | Added | Origin |
|---|----------|-------|-------|-----------------|-------|--------|
| 7A | CLAUDE.md Sync | Verify CLAUDE.md's Configuration Hierarchy and Hooks System sections are consistent with the report | cross-file | CLAUDE.md vs report | 2026-03-05 | Initial checklist — CLAUDE.md could drift from report |
---
## 8. Process
Meta-rules about the workflow verification process itself.
| # | Category | Check | Depth | Compare Against | Added | Origin |
|---|----------|-------|-------|-----------------|-------|--------|
| 8A | Source Credibility Guard | Only flag items as drift if confirmed by official sources (settings documentation page, CLI reference page, GitHub changelog). Third-party blog sources may be outdated or wrong — use them for leads only, verify against official docs before flagging | content-match | official docs only | 2026-03-05 | Adopted from subagents workflow — prevents false positives from blog sources |
---
## 9. Hyperlinks
Rules that verify all hyperlinks in the report are valid.
| # | Category | Check | Depth | Compare Against | Added | Origin |
|---|----------|-------|-------|-----------------|-------|--------|
| 9A | Local File Links | Verify all relative file links resolve to existing files | exists | local filesystem | 2026-03-05 | Initial checklist — file moves can break relative links |
| 9B | External URL Links | Verify all external URLs return valid pages (not 404 or error) | exists | HTTP response | 2026-03-05 | Initial checklist — external docs pages can be restructured or removed |
| 9C | Anchor Links | Verify all internal anchor links point to existing headings within the same file | exists | file headings | 2026-03-05 | Initial checklist — section renames can break anchor links |