logbook

logbook

コーディングエージェントは、Git の履歴を見落としがちです。膨大なうえ、適当に切り取ると誤った全体像を示すことがあります。

コードを読めても、その裏にある判断を知らない人が、機能を追加するたびに現れます。3 回書き直されたモジュール、試しては取り消されたアプローチ、前四半期の「修正」が実はテストのスキップだったことなどです。新しいエージェントセッションでは、こうした判断を知らない状態で始まることがよくあります。コードマップ（Graphify など）は、どこに何があるかは教えてくれますが、何があったかは教えてくれません。logbook は既存の Git 履歴（最新の 20,000 コミットまで）を分析し、エージェントが参照するよう指示される、コンパクトな想起レイヤーを書き出します。

npx -y @promptwheel/logbook init

一言で言えば、履歴を読み、概要を書き、エージェント設定（AGENTS.md、CLAUDE.md、または .cursorrules）に履歴を扱うワークフローを追加します。

  1,326 commits · 322 files · 7.3 years · 354 authors

  ✓ wrote LOGBOOK.md     hotspots · do-not-retry · suppression ledger
  ✓ wrote events.jsonl   1,326 structured events
  ✓ wrote JOURNEY.md     the repo's story, told back to you

単一ファイルです。npm 依存関係はゼロです。ソースコードにも Git 履歴にも一切触れず、リポジトリのデータがマシンの外に出ることもありません。書き込むのは自身の概要ファイルだけです（init はエージェント設定にブロックを追加します）。

「logbook」の由来

それは、検出器が復元できる判断を一覧できる、コンパクトな索引が必要だからです。図書館の本をすべて持ち出す必要はありません。GitHub の上位 2,500 リポジトリから無作為に選んだ 400 リポジトリのサンプルでは、全ログの 34% が、コンテキスト長の推定値で 150k トークンを超えていました。Logbook はその記録を、上限のある概要と検証可能な手がかりにまとめます。すべての判断を完全に想起できるとは謳っていません。

3 つの成果物

ファイル	内容	対象
LOGBOOK.md	新しいセッションに必要な概要：注目箇所、再試行禁止（取り消されたアプローチ）、抑制の記録（テストがスキップされたり警告が抑えられたりした事例）、アサーションを弱めた変更、壊れやすい箇所	エージェント向けです。コンテキストに追加してください。CLAUDE.md から参照できます
events.jsonl	分析対象のコミットごとに 1 件の構造化イベント：種別（src/test/config/docs）、追加／削除、差分で見つかった抑制、アサーションの変化	ツール向けです。データレイヤーです
JOURNEY.md	英雄の旅として描かれるリポジトリの履歴：「召命」「境界越え」「深淵」「長い冬」「ささやかれた取引」	あなた向けです。logbook journey を実行すると、色付きで表示されます

使い方

npx @promptwheel/logbook              # analyze the current repo
npx @promptwheel/logbook path/to/repo # or any repo
npx @promptwheel/logbook journey      # the story, in color (writes nothing)
npx @promptwheel/logbook journey --compare  # rank your almanac vs the top 2,500 GitHub repos
npx @promptwheel/logbook audit        # what is STILL suppressed in HEAD, and since when
npx @promptwheel/logbook doctor       # read-only artifact/wiring/skill/query health check
npx @promptwheel/logbook context --file path/to/file --revert  # bounded, paged query view
npx @promptwheel/logbook context --file src/a.ts --file src/b.ts # multi-path OR query
npx @promptwheel/logbook annotate SHA "why it happened" --by WHO   # persist WHY a commit happened
npx @promptwheel/logbook --json       # events to stdout (writes nothing)

# era-scoped archaeology
npx @promptwheel/logbook --since 2024-01-01 --until 2025-01-01

オプション：-n/--max N（コミット数の上限。デフォルトは 20000） · --compare · --out DIR · -q/--quiet

context はフィルタリング済みの query の順序を維持しつつ、最大 20 件のイベント、8 KiB までのページにシリアライズし、不透明な NEXT カーソルと明示的な END complete を付けます。これは配信形式であり、関連性の順位付けではありません。生の JSONL インターフェイスが必要な場合は query を使ってください。カーソルはリポジトリの HEAD、フィルター、分析対象期間、および順序付きイベントセットに紐づいています。いずれかが変わった場合は、最初のページからやり直してください。--file を繰り返し指定すると、指定したいずれかのパスに触れたコミットが対象になります。残りのフィルターは、その集合との共通条件として適用されます。各 NEXT カーソルでも同じフィルターを繰り返し指定してください。デフォルトの期間で初回実行する場合、CLI は 1 ページ目の後に events.jsonl を作成または更新するため、後続の NEXT ページではスキャン結果が再利用されます。ソースコードや Git 履歴が変更されることはありません。デフォルト以外の -n または --since/--until の期間はキャッシュされないため、CLI の各ページで指定期間が再スキャンされます。測定対象の 7,123 イベント全体では、0.8 表現のバイト数は生の行と比べて 72.7% 少なくなりました（手法と対象範囲）。

