Skip to content

Latest commit

 

History

History
485 lines (342 loc) · 14.7 KB

TROUBLESHOOTING.md

File metadata and controls

485 lines (342 loc) · 14.7 KB

Troubleshooting Guide

Purpose: Common issues and recovery paths when using Claude Code best practices

Table of Contents

CLAUDE.md Issues

My CLAUDE.md keeps growing past 60 lines

Symptom: Started at 50 lines, now 120+ lines after several months

Cause: Adding context without removing, accumulating examples and edge cases

Fix:

  1. Apply The Big 3 Audit (from FOUNDATIONAL-PRINCIPLES.md):

    • "Would removing this cause mistakes? If not, cut it."
    • Every line consumes context in every turn

  2. Move examples to separate files:

    .claude/
  CLAUDE.md (~60 lines)
  docs/
    api-examples.md
    deployment-guide.md
    testing-notes.md

    Reference in CLAUDE.md: "See docs/ for examples"

  3. Delete sections Claude never asked about:

    • Check your session history - what sections were actually referenced?
    • If Claude didn't need it in 10+ sessions, it doesn't belong

  4. Target structure (~20 lines core):

    • Project purpose: 2 lines
    • Commands: 5 lines (only non-standard ones)
    • Known gotchas: 10 lines (things that caused 2+ mistakes)
    • Current focus: 2 lines

Related: context-engineering.md

My CLAUDE.md feels too minimal - Claude makes mistakes

Symptom: Following 60-line rule but Claude lacks necessary context

Root causes to check:

  1. Missing critical gotchas:

    • Are there repeated mistakes? Add those specific gotchas
    • Don't preemptively document - add after 2nd occurrence

  2. Context should be elsewhere:

    • API documentation → Separate docs/ file or inline code comments
    • Architecture → ARCHITECTURE.md
    • Current work → PLAN.md
    • Testing procedures → Inline in test files

  3. Commands aren't clear:

    • Claude needs actual commands, not descriptions
    • Bad: "Run tests - see package.json"
    • Good: "npm test - runs unit tests with coverage"

Principle: CLAUDE.md is for "what Claude needs to avoid mistakes", not comprehensive documentation.

Pattern Overwhelm

I'm overwhelmed by 34 patterns - where do I start?

Quick Start Path (3 patterns, 30 minutes reading):

  1. context-engineering.md - Foundation for everything
  2. spec-driven-development.md - The methodology (Specify→Plan→Tasks→Implement)
  3. project-infrastructure.md - Setup patterns (recommended + advanced)

Then choose by need:

Principle: You don't need all 34 patterns. Start with 3, add as needed.

Which patterns are actually critical?

Essential (read first):

High-value for most projects:

Specialized (use when needed):

  • Everything else in patterns/ directory

Rule of thumb: If you haven't hit the problem a pattern solves, you don't need that pattern yet.

Team Adoption

My team resists adopting these patterns

Common objections + responses:

"This is too much process"

Response: The recommended setup takes 15-30 minutes and includes:

  • Stop hook (prevents lost work from uncommitted changes)
  • CLAUDE.md (~60 lines of project context)
  • SessionStart hook (shows git status)
  • Permission rules (pre-approved commands)

If even this feels like too much, start with just the Stop hook (5 minutes):

  • Add Stop hook to settings.json for uncommitted/unpushed warnings
  • Add more when value is proven

Adoption path: Stop hook only → Full recommended setup after 1 week → Advanced features as needed

"We already have our own way"

Response: Use patterns as reference, not mandate

  • Patterns document what works - adapt to your context
  • Cherry-pick: hooks without skills, CLAUDE.md without presets, etc.
  • Framework Selection Guide helps choose orchestration approach

Key: Patterns are descriptive (what works), not prescriptive (what you must do)

"I don't want to learn Spec-Driven Development"

Response: Use just the infrastructure without SDD:

  • Hooks for quality gates (formatting, linting)
  • CLAUDE.md for project context
  • settings.json for permissions
  • No planning methodology required

Separation: Infrastructure ≠ methodology. Use what helps.

"The 60-line CLAUDE.md rule seems arbitrary"

