0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@TaichiEndoh(遠藤 太一)

ループエンジニアリング - 公式は「このログを直接パースするな」と言っている

0
Posted at

公式は「このログを直接パースするな」と言っている

ループエンジニアリング 後編：実装で最初につまずく4つのこと
対象読者：前編を読んで、実際にループを組もうとしている人
読了時間：約7分

前編：ログを読ませる前に、ログを読む（※前編のURLをここに貼る）

この記事のポイント（4行）

  • Anthropic 公式は .jsonl の直接パースを推奨していません。正しい入口が4つ示されています
  • Claude Code のログは既定で30日で消えます。資産にしたいなら先に退避先を決める必要があります
  • ルールを溜め続けると効かなくなります。500指示で最良モデルでも精度68%、しかも前方の指示を優先する位置バイアスがあるという実証データがあります
  • SessionEnd フックの既定の実行予算は1.5秒。ここを知らずに書くと、静かに何も起きません

⚠️ 先に、大事な前置き

この記事は筆者の現時点での個人的見解です。法的助言ではありません。

所属先のデータを扱う場合は、必ず自組織の情報システム部門・情報セキュリティ責任者・医療機関であれば医療情報安全管理責任者に確認したうえで判断してください。筆者は、この記事の内容を実際の業務で使われたことに起因するいかなる損害についても責任を負いません。

また、ツールの仕様は頻繁に変わります。この記事は2026年8月時点の一次情報に基づいています。実行前に必ず最新の公式ドキュメントを確認してください。

5. 🎯 公式は「直接パースするな」と言っている

もう1つ、あまり触れられていない事実があります。

Claude Code のセッションログの保存場所は、公式ドキュメントに明記されています。

~/.claude/projects/<project>/<session-id>.jsonl

<project> は作業ディレクトリのパスの英数字以外をハイフンに置き換えたものです。ここまではよく紹介されています。

問題は、その直後に書いてある一文です。

The entry format is internal to Claude Code and changes between versions, so scripts that parse these files directly can break on any release.
（エントリの形式は Claude Code の内部形式であり、バージョン間で変わる。したがってこれらのファイルを直接パースするスクリプトは、どのリリースでも壊れうる）

出典：Anthropic「Manage sessions」Claude Code Docs
https://code.claude.com/docs/en/sessions

つまり、uuid や parentUuid や type といったフィールド名を前提にしたスクリプトは、公式には保証されていません。ネット上でよく見かけるフィールド構成の解説は、コミュニティによるリバースエンジニアリングの結果であって、Anthropic が保証したものではない。ここは記事や動画ではまず語られていない点です。

✅ 公式が示している正しい入口

同じドキュメントに、代替手段が4つ挙げられています。

  • /export — セッションを書き出す
  • claude -p --output-format json — 1回実行の結果を構造化された形で受け取る（stream-json も可）
  • hooks が受け取る transcript_path — フックの入力JSONにトランスクリプトのパスが渡ってくる
  • Agent SDK（TypeScript / Python） — メッセージをプログラムから直接受け取る

「1行プロンプトで jsonl を読ませる」という使い方は、AIに読ませて要約させるだけなら実務上は動きます。ただしパイプラインとして組むなら、上の4つのどれかに寄せたほうが壊れません。

⚠️ そして、ログは30日で消えます

もう1つ知っておくべきこと。Claude Code のセッションログの保持期間は、settings.json の cleanupPeriodDays で決まり、既定は30日です。

「ログが資産になる」と考えて溜め始めるなら、先に退避先を決めておく必要があります。気づいたときには消えている、という話になりかねません。

6. 🎯 ルールを溜め続けると、効かなくなる

学習内容を1つのファイルに蓄積していく手法（Learnings.md などと呼ばれます）は理にかなっています。ただ、溜め続けると逆効果になることが実証的に示されています。

500個の指示を与えると、最良のモデルでも68%

2025年の研究「How Many Instructions Can LLMs Follow at Once?」では、指示の数を増やしながらLLMの追従率を測定しています。7社20モデルを検証した結果、**最も優秀なモデルでも500個の指示を同時に与えた場合の精度は68%**にとどまりました。

さらに重要なのは、モデルが文脈の前方にある指示を優先する位置バイアスを示したという点です。

出典：Jaroslawicz et al. (2025). How Many Instructions Can LLMs Follow at Once? arXiv:2507.11538
https://arxiv.org/abs/2507.11538

長い文脈の「まんなか」は読まれにくい

関連する古典的な知見として、2023年の「Lost in the Middle」があります。関連情報が文脈の先頭か末尾にあるときは性能が高く、中間にあると性能が有意に落ちる、というU字型の傾向を示した研究です。

出典：Liu et al. (2023). Lost in the Middle: How Language Models Use Long Contexts. arXiv:2307.03172
https://arxiv.org/abs/2307.03172

つまり、ルールを100個溜めたファイルを毎回読ませても、まんなかの40個くらいは実質的に効いていない可能性があるということです。

