Todo ツールが既定オフになった Claude Code で、多段作業の進捗をどう追うか

私が変数を戻さず、台帳を置いた理由

切り分けが済んだあと、素直に CLAUDE_CODE_ENABLE_TODO_TOOLS=1 を書き足すこともできました。実際、途中で人が横から介入する作業では戻す価値があります。

ただ、私が任せている定期メンテナンスは、走り出したら基本的に見ていません。後から見返すのは「何をやると宣言したか」ではなく「結局どのファイルが変わったのか」です。チェックリストは着手前の宣言であって、完了の証拠ではありません。

以前 Claude Code の TodoList はタスク粒度で品質が決まる で、項目は検証可能な単位で切るべきだと書きました。今回はその考えを一段進めて、宣言そのものを外部に持たせるのをやめ、実際に起きたことだけを記録する方針に変えています。

置いたのは PostToolUse フックで追記する作業台帳です。ファイルを変更するツールが走るたびに1行を足していきます。

#!/usr/bin/env bash
# ~/.claude/hooks/record-change.sh
# PostToolUse フック（matcher: Edit|Write|NotebookEdit）
set -euo pipefail
 
LEDGER_DIR="${CLAUDE_LEDGER_DIR:-$HOME/.claude/ledger}"
mkdir -p "$LEDGER_DIR"
 
# jq は1回だけ呼ぶ。file_path も notebook_path も無い呼び出しは select で落とす。
# フックの失敗でセッションを止めないため、最後は必ず exit 0 で抜ける。
jq -c --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '
  (.tool_input.file_path // .tool_input.notebook_path // "") as $f
  | select($f != "")
  | {ts: $ts,
     session: (.session_id // "unknown"),
     agent:   (.agent_id   // "main"),
     tool:    (.tool_name  // "unknown"),
     file:    $f}
' >> "$LEDGER_DIR/$(date -u +%Y-%m-%d).jsonl" 2>/dev/null || true
 
exit 0

設定側は次のとおりです。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|NotebookEdit",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/record-change.sh" }
        ]
      }
    ]
  }
}

agent_id を入れているのは、サブエージェントが並列で動く構成では「誰が触ったか」が後で効くからです。フックがサブエージェント内で発火した場合に限り、この項目が入ってきます。

最初に書いた版では、session_id・agent_id・tool_name・file_path をそれぞれ別々の jq で取り出していました。手元の環境（jq 1.6）で200回続けて呼んで平均を取ると1回あたり95ミリ秒。上のように1回にまとめた版では28ミリ秒で、およそ3.4倍の短縮でした。1回の差は小さく見えますが、フックはファイルを変更するたびに走ります。数百回の編集が走る作業では、この差がそのまま体感の重さになります。

2>/dev/null || true を付けているのは意図的です。壊れた JSON が渡ってきたとき、jq はパースエラーを標準エラーに吐きます。フック自体は終了コード0で抜けるので作業は止まりませんが、ターミナルにエラーが混ざると本来の出力が読みにくくなります。

8並列にしたら、台帳が静かに壊れました

ここからが、事前の予想と逆だった部分です。

追記だけの単純なログなので、並列で書いても壊れないと思っていました。実際、短い行では壊れません。8個のプロセスから60回ずつ、合計480行を同時に追記した結果は480行すべて有効な JSON で、1行あたり平均163バイトでした。

問題は行が長くなったときです。深い階層のパスを持つプロジェクトを想定して、1行が5,293バイトになる条件で同じことをしました。8並列で合計320行。行数はきっちり320行ありました。ところが jq に通してみると、有効な JSON として読めたのは232行だけでした。88行、率にして27.5%が別の行と混ざって壊れていたのです。

行数だけ見れば正常に見えるのが厄介なところです。壊れた記録は、必要になったときに初めて役に立たないことが分かります。

境界は追記の1回の書き込みサイズにあります。おおむね4KiB を超えたあたりから、別プロセスの書き込みが割り込むようになります。並列度を上げること自体は問題ではなく、1行の長さが効きます。サブエージェントのフォークが既定で背景実行になった今、同じ台帳に複数の書き手がいる構成は珍しくありません。

対処は明快で、追記の前後をロックで囲みます。

#!/usr/bin/env bash
# 長い行でも割り込まれない版
set -euo pipefail
 
LEDGER_DIR="${CLAUDE_LEDGER_DIR:-$HOME/.claude/ledger}"
mkdir -p "$LEDGER_DIR"
OUT="$LEDGER_DIR/$(date -u +%Y-%m-%d).jsonl"
 
