Claude Code の設定でハマる箇所まとめ

Last updated at 2026-08-20Posted at 2026-08-20

Claude Code を使っていて、こういう目に遭ったことはないでしょうか。

公式に「既定でON」と書いてある機能が、なぜか使えない
昨日まで出ていたタスクリストが、いつの間にか出なくなった
設定を書いたのに、何も起きない。エラーも出ない

原因の多くは、公式ドキュメントに載っていない環境変数でした。

この1週間で踏んだものを、症状から引ける形でまとめます。全部 Windows で実測しています。

検証環境: Windows 10 Home 19045 / Claude Code 2.1.234〜2.1.235

症状から引く早見表

症状	原因	対処
`Agent type 'fork' not found`	`CLAUDE_CODE_FORK_SUBAGENT` 未設定	`=1` を設定
タスクリストが出ない	`CLAUDE_CODE_ENABLE_TASKS=0`	`CLAUDE_CODE_ENABLE_TODO_TOOLS=1` を追加
`AGENTS.md` が効かない	仕様（読まない）	`CLAUDE.md` に `@AGENTS.md` と書く
`AGENTS.md` を更新しても反映されない	symlink がコピーになっている	`ls -l` で確認、インポートに変更
`spellcheck` を有効にしても何も起きない	辞書ツールが未インストール	`hunspell` + 辞書を入れる（日本語は非推奨）
`pip install` が謎のエラーで落ちる	パスが260文字を超えた	`--no-deps` か、短いパスへ

以下、それぞれの詳細です。

1. fork が「既定でON」なのに使えない

症状

Agent type 'fork' not found.

fork は親の会話をまるごと引き継ぐサブエージェントです。2.1.232 で既定ONになったはずですが、使えません。

原因

公式ドキュメントをよく読むと、条件が付いています。

When fork mode is on in interactive sessions (default v2.1.232+)
（対話セッションで fork モードが有効なとき（v2.1.232以降は既定））

「対話セッション」限定でした。非対話モードでは明示的にONにする必要があります。

実測

同じバイナリで、環境変数だけ変えて比較しました。

`CLAUDE_CODE_FORK_SUBAGENT`	結果
未設定	使えない
`1`	使える
`0`	使えない

未設定は 0 と同じ挙動です。手元は VSCode 拡張から起動した子セッション（CLAUDE_CODE_CHILD_SESSION=1）で、対話扱いになっていませんでした。

対処

{
  "env": { "CLAUDE_CODE_FORK_SUBAGENT": "1" }
}

逆にfork だけ止めたい場合は、モードを残したまま起動を拒否できます。

{
  "permissions": { "deny": ["Agent(fork)"] }
}

ついでに測ったこと

fork が本当に会話を継ぐのかも確認しました。親セッションに秘密の値を持たせ、fork と通常のサブエージェントに同じ質問をしています。

fork=4271／紫陽花 / plain=不明

fork は答え、通常のサブエージェントは答えられませんでした。 ツールの使用は禁止しているので、ファイルを読んだのではありません。

なお通常のサブエージェントは、何も答えなくても約3.5万トークンかかります（ツール使用0回、4.5秒）。渡される定義の分です。

2. タスクリストが出なくなった

症状

複数手順の作業を頼んでも、進捗のチェックリストが表示されない。TodoWrite がツールごと存在しない。

原因

changelog にはこうあります。

Todo/task-tracking tools (TaskCreate/Get/Update/List, TodoWrite) are no longer available on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, and newer models
（Todo・タスク管理ツールは Opus 4.8、Sonnet 5、Fable 5、Mythos 5 以降のモデルでは利用できない）

ただし、これだけが原因ではありませんでした。

実測

4パターン試した結果です。

モデル	`ENABLE_TASKS`	`ENABLE_TODO_TOOLS`	使えたツール
Opus 5	未設定	未設定	TodoWrite
Haiku 4.5	未設定	未設定	TaskCreate / Get / List / Update
Opus 5	0	未設定	なし
Opus 5	未設定	1	TaskCreate / Get / List / Update

素の Opus 5 なら TodoWrite は使えます。 全部消していたのは CLAUDE_CODE_ENABLE_TASKS=0 のほうでした。

ENABLE_TASKS=0 は本来「Task ツールをやめて TodoWrite にする」切り替えです。ところが新しいモデルには Task ツールが既定で付いていないので、やめる対象がないまま TodoWrite も出てこない、という状態になります。