Response: It's evidence-based, not arbitrary:

  • Official Anthropic docs: "~60 lines recommended"
  • Reason: Context rot - accuracy decreases with token count
  • Every line in CLAUDE.md costs context in every turn
  • Test it: Try 200-line CLAUDE.md vs 50-line. Measure mistake rate.

Compromise: Start with 100 lines if needed, audit monthly toward 60.

How do we standardize across a team?

Approach:

  1. Start with shared principles (not implementations):

    • Share FOUNDATIONAL-PRINCIPLES.md first
    • Discuss The Big 3 - get alignment on "why"
    • Let implementations vary by project

  2. Create team presets (optional):

    • Fork presets/coding.md or presets/hybrid.md
    • Customize for your stack/tools
    • Teams share via internal repo or gist

  3. Standardize hooks + permissions (high value):

    • Common hooks: Stop (uncommitted warning), PostToolUse (formatting)
    • Pre-approved permissions: test/build/lint commands
    • These reduce friction without enforcing methodology

  4. Let CLAUDE.md vary (it should):

    • Every project is different
    • CLAUDE.md should be project-specific, not template-driven
    • Standardize the audit process, not the content

Template for team docs:

# Our Team's Claude Code Standards

## Required (All Projects)
- Recommended infrastructure (Stop hook, CLAUDE.md, SessionStart, permissions)
- Pre-approved permissions for `npm test`, `npm run build`

## Recommended
- CLAUDE.md under 80 lines (audit monthly)
- Use /plan for features >3 files

## Optional
- Skills (if helpful for your project)
- Presets (starting point, customize as needed)

Setup Issues

MAKE-PROJECT-RECOMMENDATIONS.md fetch fails with 404

Symptom: External fetch of setup prompt returns 404 error

Common causes:

  1. Wrong branch in URL:

    • Check URL uses master branch (not main)
    • Correct: ...claude-code-project-best-practices/master/...

  2. File moved or renamed:

    • Check repository for current structure
    • Prompts are in prompts/ directory

  3. Network/GitHub issues:

    • Try raw URL: https://raw.githubusercontent.com/flying-coyote/claude-code-project-best-practices/master/prompts/MAKE-PROJECT-RECOMMENDATIONS.md
    • If GitHub is down, clone repo locally and use file:// path

Workaround: Clone repository locally:

git clone https://github.com/flying-coyote/claude-code-project-best-practices.git
cd claude-code-project-best-practices
# Use local files

Hooks don't run / settings.json not recognized

Symptom: Configured hooks in settings.json but they don't execute

Check list:

  1. File location - Must be exactly .claude/settings.json:

    your-project/
  .claude/
    settings.json  ← here
    CLAUDE.md

  2. JSON syntax - Validate with cat .claude/settings.json | jq .:

  3. Schema version - Use current schema:

    {
  "permissions": { ... },
  "hooks": { ... }
}

    NOT old schema: { "allowedTools": ... } (deprecated)

  4. Matcher syntax:

    • Matchers use glob patterns
    • Stop hook: "matcher": "" (empty = always)
    • Specific tools: "matcher": "Bash(git commit*)" or "matcher": "Write(**/*.ts)"

  5. Claude Code version - Hooks require Claude Code v2.0+:

    • Check version: claude --version
    • Update if needed

Test hooks:

# Make uncommitted change
echo "test" >> README.md

# Stop session - should see warning
# (Ctrl+C or /exit in Claude Code)

Permission prompts keep interrupting

Symptom: Constantly prompted for permission despite pre-approving

Causes + fixes:

  1. Pattern too narrow:

    • Bad: "Bash(npm test)" (only exact command)
    • Good: "Bash(npm test*)" (includes flags/args)
    • Better: "Bash(npm run test*)" (all test scripts)

  2. Missing tool categories:

    • Pre-approve common patterns:
    "permissions": {
  "allow": [
    "Bash(git status*)",
    "Bash(git diff*)",
    "Bash(git log*)",
    "Bash(npm run test*)",
    "Bash(npm run build*)",
    "Bash(npm run lint*)"
  ]
}

  3. Destructive operations (by design):

    • git push, rm -rf, file deletions → Always prompt
    • This is a security feature - don't override
    • Pre-approve read operations, prompt for writes

