diff --git a/!/tags/claude-certified-architect.svg b/!/tags/claude-certified-architect.svg new file mode 100644 index 0000000..96e3b6c --- /dev/null +++ b/!/tags/claude-certified-architect.svg @@ -0,0 +1,35 @@ + + Claude Certified Architect Foundations — Request Access + + + + + + + + + + + + + + + + + + + + + + + + + Prove your Claude expertise — get Claude Certified Architect Foundations certification · Request Access + + diff --git a/README.md b/README.md index 867e8a6..1a4c508 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # claude-code-best-practice practice makes claude perfect -![Last Updated](https://img.shields.io/badge/Last_Updated-Mar%2013%2C%202026%2001%3A27%20PM%20PKT-white?style=flat&labelColor=555) GitHub Stars +![Last Updated](https://img.shields.io/badge/Last_Updated-Mar%2014%2C%202026%2006%3A41%20AM%20PKT-white?style=flat&labelColor=555) GitHub Stars [![Best Practice](!/tags/best-practice.svg)](best-practice/) *Click on this badge to show the latest best practice*
[![Implemented](!/tags/implemented.svg)](implementation/) *Click on this badge to show implementation in this repo*
@@ -228,5 +228,14 @@ claude ✨Trending on Github in March 2026✨

+![How to Use](!/tags/how-to-use.svg) + +``` +1. Read the repo like a course, learn what commands, agents, skills, and hooks are before trying to use them. +2. Clone this repo and play with the examples, try /weather-orchestrator, listen to the hook sounds, run agent teams, so you can see how things actually work. +3. Go to your own project and ask Claude to suggest what best practices from this repo you should add, give it this repo as a reference so it knows what's possible. +``` + [![Claude for OSS](!/tags/claude-for-oss.svg)](https://claude.com/contact-sales/claude-for-oss) [![Claude Community Ambassador](!/tags/claude-community-ambassador.svg)](https://claude.com/community/ambassadors) +[![Claude Certified Architect](!/tags/claude-certified-architect.svg)](https://anthropic.skilljar.com/claude-certified-architect-foundations-access-request) diff --git a/best-practice/claude-settings.md b/best-practice/claude-settings.md index c0d716c..e16dd26 100644 --- a/best-practice/claude-settings.md +++ b/best-practice/claude-settings.md @@ -1,8 +1,8 @@ # Claude Code Settings Reference -![Last Updated](https://img.shields.io/badge/Last_Updated-Mar%2012%2C%202026%2012%3A23%20PM%20PKT-white?style=flat&labelColor=555) ![Version](https://img.shields.io/badge/Claude_Code-v2.1.74-blue?style=flat&labelColor=555) +![Last Updated](https://img.shields.io/badge/Last_Updated-Mar%2014%2C%202026%201%3A36%20AM%20PKT-white?style=flat&labelColor=555) ![Version](https://img.shields.io/badge/Claude_Code-v2.1.75-blue?style=flat&labelColor=555) -A comprehensive guide to all available configuration options in Claude Code's `settings.json` files. As of v2.1.74, Claude Code exposes **55+ settings** and **140+ environment variables** (use the `"env"` field in `settings.json` to avoid wrapper scripts). +A comprehensive guide to all available configuration options in Claude Code's `settings.json` files. As of v2.1.75, Claude Code exposes **55+ settings** and **140+ environment variables** (use the `"env"` field in `settings.json` to avoid wrapper scripts). @@ -30,22 +30,30 @@ A comprehensive guide to all available configuration options in Claude Code's `s ## Settings Hierarchy -Claude Code settings use a 5-level user-writable override chain plus an enforced policy layer: +Settings apply in order of precedence (highest to lowest): -| Priority | Location | Scope | Version Control | Purpose | -|----------|----------|-------|-----------------|---------| -| 1 | Command line arguments | Session | N/A | Single-session overrides | -| 2 | `.claude/settings.local.json` | Project | No (git-ignored) | Personal project-specific | -| 3 | `.claude/settings.json` | Project | Yes (committed) | Team-shared settings | -| 4 | `~/.claude/settings.local.json` | User | N/A | Personal global overrides | +| Priority | Location | Scope | Shared? | Purpose | +|----------|----------|-------|---------|---------| +| 1 | Managed settings | Organization | Yes (deployed by IT) | Security policies that cannot be overridden | +| 2 | Command line arguments | Session | N/A | Temporary single-session overrides | +| 3 | `.claude/settings.local.json` | Project | No (git-ignored) | Personal project-specific | +| 4 | `.claude/settings.json` | Project | Yes (committed) | Team-shared settings | | 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. On macOS, managed settings can also be delivered via MDM profiles (plist at `com.anthropic.claudecode`). On Windows, managed settings use the Windows Registry. +**Managed settings** are organization-enforced and cannot be overridden by any other level, including command line arguments. Delivery methods: +- **Server-managed** settings (remote delivery) +- **MDM profiles** — macOS plist at `com.anthropic.claudecode` +- **Registry policies** — Windows HKLM/HKCU at `Software\Anthropic\ClaudeCode` +- **File** — `managed-settings.json` (macOS: `/Library/Application Support/ClaudeCode/`, Linux/WSL: `/etc/claude-code/`, Windows: `C:\Program Files\ClaudeCode\`) + +Within the managed tier, precedence is: server-managed > MDM/OS-level policies > `managed-settings.json` > HKCU registry (Windows only). Only one managed source is used; sources do not merge. + +> **Note:** As of v2.1.75, the deprecated Windows fallback path `C:\ProgramData\ClaudeCode\managed-settings.json` has been removed. Use `C:\Program Files\ClaudeCode\managed-settings.json` instead. **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. +- Array settings (e.g., `permissions.allow`) are **concatenated and deduplicated** across scopes — entries from all levels are combined, not replaced. --- @@ -59,11 +67,11 @@ Claude Code settings use a 5-level user-writable override chain plus an enforced | `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 | -| `cleanupPeriodDays` | number | `30` | Sessions inactive longer than this are deleted at startup | +| `cleanupPeriodDays` | number | `30` | Sessions inactive longer than this are deleted at startup. Setting to `0` deletes all existing transcripts and disables session persistence entirely (no `.jsonl` files written, `/resume` shows no conversations) | | `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` | +| `availableModels` | array | - | Restrict which models users can select via `/model`, `--model`, or `ANTHROPIC_MODEL`. Does not affect the Default option. Example: `["sonnet", "haiku"]` | | `fastModePerSessionOptIn` | boolean | `false` | Require users to opt in to fast mode each session | | `teammateMode` | string | `"auto"` | Agent team display mode: `"auto"` (split panes in tmux/iTerm2, in-process otherwise), `"in-process"`, or `"tmux"` | | `includeGitInstructions` | boolean | `true` | Include git-related instructions in system prompt | @@ -87,7 +95,7 @@ Store plan and auto-memory files in custom locations. | Key | Type | Default | Description | |-----|------|---------|-------------| | `plansDirectory` | string | `~/.claude/plans` | Directory where `/plan` outputs are stored | -| `autoMemoryDirectory` | string | - | Custom directory for auto-memory storage. Overrides the default memory location | +| `autoMemoryDirectory` | string | - | Custom directory for auto-memory storage. Accepts `~/`-expanded paths. Not accepted in project settings (`.claude/settings.json`) to prevent redirecting memory writes to sensitive locations; accepted from policy, local, and user settings | **Example:** ```json @@ -187,7 +195,7 @@ Control what tools and operations Claude can perform. | `permissions.ask` | array | Rules requiring user confirmation | | `permissions.deny` | array | Rules blocking tool use (highest precedence) | | `permissions.additionalDirectories` | array | Extra directories Claude can access | -| `permissions.defaultMode` | string | Default permission mode | +| `permissions.defaultMode` | string | Default permission mode. In Remote environments, only `acceptEdits` and `plan` are honored (v2.1.70+) | | `permissions.disableBypassPermissionsMode` | string | Prevent bypass mode activation | | `allowManagedPermissionRulesOnly` | boolean | **(Managed only)** Only managed permission rules apply; user/project `allow`, `ask`, `deny` rules are ignored | | `allow_remote_sessions` | boolean | **(Managed only)** Allow users to start Remote Control and web sessions. Defaults to `true`. Set to `false` to prevent remote session access | @@ -220,6 +228,8 @@ Control what tools and operations Claude can perform. | `Skill` | `Skill(skill-name)` | `Skill(weather-fetcher)` | | `MCP` | `mcp__server__tool` or `MCP(server:tool)` | `mcp__memory__*`, `MCP(github:*)` | +**Evaluation order:** Rules are evaluated in order: deny rules first, then ask, then allow. The first matching rule wins. + **Bash wildcard notes:** - `*` can appear at **any position**: prefix (`Bash(* install)`), suffix (`Bash(npm *)`), or middle (`Bash(git * main)`) - `Bash(*)` is treated as equivalent to `Bash` (matches all bash commands) @@ -443,7 +453,7 @@ The `/model` command exposes an **effort level** control that adjusts how much r 3. Use **← →** arrow keys to adjust the effort level 4. The setting applies to the current session and future sessions -**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. +**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. As of v2.1.75, 1M context window for Opus 4.6 is available by default on Max, Team, and Enterprise plans. ### Model Environment Variables @@ -507,6 +517,8 @@ The status line command receives a JSON object on stdin with these notable field ### File Suggestion Configuration +The file suggestion script receives a JSON object on stdin (e.g., `{"query": "src/comp"}`) and must output up to 15 file paths (one per line). + ```json { "fileSuggestion": { diff --git a/changelog/best-practice/claude-settings/changelog.md b/changelog/best-practice/claude-settings/changelog.md index 680f318..11b1931 100644 --- a/changelog/best-practice/claude-settings/changelog.md +++ b/changelog/best-practice/claude-settings/changelog.md @@ -62,3 +62,22 @@ | 9 | LOW | Suspect Keys | Verify `skipWebFetchPreflight`, `sandbox.ignoreViolations`, `sandbox.network.deniedDomains`, `skippedMarketplaces`, `skippedPlugins`, `pluginConfigs` — still not in official docs | ON HOLD (kept in report pending verification — recurring from 2026-03-05) | | 10 | LOW | Missing Env Var | Add `CLAUDE_CODE_SUBAGENT_MODEL` to env vars table (already in Model env example block but missing from table) | COMPLETE (added to env vars table) | | 11 | LOW | Example Update | Update Quick Reference example to include `modelOverrides` and corrected `$schema` URL | COMPLETE (example updated with both) | + +--- + +## [2026-03-14 01:35 AM PKT] Claude Code v2.1.75 + +| # | Priority | Type | Action | Status | +|---|----------|------|--------|--------| +| 1 | HIGH | Settings Hierarchy | Restructure to match official 5-level hierarchy: Managed (#1) > CLI args > Local > Project > User. Remove `~/.claude/settings.local.json` row. Add managed-tier internal precedence (server-managed > MDM > file > HKCU). Note Managed "cannot be overridden by any other level, including CLI args" | COMPLETE (restructured table to 5 levels with Managed as #1, added delivery methods, internal precedence, and file paths) | +| 2 | HIGH | Changed Behavior | Fix `availableModels` description: change from complex object array (`title`/`modelId`/`effortOptions`) to simple string array `["sonnet", "haiku"]` per official docs | COMPLETE (updated description to match official docs format) | +| 3 | HIGH | Changed Behavior | Add `cleanupPeriodDays` `0`-value behavior: "Setting to `0` deletes all existing transcripts at startup and disables session persistence entirely" | COMPLETE (added 0-value behavior to description) | +| 4 | HIGH | Permission Syntax | Add evaluation order note to Permissions section: "Rules are evaluated in order: deny rules first, then ask, then allow. The first matching rule wins." | COMPLETE (added evaluation order before Bash wildcard notes) | +| 5 | MED | Changed Description | Add `autoMemoryDirectory` scope restriction: "Not accepted in project settings (`.claude/settings.json`). Accepted from policy, local, and user settings" | COMPLETE (added scope restriction to description) | +| 6 | MED | Changed Description | Add `permissions.defaultMode` Remote environment note: only `acceptEdits` and `plan` are honored in Remote environments (v2.1.70) | COMPLETE (added Remote restriction to description) | +| 7 | MED | Model Config | Add Opus 4.6 1M context default note: as of v2.1.75, 1M context is default for Max/Team/Enterprise plans | COMPLETE (added to Effort Level note) | +| 8 | MED | Settings Hierarchy | Add Windows managed path note: v2.1.75 removed deprecated `C:\ProgramData\ClaudeCode\` fallback — use `C:\Program Files\ClaudeCode\managed-settings.json` | COMPLETE (added deprecation note in hierarchy section) | +| 9 | MED | Display & UX | Add `fileSuggestion` stdin JSON format (`{"query": "..."}`) and 15-path output limit detail | COMPLETE (added stdin format and output limit to File Suggestion section) | +| 10 | MED | Settings Hierarchy | Update array merge note from "merged" to "concatenated and deduplicated" per official docs | COMPLETE (updated wording in hierarchy Important section) | +| 11 | LOW | Suspect Keys | `sandbox.ignoreViolations`, `sandbox.network.deniedDomains` still not in official docs or JSON schema top-level | ON HOLD (kept in report pending verification — recurring from 2026-03-05) | +| 12 | LOW | Suspect Keys | `skipWebFetchPreflight`, `skippedMarketplaces`, `skippedPlugins`, `pluginConfigs` — confirmed in JSON schema but not on official settings page | ON HOLD (kept in report — valid per schema, recurring from 2026-03-05) |