対処

{
  "env": { "CLAUDE_CODE_ENABLE_TODO_TOOLS": "1" }
}

変数名は Todo ですが、戻ってくるのは Task ツール一式です。 TodoWrite は入っていません。

Todo と Task の違い

	`TodoWrite`	Task ツール
更新の単位	1回でリスト全体を書き換え	`TaskCreate` で1件追加、`TaskUpdate` で1件更新
読み出し	なし	`TaskList` / `TaskGet`
依存関係	なし	`addBlocks` / `addBlockedBy`

3. AGENTS.md が読まれない

症状

AGENTS.md に書いた指示が、Claude Code だけ反映されない。

原因

仕様です。

Claude Code reads CLAUDE.md, not AGENTS.md.

対応要望（issue #6235、リアクション5,983）は 2026-08-17 に completed で閉じられましたが、中身は回避策の案内で、実装ではありませんでした。実測でも読まれません。

対処: `@AGENTS.md` インポート

@AGENTS.md

## Claude Code

この節は Claude Code 専用です。

実ファイルへの参照なので、AGENTS.md を書き換えるたびに反映されます。 下に Claude 専用の指示を足せるのも利点です。

Windows で symlink を使ってはいけない

公式はもう1つ、symlink を挙げています。

ln -s AGENTS.md CLAUDE.md

Git Bash で実行すると、エラーも出ず成功し、初回はちゃんと動きます。 しかし中身が違いました。

-rw-r--r-- 1 ... 165 Aug 20 08:34 CLAUDE.md      ← lrwxrwxrwx ではない
inode: AGENTS.md=7036874418332751  CLAUDE.md=7881299348464765
readlink: リンクではない

コピーが作られています。 そのため AGENTS.md を更新しても、Claude Code は古い内容を読み続けます。

ファイル	中身
`AGENTS.md`（書き換えた）	椿5024
`CLAUDE.md`（コピー）	向日葵7391 のまま

確認は1行です。

ls -l CLAUDE.md    # lrwxrwxrwx なら本物、-rw-r--r-- ならコピー

公式にも「Windows では管理者権限か開発者モードが要るのでインポートを使え」とありますが、「成功したように見えてコピーになる」とは書かれていません。

4. spellcheck を有効にしても何も起きない

症状

2.1.235 で追加された spellcheck を有効にしても、下線が出ない。

原因

この機能は外部の辞書ツールを使います。

using your installed aspell, hunspell, or ispell

Windows には3つとも標準で入っていません。

aspell   : (未インストール)
hunspell : (未インストール)
ispell   : (未インストール)

入れても、辞書が0個

winget で hunspell は4秒で入りますが、辞書は別です。

AVAILABLE DICTIONARIES (path is not mandatory for -d option):
（空）

辞書なしで動かすとこうなります。

Can't open affix or dictionary files for dictionary named "default".

そして終了コードは 0 です。 呼び出す側からは「エラーなく、指摘ゼロ」に見えます。

日本語では有効にしないほうがいい

英語辞書を入れて日本語の文を検査したところ、15箇所中14箇所（93%）がスペルミス扱いでした。

語	修正候補
を	`e, s, i, a, n, r, t, o, l, c, d, u, g, m`
md	`MD, Md, ms, m, d, med, mid, mad, mod, mud`

助詞の「を」を「e」に直せと言ってきます。 CLAUDE.md の md も引っかかります。

語の区切りも壊れます。漢字のところで切れるため、「このリポジトリのテストが」が1語として扱われました。辞書を足しても解決しません。

既定は無効なので、何もしなければ今までどおりです。

5. Windows 固有の落とし穴（まとめ）

Windows で踏んだものを集めました。

