You are configuring Claude Code for production resilience. Work autonomously — do not ask questions.
TARGET: $ARGUMENTS (defaults to current project if not specified)
============================================================
PHASE 1: AUDIT CURRENT CONFIGURATION
LOCATE SETTINGS FILES
Find all active settings files in order of precedence:
- ~/.claude/settings.json (user-global)
- /.claude/settings.json (project-level)
- /.claude/settings.local.json (local overrides, gitignored)
For each file found, record:
- Current
model value
- Whether
fallbackModel is already set (and its current value)
- Whether
autoMode is configured
- Hook definitions (PreToolCall, PostToolCall, Stop, etc.)
- Plugin and skill configuration
CHECK CLAUDE CODE VERSION
Run: claude --version
fallbackModel, --safe-mode, and /cd all require v2.1.166 or higher.
If the installed version is older, output the upgrade command and stop:
npm install -g @anthropic-ai/claude-code@latest
IDENTIFY RUNNING ENVIRONMENT
Check environment variables for CI context: CI, GITHUB_ACTIONS, CIRCLECI,
BUILDKITE, JENKINS_URL, TRAVIS.
Record environment type:
- CI/CD pipeline: benefits most from fallbackModel (prevents failed overnight runs)
- Developer workstation: benefits most from --safe-mode and /cd hygiene
- Both: configure everything
============================================================
PHASE 2: CONFIGURE FALLBACKMODEL CHAIN
DETERMINE PRIMARY MODEL
Read model from the effective settings.json. If unset, the runtime
default is claude-opus-4-8.
WRITE FALLBACK CHAIN
Apply to the project-level .claude/settings.json (create if absent).
Use descending capability — most capable first, Haiku as the budget
safety net:
If primary is claude-opus-4-8:
{
"model": "claude-opus-4-8",
"fallbackModel": [
"claude-sonnet-4-6",
"claude-haiku-4-5-20251001"
]
}
If primary is claude-sonnet-4-6:
{
"model": "claude-sonnet-4-6",
"fallbackModel": [
"claude-haiku-4-5-20251001"
]
}
If primary is already Haiku — no fallback exists. Flag this and
recommend upgrading to Sonnet or Opus as the primary for any autonomous
pipeline, then adding Haiku as the fallback.
VERIFY TOOL CAPABILITY ALIGNMENT
Check whether the project uses tools that not all models support:
- Computer use: not supported on Haiku — remove from chain if present
- Extended thinking: not supported on Haiku — remove from chain if present
- Agent tool (sub-agents): supported on all current models
If a mismatch is found, remove the incompatible model from the chain
and add a comment explaining why in the settings file.
VALIDATE JSON SYNTAX
After writing settings.json, verify it parses:
node -e "JSON.parse(require('fs').readFileSync('.claude/settings.json','utf8'))" && echo OK
Fix and re-validate if the check fails.
============================================================
PHASE 3: INSTALL SAFE-MODE TROUBLESHOOTING PROTOCOL
CREATE OR UPDATE DEBUGGING RUNBOOK
Create .claude/DEBUGGING.md (or append to it if it already exists):
## Claude Code — Troubleshooting Protocol
### Step 1: Safe mode isolation
If Claude Code behaves unexpectedly (loops, crashes, wrong tool use,
unexpected prompts):
claude --safe-mode
Safe mode disables ALL customizations: CLAUDE.md, hooks, plugins,
bundled skills. If the problem disappears → the culprit is in your
config stack.
### Step 2: Layer bisect (when safe mode is clean)
Re-enable layers one at a time, testing after each:
1. Hooks (most common source of loops — check PreToolCall first)
2. Plugins
3. CLAUDE.md / nested .claude/ directories
4. Bundled skills (`disableBundledSkills: false`)
### Step 3: Hook log inspection
Hooks write to stderr by default. To capture hook output during a
session, temporarily add verbose logging:
"hooks": {
"PreToolCall": [{
"matcher": ".*",
"hooks": [{"type": "command", "command": "echo \"[hook] $CLAUDE_TOOL_NAME\" >&2"}]
}]
}
### Step 4: Change directory without restarting
To switch project root mid-session without losing context or cache:
/cd <new-directory>
Prompt cache is fully preserved. /cd does not rebuild context from
scratch. Use it instead of opening a new session.
### Step 5: Fallback model verification
If you suspect a fallbackModel switch caused unexpected behavior,
check the session log (~/.claude/logs/) for lines containing
"fallback" to confirm which model was active at each point.
VERIFY HOOK STDERR OUTPUT (IF HOOKS EXIST)
For any existing hook command, confirm it writes actionable output to
stderr on failure. A hook that silently exits non-zero is harder to
debug than one that prints a clear error message. Update any silent
hooks to log to stderr:
<your-hook-command> || echo "[hook failed] <hook-name>" >&2
============================================================
PHASE 4: AUDIT NESTED SUB-AGENT DEPTH (IF APPLICABLE)
SCAN FOR AGENT DEFINITIONS
Check .claude/agents/*.md for sub-agent definitions. If no agent files
exist, skip this phase and note "no agent files found."
AUDIT DEPTH CONSTRAINTS
With v2.1.166+, sub-agents nest up to 5 levels deep. For each agent
file found:
- Determine whether it spawns child sub-agents
- Estimate the maximum pipeline depth
- Flag any pipelines exceeding depth 3 (they should be intentional and
justified with a comment)
Recommended depth budget:
- Level 1: Orchestrator (parent session)
- Level 2: Domain specialists (implement, test, review)
- Level 3: Per-file workers (optional)
- Levels 4–5: Reserved for deep recursive analysis only
ENSURE CHILD FAILURE HANDLING
For each sub-agent that spawns children, verify its system prompt
includes explicit failure handling. If it doesn't, add:
If any child sub-agent fails its acceptance criteria, halt immediately
and surface the child's transcript to the parent. Do not auto-retry.
Auto-retry masks real problems. Hard-fail with transcript is the correct
default.
============================================================
OUTPUT
Produce a concise audit report:
Claude Code Production Resilience Audit
Claude Code version: [installed version] — [OK ≥ 2.1.166 / UPGRADE REQUIRED]
fallbackModel chain:
- Primary: [model]
- Fallback 1: [model or "not configured"]
- Fallback 2: [model or "not configured"]
- Capability mismatches removed: [list or "none"]
Safe mode: [available / not available — old version]
Debugging runbook: [created at .claude/DEBUGGING.md / updated / already exists]
Sub-agent audit:
- Agent definition files found: [count]
- Estimated max pipeline depth: [N levels]
- Failure-handling gaps fixed: [count]
- Depth concerns: [list or "none"]
Files modified:
- [list each file and what changed]
Next steps (manual):
- [anything requiring action outside this session]
============================================================
SELF-HEALING VALIDATION (max 2 iterations)
After producing output, validate:
- All modified JSON files parse without errors.
- The fallbackModel array contains only valid model IDs (no typos).
- .claude/DEBUGGING.md exists and contains non-empty content.
- If version check failed, the upgrade command is clearly stated.
If any check fails:
- Fix the failing item
- Re-run only that check
- Update the report
After 2 iterations, note any remaining gaps and stop.
1---2name: fallback-model-setup3description: "Configures Claude Code's fallbackModel chain, --safe-mode troubleshooting protocol, and /cd workspace hygiene for production-resilient autonomous coding sessions. Audits current settings, installs the optimal three-model fallback chain, and documents a fast debugging loop. Requires Claude Code v2.1.166+."4version: "1.0.0"5category: productivity6platforms:7 - CLAUDE_CODE8metadata:9 source: https://skillmd.com/skills/tinh2/fallback-model-setup10---1112You are configuring Claude Code for production resilience. Work autonomously — do not ask questions.1314TARGET: $ARGUMENTS (defaults to current project if not specified)1516============================================================17PHASE 1: AUDIT CURRENT CONFIGURATION18============================================================19201. LOCATE SETTINGS FILES21 Find all active settings files in order of precedence:22 - ~/.claude/settings.json (user-global)23 - <project>/.claude/settings.json (project-level)24 - <project>/.claude/settings.local.json (local overrides, gitignored)2526 For each file found, record:27 - Current `model` value28 - Whether `fallbackModel` is already set (and its current value)29 - Whether `autoMode` is configured30 - Hook definitions (PreToolCall, PostToolCall, Stop, etc.)31 - Plugin and skill configuration32332. CHECK CLAUDE CODE VERSION34 Run: claude --version3536 fallbackModel, --safe-mode, and /cd all require v2.1.166 or higher.37 If the installed version is older, output the upgrade command and stop:38 ```39 npm install -g @anthropic-ai/claude-code@latest40 ```41423. IDENTIFY RUNNING ENVIRONMENT43 Check environment variables for CI context: CI, GITHUB_ACTIONS, CIRCLECI,44 BUILDKITE, JENKINS_URL, TRAVIS.4546 Record environment type:47 - CI/CD pipeline: benefits most from fallbackModel (prevents failed overnight runs)48 - Developer workstation: benefits most from --safe-mode and /cd hygiene49 - Both: configure everything5051============================================================52PHASE 2: CONFIGURE FALLBACKMODEL CHAIN53============================================================54551. DETERMINE PRIMARY MODEL56 Read `model` from the effective settings.json. If unset, the runtime57 default is claude-opus-4-8.58592. WRITE FALLBACK CHAIN60 Apply to the project-level .claude/settings.json (create if absent).61 Use descending capability — most capable first, Haiku as the budget62 safety net:6364 If primary is claude-opus-4-8:65 ```json66 {67 "model": "claude-opus-4-8",68 "fallbackModel": [69 "claude-sonnet-4-6",70 "claude-haiku-4-5-20251001"71 ]72 }73 ```7475 If primary is claude-sonnet-4-6:76 ```json77 {78 "model": "claude-sonnet-4-6",79 "fallbackModel": [80 "claude-haiku-4-5-20251001"81 ]82 }83 ```8485 If primary is already Haiku — no fallback exists. Flag this and86 recommend upgrading to Sonnet or Opus as the primary for any autonomous87 pipeline, then adding Haiku as the fallback.88893. VERIFY TOOL CAPABILITY ALIGNMENT90 Check whether the project uses tools that not all models support:91 - Computer use: not supported on Haiku — remove from chain if present92 - Extended thinking: not supported on Haiku — remove from chain if present93 - Agent tool (sub-agents): supported on all current models9495 If a mismatch is found, remove the incompatible model from the chain96 and add a comment explaining why in the settings file.97984. VALIDATE JSON SYNTAX99 After writing settings.json, verify it parses:100 ```bash101 node -e "JSON.parse(require('fs').readFileSync('.claude/settings.json','utf8'))" && echo OK102 ```103 Fix and re-validate if the check fails.104105============================================================106PHASE 3: INSTALL SAFE-MODE TROUBLESHOOTING PROTOCOL107============================================================1081091. CREATE OR UPDATE DEBUGGING RUNBOOK110 Create .claude/DEBUGGING.md (or append to it if it already exists):111112 ```markdown113 ## Claude Code — Troubleshooting Protocol114115 ### Step 1: Safe mode isolation116 If Claude Code behaves unexpectedly (loops, crashes, wrong tool use,117 unexpected prompts):118119 claude --safe-mode120121 Safe mode disables ALL customizations: CLAUDE.md, hooks, plugins,122 bundled skills. If the problem disappears → the culprit is in your123 config stack.124125 ### Step 2: Layer bisect (when safe mode is clean)126 Re-enable layers one at a time, testing after each:127 1. Hooks (most common source of loops — check PreToolCall first)128 2. Plugins129 3. CLAUDE.md / nested .claude/ directories130 4. Bundled skills (`disableBundledSkills: false`)131132 ### Step 3: Hook log inspection133 Hooks write to stderr by default. To capture hook output during a134 session, temporarily add verbose logging:135136 "hooks": {137 "PreToolCall": [{138 "matcher": ".*",139 "hooks": [{"type": "command", "command": "echo \"[hook] $CLAUDE_TOOL_NAME\" >&2"}]140 }]141 }142143 ### Step 4: Change directory without restarting144 To switch project root mid-session without losing context or cache:145146 /cd <new-directory>147148 Prompt cache is fully preserved. /cd does not rebuild context from149 scratch. Use it instead of opening a new session.150151 ### Step 5: Fallback model verification152 If you suspect a fallbackModel switch caused unexpected behavior,153 check the session log (~/.claude/logs/) for lines containing154 "fallback" to confirm which model was active at each point.155 ```1561572. VERIFY HOOK STDERR OUTPUT (IF HOOKS EXIST)158 For any existing hook command, confirm it writes actionable output to159 stderr on failure. A hook that silently exits non-zero is harder to160 debug than one that prints a clear error message. Update any silent161 hooks to log to stderr:162 ```bash163 <your-hook-command> || echo "[hook failed] <hook-name>" >&2164 ```165166============================================================167PHASE 4: AUDIT NESTED SUB-AGENT DEPTH (IF APPLICABLE)168============================================================1691701. SCAN FOR AGENT DEFINITIONS171 Check .claude/agents/*.md for sub-agent definitions. If no agent files172 exist, skip this phase and note "no agent files found."1731742. AUDIT DEPTH CONSTRAINTS175 With v2.1.166+, sub-agents nest up to 5 levels deep. For each agent176 file found:177 - Determine whether it spawns child sub-agents178 - Estimate the maximum pipeline depth179 - Flag any pipelines exceeding depth 3 (they should be intentional and180 justified with a comment)181182 Recommended depth budget:183 - Level 1: Orchestrator (parent session)184 - Level 2: Domain specialists (implement, test, review)185 - Level 3: Per-file workers (optional)186 - Levels 4–5: Reserved for deep recursive analysis only1871883. ENSURE CHILD FAILURE HANDLING189 For each sub-agent that spawns children, verify its system prompt190 includes explicit failure handling. If it doesn't, add:191192 ```193 If any child sub-agent fails its acceptance criteria, halt immediately194 and surface the child's transcript to the parent. Do not auto-retry.195 ```196197 Auto-retry masks real problems. Hard-fail with transcript is the correct198 default.199200============================================================201OUTPUT202============================================================203204Produce a concise audit report:205206### Claude Code Production Resilience Audit207208**Claude Code version:** [installed version] — [OK ≥ 2.1.166 / UPGRADE REQUIRED]209210**fallbackModel chain:**211- Primary: [model]212- Fallback 1: [model or "not configured"]213- Fallback 2: [model or "not configured"]214- Capability mismatches removed: [list or "none"]215216**Safe mode:** [available / not available — old version]217**Debugging runbook:** [created at .claude/DEBUGGING.md / updated / already exists]218219**Sub-agent audit:**220- Agent definition files found: [count]221- Estimated max pipeline depth: [N levels]222- Failure-handling gaps fixed: [count]223- Depth concerns: [list or "none"]224225**Files modified:**226- [list each file and what changed]227228**Next steps (manual):**229- [anything requiring action outside this session]230231============================================================232SELF-HEALING VALIDATION (max 2 iterations)233============================================================234235After producing output, validate:2362371. All modified JSON files parse without errors.2382. The fallbackModel array contains only valid model IDs (no typos).2393. .claude/DEBUGGING.md exists and contains non-empty content.2404. If version check failed, the upgrade command is clearly stated.241242If any check fails:243- Fix the failing item244- Re-run only that check245- Update the report246247After 2 iterations, note any remaining gaps and stop.