台帳はバッチ処理されます

コストのかかる処理（2 万件のコミット差分のスキャン）は、上限付きのウィンドウで一度だけ実行され、すべての利用者がその結果を再利用します。events.jsonl が存在し、HEAD と一致する場合は即座に読み込まれます。新しいコミットが追加されていれば、その分だけスキャンしてマージします。2 万件のコミットがあるリポジトリでの計測結果は、初回 43 秒、前回の実行結果がディスクにある場合は 0.4 秒、MCP セッション内での再呼び出しは 4 ミリ秒でした。回避策として、LOGBOOK_NO_CACHE=1 を指定すると全件再構築を強制し、LOGBOOK_WINDOW=N でスキャンウィンドウを調整できます。

--compare は、2,500 リポジトリのフリート実行から作成したパーセンタイルテーブルを CLI に組み込んでいます。依存関係もネットワーク呼び出しも引き続きゼロです。

信頼性と診断

Git のサブジェクト、パス、作成者、注釈は、リポジトリによって制御される入力です。Logbook はイベントレコードを変更せずに保存しますが、Markdown やエージェント向け監査出力を生成する際にはこれらの値をサニタイズし、信頼できない証拠としてラベル付けします。生成ファイルは一度に 1 つずつアトミックに置き換えられます。2 つの Markdown 成果物には、events.jsonl にひも付く HEAD、イベント数、スコープ、台帳ハッシュの一致したレコードが含まれます。複数ファイルの更新はトランザクションではないため、中断されたバンドルは次回のチェックで検出されます。

レポートが古く見える場合や、バグを報告する場合は、読み取り専用の doctor を実行してください。

npx -y @promptwheel/logbook@latest doctor

生成レコードの鮮度と台帳の整合性、現在のエージェント設定（上書きする AGENTS.override.md を含む）、インストール済みの Logbook スキル、実際のパスクエリをチェックします。Markdown の文章に対するユーザー編集を個別にハッシュすることはありません。何も書き込まず、チェックに失敗するとゼロ以外の値を返し、issue やリリーススレッドへの返信に貼り付けやすい簡潔なレポートを出力します。

エージェントに組み込む

logbook init がこれを行います。手動で設定する場合は、CLAUDE.md（または AGENTS.md / .cursorrules）に 1 つのブロックを追加し、新しいセッションのたびに、まず履歴を読むよう指示します。

## Repo memory
Before planning or editing:
1. Read LOGBOOK.md at the repo root completely before any history query.
2. If Historical signal is LOW, use it only as a hotspot map. Otherwise,
   inspect task-relevant do-not-retry entries and fragile areas.
3. For complete do-not-retry coverage, inspect all relevant paths:
   npx -y @promptwheel/logbook context --file path/to/file --revert
   Repeat --file for each other relevant path. If output says NEXT, repeat the
   identical filters with --cursor TOKEN until END complete before concluding.
4. Treat findings as leads, not verdicts. Verify claims with git show SHA and
   confirm that the constraint still applies to the current tree.
Refresh the record: npx -y @promptwheel/logbook
Check what is still silenced: npx -y @promptwheel/logbook audit
When you investigate WHY a listed commit happened and verify it in the
diffs, persist it (replace SHA, the sentence, and MODEL with your own
model name; never annotate guesses):
npx -y @promptwheel/logbook annotate SHA "one specific sentence" --by MODEL

この設定により、エージェントが履歴のワークフローを独自に考え出すのではなく、それを使うようになります。これはあくまで指示であり、保証ではありません。実際の参照は完全ではないため、リスクの高い作業では確認してください。

遅延エンリッチメント：レコードは WHAT を示し、エージェントは WHY を記録する

台帳からリファクタリングがリバートされたことは分かりますが、webpack4 が壊れたためにリバートされたことまでは分かりません。エージェントは、そのリバートに関連するタスクに初めて直面した際に、いずれにせよその理由を突き止めます。annotate を使えば、セッション終了時にその発見を破棄せずに保持できます。

logbook annotate c08adc2 "WeakMap cache added to dodge a React-Compiler lint warning; reverted to direct ref mutation" --by claude

LOGBOOK.md はすぐに更新されます（ディスク上に新しい成果物が見つかった後続のセッションでは、CLI を再実行しない場合があります）。また、再試行禁止の項目には理由が記録されます。

- 2024-09-15 c08adc2 revert useShallow refactor in #2701 (#2703)
  - why (inferred by claude, 2026-07-11): WeakMap cache added to dodge a React-Compiler lint warning; reverted to direct ref mutation

