【ITニュース解説】The transcript is the record: reading what a coding agent actually did

近年、AIを活用してコードを生成したり、開発作業を支援したりする「コーディングエージェント」が注目されている。システムエンジニアを目指す皆さんにとって、これらのエージェントがどのように機能し、どのような情報を残すのかを理解することは、将来の仕事に不可欠な知識となるだろう。特に、エージェントが「何をしたのか」を正確に把握するための「作業記録」の重要性について解説する。

皆さんがターミナル（コマンドラインの画面）でコーディングエージェントとやり取りをする際、画面にはエージェントの応答や作業の進行状況が表示される。しかし、この画面表示は決して完全な作業記録ではない。画面は常に新しい情報で上書きされたり、スクロールアウトして見えなくなったり、ウィンドウのリサイズによって表示内容が失われたりする。もし作業中に重要な情報が画面から消えてしまえば、後からその内容を確認することは非常に難しくなる。このような画面の特性から、ターミナルに表示される情報だけを頼りにエージェントの作業を評価することは、正確性に欠け、重要な部分を見落とすリスクがある。

しかし、安心してもらいたい。多くのコーディングエージェントは、ターミナルに表示される内容とは別に、作業中のすべてのステップを詳細な「作業記録（トランスクリプト）」として、構造化されたファイルとしてユーザーのコンピュータのディスクに保存している。これは、エージェントが何を実行し、何を考え、どのような応答を生成したかという、まさにその「監査証跡」とも言える情報である。例えば、人気のあるエージェントであるClaude CodeはJSONL形式のファイルを、CodexもJSONL形式のファイルを、OpenCodeはSQLiteデータベースを、それぞれユーザーのホームディレクトリ配下に保存している。これらのファイルは、エージェントが作業を行うその瞬間に逐次書き込まれるため、画面表示のように情報が失われる心配がない。

では、多くの記録ファイルの中から、特定のタスクの記録をどうやって見つけ出すのか。これは、複数の作業を繰り返す中で多くの記録が生成されるため、少し工夫が必要となる。まず有効な手がかりの一つは「ディレクトリ名」だ。Claude Codeのように、多くのエージェントは、作業が行われたプロジェクトのディレクトリ名を元に、記録ファイルを保存するフォルダ名やファイル名を生成する傾向がある。これにより、大まかな絞り込みが可能になるが、パスが長すぎるとファイル名が短縮されたりハッシュ化されたりするため、これだけでは完全な特定には至らない場合もある。次に、「時間情報」も重要な手がかりとなる。記録ファイルの作成日時や最終更新日時を参照し、目的のタスクが開始された後に作成・更新されたファイルに限定することで、候補をさらに絞り込める。ただし、同じディレクトリで非常に短い時間のうちに複数のタスクを実行した場合、時間情報だけでは区別が難しいこともある。

最も確実な特定方法は、「完了マーカー」を利用することだ。これは、エージェントへの指示（プロンプト）の中に、タスクが完了した際に必ず出力するよう指定する、ユニークな文字列のことである。例えば、「タスク完了時には必ず『---TASK_COMPLETED_XYZ---』と出力せよ」といった指示をプロンプトに含めるのだ。これにより、記録ファイルの中からこのユニークなマーカーを含むものを探し出すことで、そのタスクの記録をほぼ確実に特定できる。エージェントが内部で生成するセッションIDは通常ユーザーには開示されないため、この完了マーカーは、特定のタスクの記録を識別する上で非常に強力な手段となる。これらの手がかりを「ディレクトリで絞り込み、時間で絞り、最後に完了マーカーを探す」という順序で適用することで、目的の記録を効率的に見つけ出すことができるだろう。

この作業記録からは、エージェントが最終的に生成した回答の「生のテキスト」や、作業中に発言した詳細な内容を、ユーザーインターフェースによる装飾なしで読み取ることができる。これにより、エージェントが何を意図し、どのような結論に至ったかを具体的に把握することが可能となる。しかし、この記録から読み取れないことも理解しておく必要がある。例えば、エージェントが内部で実際に実行したコマンドの正確なタイムラインや、コードの変更内容を示す差分（diff）といった情報は、記録には含まれていない。また、エージェントの作業が「正しかったのか」あるいは「品質が良いのか」といった、作業自体の評価も記録からは得られない。これらの記録はあくまでエージェント自身の「主張」であり、その内容が正しいかどうかは、別途、皆さんがコードリポジトリの実際の変更内容を確認したり、テストを実行したりするなどして、検証する必要がある。

これらの作業記録を扱う上で、いくつかの重要な注意点がある。まず、記録ファイルの形式や保存場所は、エージェントの開発元が公開している「正式なAPI」ではない。これはつまり、エージェントがバージョンアップするたびに、記録の形式や保存場所が予告なく変更される可能性がある、ということだ。過去には、OpenCodeが記録方法をファイルからSQLiteデータベースへと移行した例もある。そのため、もし皆さんが記録を読み取るツールを自作したり利用したりする場合には、ファイルが見つからない、解析できない、形式が変わった、といった状況でも、エラーで停止するのではなく、画面表示を読むなどの代替手段に柔軟に切り替える（フォールバックする）ように設計されていることが望ましい。

さらに、これらの記録は基本的に、エージェントを実行した「自分のローカルコンピュータ上」に保存される。そのため、クラウドサービスとして提供されるエージェントなど、ユーザーがファイルシステムに直接アクセスできない環境では、この詳細な作業記録を利用することはできない。また、通常、読み取ることができるのは記録ファイルの「最新の部分」（例えば、最新の数千文字程度）に限られることが多く、非常に古い作業内容全体を詳細に遡って分析することは一般的ではない。このように、作業記録のフォーマットは不安定で、利用には継続的なメンテナンスと注意が求められるという、具体的なコストも認識しておくべきだろう。

まとめると、コーディングエージェントの作業記録は、AIとの協調開発において、エージェントの「思考プロセス」や「具体的な振る舞い」を深く理解するための非常に貴重な情報源である。しかし、その利用には、記録の性質や限界、そして技術的な不安定さをしっかりと理解し、適切に対処するための知識と準備が不可欠となる。システムエンジニアを目指す皆さんにとって、このようなツールの裏側の仕組みを理解することは、将来AIと効果的に協働し、より高品質なソフトウェアを開発していく上で、極めて重要なスキルとなるだろう。