紹介されている手法の多くも「週に1回、内容を整理・統合せよ」と言っています。それは正しいのですが、なぜ必要なのかの根拠までは書かれていないことが多い。根拠はここにあります。整理は好みの問題ではなく、性能の問題です。

そして整理には別のジレンマがあります。抽象化しすぎると具体的な再発防止策が失われる。「実装を読まずに憶測で書いた」という具体的な失敗録は、「事実確認を徹底する」という抽象的な原則に丸められた瞬間に、効き目を失います。ここは自動化しきれない部分だと、筆者は考えています。

7. 🔧 実装で最初につまずくところ：SessionEnd の1.5秒

「セッション終了時にフックを立てて、その日の学びを自動追記させる」という手法がよく紹介されます。実際に組もうとすると、公式仕様に1つ壁があります。

Claude Code の SessionEnd フックは、全体で1.5秒の実行予算を共有します。timeout を明示的に設定すれば最大60秒まで引き上げられますが、既定のままだと1.5秒です。

出典：Anthropic「Hooks reference」Claude Code Docs
https://code.claude.com/docs/en/hooks

LLMを呼んで「今日の学びを要約して追記する」という処理は、1.5秒ではまず終わりません。つまり既定のままフックを書くと、静かに何も起きないということになります。

対処としては、

  • timeout を明示的に設定する
  • あるいは、フックでは transcript_path を退避するだけにして、要約は別のタイミング（翌朝のバッチなど）で回す

後者のほうが素直だと思います。フックは記録係に徹させ、考えるのは別の工程に分ける。

なお、セッション開始時にファイルを読ませる SessionStart フックは startup / resume / clear / compact / fork を matcher で切り分けられます。コンパクション後にルールを再注入する使い方は、公式ドキュメントにサンプルが載っています。

8. セッション間の連携は、公式機能になりました

「セッションのログファイルのパスを別のセッションに渡して続きをやらせる」という運用の工夫が共有されていますが、これはすでに公式機能になっています。

Anthropic 公式リポジトリの CHANGELOG に、バージョン 2.1.224 の項目としてこう記載されています。

Added cross-session SendMessage: Claude Code sessions can now message each other, on any of your machines, with ListAgents to discover them (macOS and Linux)

出典：anthropics/claude-code CHANGELOG.md
https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md

ListAgents で相手を見つけ、SendMessage で送る。macOS と Linux のみという制約はありますが、パスを手で貼り付ける必要はもうありません。

この領域は動きが速いので、手作業のハックを組む前に CHANGELOG を見る癖をつけたほうがよさそうです。

✅ 今夜やる、1つのこと

全部やる必要はありません。1つだけ選ぶなら、これです。

いま使っているフックの timeout を確認する。

SessionEnd に何か書いているのに「動いている実感がない」なら、たぶん1.5秒で切られています。設定していないなら、それは設定漏れではなく仕様です。

まとめ

  • Anthropic 公式は jsonl の直接パースを推奨していません。/export、claude -p --output-format json、hooks の transcript_path、Agent SDK が公式に示された入口です
  • ログは既定で30日で消えます（cleanupPeriodDays）。溜める前に退避先を決めてください
  • ルールを溜め続けると効かなくなります。500指示で68%、位置バイアスあり。週1回の整理は好みの問題ではなく性能の問題です
  • ただし抽象化しすぎると具体的な再発防止策が失われます。ここは自動化しきれない部分だと考えています
  • SessionEnd フックの既定予算は1.5秒。フックは記録係に徹させ、考えるのは別の工程に分けたほうが素直です
  • セッション間の連携は SendMessage / ListAgents として公式機能になりました（macOS / Linux）

ログを見る前に、ログを見る。そして仕組みを組む前に、公式ドキュメントを読む。医療機器の世界では当たり前にやっていることが、AIの世界ではまだ手順に入っていない。この2本を通して言いたかったのは、それだけの話です。

⚠️ 最後にもう一度

この記事は筆者の現時点での個人的見解です。法的助言ではありません。

業務データを扱う場合は、必ず自組織の情報システム部門・情報セキュリティ責任者と相談したうえで判断してください。医療機関の場合は、医療情報安全管理責任者への確認を必ず行ってください。患者情報を含む可能性のあるデータは、いかなる形でも外部のLLMに入力しないでください。

ツールの仕様は変わります。実行前に必ず最新の公式ドキュメントを確認してください。

筆者は、この記事の内容を実際の業務で使われたことに起因するいかなる損害についても責任を負いません。

出典・参考資料（後編）

著者プロフィール

臨床工学技士 × AIエンジニア / 11年間、病院の医療機器の現場に立ち続けてきました。
いまはAIエンジニアとしても活動しながら、酪農学園大学の研究生として論文博士の取得を目指しています。
研究テーマの主軸は遺伝子医療の未来。そのうえで、医療現場と地続きにある病院のIT・サイバーセキュリティ・医療AI導入についても、現場で起きている課題と一次情報を突き合わせながら調べ続けています。

質問・誤りの指摘・「うちではこうしている」という事例の共有、いつでも歓迎します。

X：@endoh_taichi
Qiita：@TaichiEndoh

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?