注釈は annotations.jsonl に保存されます。sha をキーとし（不変なので、事実として古くなることはありません）、帰属情報と日付を記録し、各コミットについて最後に書き込まれた注釈が有効になります。注釈はレコードに重ねる判断であり、レコード自体には混ぜません。決定論的な台帳は変更されず、理由は出典情報と免責事項付きで表示されます。A/B ベンチマークでの計測では、理由が記録されたログブックを持つエージェントは、エンリッチメントされていないエージェントが調査を計画したのに対し、計画段階で実際の失敗原因を設計上の制約として述べました（読み取りトークンは +2％）。また、zustand では原因を誤って推測しました。注意点として、注釈は事実として無効になることはありませんが、制約としては古くなります。webpack4 が廃止されれば、「webpack4 が壊れた」という理由はもはや制約ではありません。そのため、日付は常に表示されます。チームで共有する記憶として使う場合はファイルをコミットし、個人用にする場合は gitignore に追加してください。

監査：履歴の調査を ToDo リストに変える

logbook audit は、台帳の日付と HEAD で現在も当てはまる内容を照合します。

  describe.skip  test/express.static.js:137  since 2019-05-02 (7.2y)

  1 live suppression · oldest 7.2 years

これは express で、現在も続いている問題です。静的ファイルのテストスイートが 7 年間スキップされています。台帳はそれがいつ起きたかを示し、監査はそれが今も続いていることを示します。また、抑制が解除された後に再追加された場合、監査にはその攻防の記録が表示されます。re-silenced ×3 (+-++--+)――修正を何度も試みられながら、何度も失敗しているテストです。

コンテキストの経済性

上位2,500件から無作為に抽出した400リポジトリのサンプルでは、LOGBOOK.md の推定トークン数の中央値は 約1,000トークンでした。サンプル内の git log 全体の中央値はその82倍で、 34％は推定15万トークンを超えていました。これは、セッションで生の履歴を 取り込む必要がある場合にのみ削減できるコンテキスト量です： docs/context-economics.md。

エージェントの動作は実際に変わるのでしょうか？

履歴が密集した計画タスクを選んだ場合は、変わります。ただし、重要な境界があります。履歴をあまり考慮して選んでいない新しい10件のタスクを対象に後から検証したところ、パッケージ化された Logbook を使う群は、強力な生のGitの指示を上回りませんでした（安全な計画は2/10件に対して3/10件）。既知のレシートはすべてインデックス化されていましたが、Logbook のクエリを通じてエージェントに届いたものはなく、検索と利用がボトルネックだと分かりました。docs/wrong-work-benchmark.mdのエビデンス状況に関する注記を参照してください。最初のA/Bテストでは、zustand の useShallow リファクタリングを計画するよう求められたエージェントが、2024年にマージ後に取り消されたリファクタリングを再び試みようとしました。同じエージェントに LOGBOOK.md をコンテキストとして与えると、取り消しを出発点とし、再試行禁止リストからそのリポジトリに特徴的な失敗の種類を推測して、まずテストで過去の失敗を再現する計画を立てました。トランスクリプト全文：docs/does-it-change-agent-behavior.md。

履歴が意図的に密集した計画タスクを対象とする6件の社内実験では、履歴を与えられなかったエージェントは、すでに取り消された作業や完了済みの作業を6件中4件で提案しました。一方、生成された LOGBOOK.md 全体を与えられたエージェントでは、そうした提案は6件中0件で、コンテキストは約4.7kトークン増加しました。これは計画のみを対象とし、社内で評価したもので、過去の落とし穴があるタスクを選んでいます。手法と対象範囲： docs/wrong-work-benchmark.md。

適用範囲について

• 調査結果は手掛かりであり、断定ではありません。抑制コミットは「人間が確認すべき場所」を示すものであり、不正行為を意味するものではありません。大規模なアサーション削除は通常、機能の削除であり、そのようにタグ付けされています。
• 検出にはコミットの件名と差分に対する正規表現を使います（系譜：エージェントが作成したコードを対象とする1,800件のPR調査で調整した分類器）。巧妙な回避は見逃し、一部の無害な変更にはフラグを立てます。数秒で実行できる依存関係ゼロのツールとしては、これが適切なトレードオフです。また、これは意図的な役割分担でもあります。ログブックは低コストで決定論的な想起レイヤーであり、それを読むエージェントは、タスクに照らして手掛かりを選別する精度レイヤーです。
• 残された情報を読み取ります。スカッシュやリベースによってブランチ内の試行は消えます（試してから取り消した変更は、スカッシュ後の差分では差し引きゼロになります）。また、コミットされていない実験はそもそも見えません。ログブックは、作業中にエージェントが記録するジャーナルを補完するものです。まさにそのための橋渡しが annotate であり、ジャーナルに取って代わるものではありません。
• シャロークローンでは分析に必要な情報が不足します。ログブックは git fetch --unshallow を実行するよう案内します。

ログブックは記録し、審判役が判断する

このツールは、2つで構成される仕組みの一方です。ログブックは、3月にテストが省略されたことを伝えます。promptwheel — 審判役 — は、今日の「成功」がコードによるものか、テストの編集によるものかを証明します。同じ問いの過去形と現在形です。これは本当に改善したのでしょうか？

MIT。