Claude Code Tool Patterns & Gotchas

Extracted: 2026-02-09 (consolidated 2026-02-10)
Context: Claude Code のツール使用時に発生しがちな問題とその回避策

---

1. Large File Write Performance

Problem

Very large files (>3000 lines) in a single Write tool call become extremely slow and may appear to hang.

Symptoms:

• Write operation takes >60 seconds
• User interrupts thinking it's stuck
• No feedback on progress

Solution

Split large files into modular components:

1. Identify logical boundaries (chapters, sections, domains)
2. Create multiple focused files (200-800 lines each)
3. Add navigation file (README/index) to tie them together
4. Write files in parallel when possible

# BAD: Single monolithic file
/docs/architecture.md (4000 lines) → 90+ seconds

# GOOD: Modular files
/docs/architecture/
├── README.md (200 lines)
├── 00-overview.md (600 lines)
├── 01-adr-backend.md (500 lines)
└── ...
→ Each write completes in ~5-10 seconds

---

2. File Edit Refresh Pattern

Problem

Edit tool fails with "File has been modified since read" when file state has changed since last Read.

Solution

Always Read immediately before Edit:

# BAD: Edit without recent Read
- Earlier: Read file.py
- (Multiple other operations)
- Later: Edit file.py  # May fail

# GOOD: Read immediately before Edit
- Earlier: Read file.py
- (Multiple other operations)
- Later: Read file.py   # Refresh state
- Then: Edit file.py    # Safe to edit

When to Apply

• Before every Edit call in sessions with multiple file operations
• After file state might have changed through other tools
• In long-running sessions (context near limits)
• When you see "File has been modified" errors

---

3. Hook Command JSON Escape Trap

Problem

settings.json の hooks にシェルコマンドを直接書くと、\", $, \n などの
特殊文字が JSON パースエラー（"Bad control character in string literal"）を引き起こす。

Solution

外部スクリプトファイルに切り出す:

# ~/.claude/hooks/my-hook.sh
#!/bin/bash
file=$(jq -r '.tool_input.file_path // empty')
if [ -n "$file" ] && echo "$file" | grep -q '\.py$'; then
  ruff format "$file" 2>/dev/null
fi
exit 0

// settings.json — シンプルなコマンドだけを記述
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "bash ~/.claude/hooks/my-hook.sh"
      }]
    }]
  }
}

When to Apply

• Hook コマンドに引用符、変数展開、パイプ、条件分岐が含まれる場合
• settings.json の JSON validation エラーが出た場合

---

When to Use

• Planning to write a file >1000 lines
• Editing files after many intervening tool calls
• In complex multi-step workflows with frequent file operations
• Hook に複雑なシェルコマンドを設定する場合