Balance: Pre-approve frequent operations, keep prompts for destructive ones.

Hook Problems

PreToolUse hook blocks legitimate operations

Symptom: Hook rejects operation you want to allow

Debug approach:

  1. Check hook logs - See what matched:

    • Hook output shows matcher that triggered
    • Verify the hook is catching what you intended

  2. Refine matcher:

    • Too broad: "matcher": "Bash(*)" → blocks everything
    • Better: "matcher": "Bash(rm*)" → blocks only rm commands
    • Exceptions: Use multiple hooks with specific matchers

  3. Add escape hatch:

    {
  "matcher": "Bash(rm -rf*)",
  "hooks": [{
    "type": "command",
    "command": "echo '⚠️ Destructive operation - confirm first (y/n):'; read confirm; [ \"$confirm\" = \"y\" ]"
  }]
}

    This prompts instead of blocking outright.

Related: advanced-hooks.md

PostToolUse hook slows down sessions

Symptom: Every tool call takes extra time due to hook execution

Optimization:

  1. Make hooks fast:

    • Bad: npm run lint (runs full lint on every write)
    • Good: npx eslint --fix "$FILE" (only file that changed)

  2. Use targeted matchers:

    • Bad: "matcher": "Write(*)" → runs on every file write
    • Good: "matcher": "Write(**/*.{ts,tsx})" → only TypeScript files

  3. Async where possible:

    • Formatting: sync (user expects formatted file)
    • Linting: can be async background job

  4. Consider removing hook:

    • If faster to manually run npm run format after session
    • PostToolUse hooks best for auto-fixable issues (format, import sort)

Rule: Hooks should be <200ms. If slower, make async or remove.

Performance Issues

Claude Code feels slow / high latency

Common causes:

  1. MCP server latency - MCP adds 300-800ms per call:

    • Fix: Use native tools where possible
    • Read files: Native Read tool (fast) vs MCP file server (slow)
    • See mcp-vs-skills-economics.md

  2. Bloated CLAUDE.md - Large context = slower processing:

  3. Too many skills loaded:

    • Fix: Skills consume context when loaded
    • Remove unused skills from .claude/skills/
    • Use multi-workflow pattern for large skills

  4. Large file operations:

    • Fix: Use pagination for large files
    • Read specific line ranges instead of full file

Context window exhausted mid-session

Symptom: Claude says "I've run out of context" or quality degrades

Recovery:

  1. One feature at a time (Principle #8):

    • Stop, commit current work
    • Start new session for next feature
    • External artifacts (git, specs) bridge sessions

  2. Externalize state:

    • Move progress to PLAN.md or TODO.md
    • Commit work-in-progress to branch
    • New session can load state from files

  3. Reduce context overhead:

    • Audit CLAUDE.md (trim to essentials)
    • Remove large skills not used this session
    • Close unrelated files

Prevention: Use long-running-agent.md pattern

External Fetch Errors

"File not found" when fetching patterns from GitHub

Symptom: External fetch returns 404 for pattern files

Checklist:

  1. Verify branch name: Use master not main

    • Correct: .../master/patterns/...

  2. Check file name case: Filenames are case-sensitive

    • Correct: spec-driven-development.md
    • Wrong: Spec-Driven-Development.md

  3. Use raw.githubusercontent.com for content:

    • Correct: https://raw.githubusercontent.com/flying-coyote/claude-code-project-best-practices/master/patterns/spec-driven-development.md
    • Wrong: https://github.com/.../blob/master/... (HTML page, not raw)

  4. Check repository status: Visit repo to confirm file exists

Alternative: Clone repo locally and use local paths (most reliable)

Still Stuck?

Resources

  1. Search existing patterns - Problem might be documented:

  2. Check FOUNDATIONAL-PRINCIPLES.md - Most issues trace to violating The Big 3

  3. Review examples/ - See complete working implementations:

  4. File an issue - If problem isn't covered:

Last Updated: February 2026