落とし穴	症状	対処
`ln -s` がコピーになる	同期しない。エラーは出ない	`ls -l` で確認。インポートを使う
辞書ツールが入っていない	`spellcheck` が無反応	`winget install FSFhu.Hunspell` ＋辞書
`MAX_PATH` 260文字	`pip install` が謎のエラーで落ちる	`--no-deps`、または短いパスへ
日本語＋全角スペースのユーザー名	ツールによっては落ちる	`\\?\` 対応のツールなら通る

MAX_PATH は実際に踏みました。エラーに出たパスがちょうど260文字で、1文字足りずに落ちていました。

failing path length: 260
LongPathsEnabled = 0

短いディレクトリ（C:\nd）に作り直しても同じ場所で落ちたので、インストール先ではなくパッケージの中身が原因でした。

6. 公式ドキュメントに載っていない環境変数

ここまでに出てきた変数を、公式の設定ドキュメントと突き合わせました。

変数	設定ドキュメント	挙動への影響
`CLAUDE_CODE_FORK_SUBAGENT`	記載なし	fork の可否
`CLAUDE_CODE_ENABLE_TASKS`	記載なし	Todo/Task ツールの可否
`CLAUDE_CODE_ENABLE_TODO_TOOLS`	記載なし	同上
`CLAUDE_CODE_CHILD_SESSION`	記載なし	セッションの扱い
`CLAUDE_CODE_ENTRYPOINT`	記載なし	起動元の識別
`spellcheck`（設定キー）	記載なし	入力欄のスペル検査

挙動を左右する変数が、設定ドキュメントに1つも載っていません。 根拠は changelog か、Agent SDK 向けのページに散っています。

そのため「ドキュメントに書いていない＝存在しない」とは限りません。症状が出たら、まず自分の環境変数を見るのが早道です。

7. 自分の環境を確認する

まずこれを実行してください。1行で現状が分かります。

env | grep -i "^CLAUDE" | sort

主要なものだけ見るなら、こちらです。

for v in CLAUDE_CODE_FORK_SUBAGENT CLAUDE_CODE_ENABLE_TASKS \
         CLAUDE_CODE_ENABLE_TODO_TOOLS CLAUDE_CODE_ENTRYPOINT; do
  eval "echo \"$v = \${$v:-(未設定)}\""
done

設定ファイルの場所も押さえておくと調べやすくなります。

対象	場所
ユーザー設定	`~/.claude/settings.json`
プロジェクト設定	`./.claude/settings.json`
ローカル設定（gitignore推奨）	`./.claude/settings.local.json`
MCP 登録	`~/.claude.json`
指示ファイル	`~/.claude/CLAUDE.md`、`./CLAUDE.md`

どのファイルが実際に読まれたかは、セッション内で /context を実行すると Memory files の一覧で確認できます。

8. 切り分けの手順

原因が分からないときの順序です。

1. バージョンを確認する。 挙動が変わった直後なら、更新が原因のことが多いです。

claude --version

2. 環境変数を疑う。 特に settings.json に書いていないのに設定されているものがあります。手元では CLAUDE_CODE_ENABLE_TASKS=0 が親プロセスから渡っていました。

3. claude -p で対照実験をする。 変数を1つだけ変えて挙動を比べます。

CLAUDE_CODE_FORK_SUBAGENT=1 claude -p '...'
env -u CLAUDE_CODE_FORK_SUBAGENT claude -p '...'

env -u で「未設定」を再現できます。空文字列を入れるのとは違うので、ここは -u を使ってください。

4. 設定ドキュメントになければ changelog を見る。 前述のとおり、載っていない項目が実際に効いています。

まとめ

Agent type 'fork' not found → CLAUDE_CODE_FORK_SUBAGENT=1。未設定は 0 と同じ
タスクリストが出ない → CLAUDE_CODE_ENABLE_TASKS=0 が犯人。ENABLE_TODO_TOOLS=1 で戻る（戻るのは Task ツール）
AGENTS.md は読まれない。 CLAUDE.md に @AGENTS.md と書く
Windows の ln -s はコピーになる。 エラーが出ないので気づけない。ls -l で確認
spellcheck は辞書ツールが別途必要。 日本語では9割に下線が引かれるので有効にしない
挙動を決める環境変数が、設定ドキュメントに載っていない。 症状が出たら env | grep CLAUDE から
切り分けは claude -p ＋ env -u で、変数を1つだけ変えて比べる

「設定したのに効かない」ときは、設定ファイルより先に環境変数を見るのが近道でした。

参考

各項目の詳しい検証は個別記事に書いています。

公式:

Claude Code changelog
Settings / Memory / Subagents

※ 引用は原文と日本語訳を併記しています。訳は読みやすさを優先しているので、正確な表現は原典をご確認ください。

JQITのエンジニアの95%以上は未経験からの採用です。
よければコーポレートサイトにも遊びに来てください。

▶ コーポレートサイト

エンジニア採用も行っています。もしご興味あれば覗いてみてください。

▶ 採用サイト

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up