arxiv 2602.11988 の知見に基づき、Claude Code の開発環境を最適化した。
論文の核心: コンテキストファイルはタスク成功率を下げる傾向がある。エージェントは指示に忠実すぎて不要な要件まで守り、推論コストが20%以上増える。
| 指標 | Before | After | 削減率 |
|---|---|---|---|
| CLAUDE.md (global) | 41行 | 13行 | -68% |
| CLAUDE.md (project) | 43行 | 19行 | -56% |
| settings.local.json | 142エントリ | 12エントリ | -92% |
| 自動化 Hooks | 0本 | 3本 | — |
| 総合スコア | 3/10 | 8/10 | — |
書くべき（KEEP）:
- ビルド/テストコマンド（
pnpm test等） - リポジトリ固有ツール設定（Biome config 等）
- コードを読んでも分からない慣習（ドメイン用語、コミット規約）
- 安全制約（スコープ制限）
書くべきでない（REMOVE）:
- プロセス指示（「TDD で書け」「プロトタイプ優先」）→ エージェントを過度に制約
- スタイルガイド（「strict TypeScript」「no any」）→ tsconfig.json から推測可能
- コード構造の説明（「テストは co-located」）→ ファイル構造から推測可能
- ドキュメント標準（「JSDoc を書け」）→ タスクを不必要に複雑にする
Claude Code には auto memory の組み込みガイドラインがある:
- 古い/間違った情報の削除指示
- 重複防止
- セッション固有情報の排除
- 200行ハードリミット
これを知らずに CLAUDE.md に Knowledge Self-Amendment セクションを書いていた。
カスタムルールが組み込み機能と重複すると、二重管理になるだけで価値がない。
実際、「MEMORY.md → rules に自動昇格」のルールを書いていたが、4プロジェクト調べて自動昇格で作られた rules は 0件 だった。
| 層 | 置くもの | 例 |
|---|---|---|
グローバル (~/.claude/settings.json) |
全プロジェクト共通コマンド | Bash(git *), Bash(pnpm *) |
ローカル (.claude/settings.local.json) |
プロジェクト固有のみ | Bash(playwright-cli *), 特定ドメインの WebFetch |
ローカルに142エントリ溜まっていた原因: 承認のたびに自動追加されるが、グローバルに移す仕組みがないため。 定期的にローカルを棚卸しし、汎用コマンドはグローバルに昇格させる運用が必要。
allow をワイルドカード（Bash(git *)）にすると git push --force も通る。
deny で危険なパターンを明示的にブロック:
"deny": [
"Bash(git push * --force*)",
"Bash(git push * -f *)",
"Bash(git reset --hard *)",
"Bash(git clean *)",
"Bash(git branch -D *)",
"Bash(rm -rf *)"
]chmod のような強めのコマンドは allow に入れず、都度承認が安全。
| Hook | トリガー | 解決する問題 |
|---|---|---|
post-format.sh |
PostToolUse (Edit/Write) | Svelte ファイルのタブ/スペース混在 |
protect-branch.sh |
PreToolUse (Edit/Write) | main/master への直接編集事故 |
cleanup.sh |
Stop | ~/.claude 配下のファイル肥大化 |
特に post-format.sh は、MEMORY.md に「Edit tool がタブを壊す」と3回記録されていた問題を Hook で根本解決した例。
繰り返し MEMORY.md に書かれる問題は、Hook で自動化できないか検討すべき。
# Base Claude Code Configuration
## Language
- **Response to user**: Japanese
- **Code/Comments/Commits/Docs**: English
## Constraints
- Edit ONLY files within project root. Use `tmp/` for scratch work
- Commands MUST NOT auto-invoke other commands. Display for user to run manually
## Tools
- **Context7**: Proactively use for library/framework documentation lookup