# 9> でロックファイルを開き、flock で追記の全体を保護する。
# ブロック全体を { } で囲むのが要点。jq だけを囲むとリダイレクトが外に出てしまう。
{
  flock 9
  jq -c --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '
    (.tool_input.file_path // .tool_input.notebook_path // "") as $f
    | select($f != "")
    | {ts: $ts,
       session: (.session_id // "unknown"),
       agent:   (.agent_id   // "main"),
       tool:    (.tool_name  // "unknown"),
       file:    $f}
  ' >> "$OUT" 2>/dev/null || true
} 9>"$LEDGER_DIR/.lock"
 
exit 0

同じ条件（8並列・5,293バイト・320行）で試したところ、320行すべてが有効な JSON になりました。短い行での負荷も測り直しましたが、1回あたり28ミリ秒が30ミリ秒になった程度です。2ミリ秒で静かな破損を防げるなら、迷う理由はありませんでした。

数値は手元の Linux 環境（jq 1.6）で測ったものです。絶対値は環境で動きますが、行が長くなると壊れ始めるという性質そのものは変わりません。

台帳を読む側を用意して、はじめて意味が出る

書き溜めるだけでは使えません。ファイル単位でまとめ、最後に触れた順に並べる読み手を用意しました。

#!/usr/bin/env bash
# ~/.claude/hooks/ledger.sh [YYYY-MM-DD]
set -euo pipefail
 
LEDGER_DIR="${CLAUDE_LEDGER_DIR:-$HOME/.claude/ledger}"
DAY="${1:-$(date -u +%Y-%m-%d)}"
FILE="$LEDGER_DIR/$DAY.jsonl"
 
[ -f "$FILE" ] || { echo "no ledger for $DAY"; exit 0; }
 
jq -rs '
  group_by(.file)
  | map({
      file:   .[0].file,
      edits:  length,
      last:   (map(.ts) | max),
      agents: (map(.agent) | unique | join(","))
    })
  | sort_by(.last)
  | .[]
  | "\(.last)  \(.edits)x  \(.agents)  \(.file)"
' "$FILE"

出力はこうなります。

2026-08-16T03:07:47Z  2x  main   /repo/src/api/client.ts
2026-08-16T03:07:47Z  1x  ag-7   /repo/src/api/retry.ts

同じファイルに何度も戻っている箇所は、たいてい迷いが出た場所です。チェックリストの「完了」印には表れませんが、台帳では編集回数として素直に出ます。私はここを見て、あとから自分でレビューする範囲を決めています。

読み手を先に決めておくと、書き手側に何を入れるかも定まります。逆にすると、記録に何でも詰め込んで行が長くなり、先ほどの破損に近づいていきます。

戻すか、置き換えるか

どちらが正解ということはなく、作業の性質で分かれると考えています。台帳を選ぶ場合と変数で戻す場合、私自身の使い分けは次のとおりです。

環境変数で戻した方がよい場合

• 人が横で見ていて、途中で方針を変える可能性がある作業
• エージェントチームで共有タスクリストを前提に分担している場合。持たないエージェントはメッセージで調整することになり、手数が増えます
• 手順そのものを他の人に説明する必要がある作業

戻さず台帳に寄せた方がよい場合

• 走り出したら見ていない定期実行。宣言よりも結果が要る
• コンテキストの余裕が乏しい長時間の作業。ツール定義とリマインダーの分を丸ごと空けられます
• 後から「何が変わったか」を機械的に突き合わせたい作業

セッション単位で切り替えられるのも利点です。全体に効かせたくなければ、claude --allowedTools TaskCreate のように起動時に名前を挙げるだけでも読み込まれます。

チームで使う場合は、どちらかに揃えて明文化しておくことをお勧めします。共有タスクリストを持つメンバーと持たないメンバーが混在した状態は、片側からは割り当てたつもりで、もう片側からは見えていないという食い違いを生みます。どちらの向きに揃えるにせよ、二度診断するより安く済みます。

私はしばらく、対話セッションは戻さないまま、台帳だけを常時走らせています。チェックリストが消えて最初は落ち着かなかったのですが、実際に困ったのは初日だけでした。結果を見る習慣がつくと、宣言を眺めていた時間がそれほど役に立っていなかったことに気づきます。

まずは PostToolUse に上のフックを1本だけ入れて、いつもの作業を1回走らせてみてください。その日の台帳を眺めると、自分がどのファイルに何度も戻っているかが分かります。そこが、次に整理すべき場所です。