debugkit

debugkit

何かが壊れているのに、誰にも原因がわからないときに頼るスキルです。他のビルドスキルはすべて、計画、課題、差分、確定した判断といった意図を入力として受け取ります。debugkit が受け取るのは症状であり、その症状を誰かが対処できる原因へと変えることが、debugkit の役割です。

これは単一の手順です。モードはありません。どのバグでも同じ手順を実行し、内部の分岐はユーザーの依頼ではなく、証拠から判断できることに基づいて決まります。

診断はしますが、修正はしません

debugkit は調査のためにリポジトリを自由に変更し、その変更をすべて元に戻します。 ログ行、二分探索、設定の調査、コメントアウトした分岐などはすべて使用できますが、実行後に残るものはありません。残るのは原因、失敗を再現するもの（赤になったテストは引き継ぎ用の成果物としてディスクに残ります）、そして適用するのではなく説明された修正案です。

この境界を設けるのは、謙遜のためではありません。報告の信頼性を保つためです。原因を見つけ、さらに解決策まで適用するスキルは、すでに答えを決めています。そのため、あとで読む内容は、すでに行われた編集を正当化するものになってしまいます。診断と変更を別々の担当に任せれば、その間に異議を唱えられる瞬間が生まれます。

このスキルのツールに Edit が含まれているのは、調査のために追跡対象ファイルを編集するからです。だからこそ、調査記録は飾りではなく、不可欠なものです。デバッグセッションと、誰かのコミット前の作業を隔てる唯一のものだからです。

どのようなときに使うか

「デバッグして」「なぜ失敗するのか」「根本原因を見つけて」「実際の原因は何か」「このテストは不安定だ」「アップグレード後に壊れた」「昨日は動いていたのに今は動かない」「このエンドポイントが遅くなった」「/debugkit」。

境界は5つ。それぞれ1行で説明します。

• コードレビューではありません。 レビューでは、誰かが書いたばかりの作業に欠陥がないか、差分を読みます。debugkit は、すでに実行されて誤動作したコードの症状を追います。誰も実行していない差分に現れた症状は、デバッグではなくレビューの対象です。
• テスト計画ではありません。 機能をどう検証するかの計画は、バグが発生する前に行います。debugkit は、何かがすでに失敗したあとに開始します。
• プロトタイプではありません。 使い捨ての試作は、まだ確定していない意図（「この設計は実用に耐えるか？」）に答えます。debugkit は、観測された失敗を説明するために調査します。ツールは似ていますが、問いは正反対です。
• 機能リクエストではありません。 受付条件を参照してください。これまで実装されたことのない動作は、壊れているのではなく、まだ存在しないのです。
• 最適化ではありません。 パフォーマンスのリグレッションは対象です。「以前は速かった」なら二分探索できる変更があり、変更前後を明確に比較できるため、手順をそのまま実行できます。「もっと速くして」は対象外です。見つけるべき原因はなく、プロファイルを読むだけだからです。また、以下のすべてのゲートは、動作していた状態が動作しなくなったことを前提としています。

受付条件

手順を開始する前に、3つの事実が必要です。どれかが不足していたら一度だけ尋ね、揃うまで先に進まないでください。

事実	必要な理由
期待される動作	何が起きるべきだったか
実際の動作	代わりに何が起きたか
発生箇所	どの環境、ブランチ、マシンで発生したか

期待と実際の違いが、そのまま症状です。「壊れています」としか伝えられないと、エージェントは期待される動作を作り上げ、それを基準にデバッグします。そして、その作り上げた期待こそが、間違ったものを直す自信満々の修正すべての根本原因になります。「発生箇所」は答える手間がほとんどかからず、再現の手順へ進むか、証拠のみのモードに進むかをすぐに判断できます。

受付条件は、意図的に一文で答えられるようにしています。クリアするのに10分かかる条件は、無視されてしまうからです。

切り返しは一度だけ。 「期待される動作」が、これまで一度も実装されていない動作だとわかった場合、それはバグではなく機能リクエストです。その旨を伝え、計画スキルに引き継いでください。インストールされていれば plankit を使い、そうでなければ、これは診断ではなく計画が必要だと明確に伝えてください。

3つの終了状態

すべての実行は、必ず次のいずれか1つで終わります。4つ目はありません。それを作り出すことこそ、このスキルが防ごうとしている失敗です。

結果	意味	引き継ぎ先
原因を証明済み	オン／オフのテストに合格したため、症状を任意にオン／オフできます	失敗を再現する手順とともに、ビルドスキルへ
再現済み、原因は未解明	バグは確実に再現でき、すべての仮説が否定されました	縮小した再現手順と、候補から除外した項目とともに、ユーザーへ
計測計画	バグをまったく再現できませんでした	優先順位を付けた仮説と、それぞれを判別する計測方法とともに、ユーザーへ

4つ目の状態は、検証されていないもっともらしい仮説です。たまたま正しかったとしても、それは失敗です。 実際の診断とまったく同じ確信度、語彙、形式で書かれるため、単に役に立たないだけでなく、危険なのです。

最初の結果だけがビルド工程へ引き継がれます。ほかの2つはユーザーに返します。何も証明されておらず、実装すべきものがないからです。ここでは、正直に「結果なし」と報告することは成功であり、未達ではありません。

手順

1. 再現する

誰でも実行でき、毎回失敗するコマンドを見つけます。

ゲート：再現できなければ、診断しません。 再現されていないバグから生まれる仮説は、発見事項と見分けがつきません。自分がどちらを書いたのか判断する方法がありません。

このゲートが関わる範囲は、見た目以上に広いものです。本番環境でしか発生しないバグはすべてここに該当します。また、安全に切り替えられない原因もすべて該当します。証明ゲートは再現手順に対してのみ実行され、それ以外には使えないためです。症状が発生する場所が稼働中のシステムしかないなら、何かを安全に証明できる場所は最初からありません。それは証明の失敗ではなく、再現の失敗です。

1つのコマンドが連続3回失敗した時点でこのステップは完了です。あるいは、症状が断続的であると宣言し、証明ゲートの統計的な形式へ進めた時点で完了です。

再現に本当に失敗した場合は、確信度を明示して、その旨をはっきり伝え、計測計画の分岐へ進みます。ひそかな代替手段として扱ってはいけません。実行品質の低下を告げないままでは、完全な実行として受け取られてしまいます。

2. 切り分ける

症状が消えずに取り除けるものがなくなるまで、再現手順を縮小します。出力は、失敗する最小ケースです。

縮小する間は、決定性を強制します。 シードを固定し、並行処理を直列化し、時計を固定し、フィクスチャの順序を固定します。20回に1回しか失敗しないバグはオン／オフを切り替えられないため、ここで決定性を確保するのは単なる配慮ではありません。次のゲートに進むための前提条件です。

バグが実際に依存する軸に沿って二分探索します。コミット、入力、設定値、依存関係のバージョン、2つの環境間の差分などが対象です。

コミットの二分探索は必ず使い捨てのワークツリーで実行し、ユーザーの作業ツリーでは決して実行しないでください。 git bisect は HEAD を移動し、作業ツリーがクリーンであることを要求します。そのため、作業ツリー内で実行すると、すぐに拒否されるか、ユーザーの未コミット作業と自分の調査記録の両方を壊してしまいます。

git worktree add --detach <scratch-path> <known-good-ref>   # bisect lives here
git worktree remove <scratch-path>                          # before the run ends

このライフサイクルを管理するワークツリースキルがインストールされている場合、このエコシステムでは gitkit がそれを担います。インストールされていなければ、上記の2つのコマンドがすべてです。いずれの場合も、実行が終わる前にワークツリーを削除します。削除に失敗した場合は、引き継ぎ時に絶対パスを記載します。

決定性を強制したことでバグが完全に消える場合、それ自体が発見事項です。タイミングこそが仕組みだからです。その旨を伝え、非決定的な再現手順を残し、縮小できたふりをせずに、証明ゲートの統計的な形式へ進めます。

3. 仮説を立てる

検証を始める前に、原因の候補を書き出してください。 それぞれに、外れる可能性のある予測が伴います。つまり、仮説が間違っていれば観察されないはずのことを予測します。

反証可能な予測のない仮説は、ラベルを付けた当て推量です。排除できないため、実行の全過程を生き残り、最後まで残ります。その結果、まさにその仮説がレポートに載ることになります。

先に書き出すのは、単なる形式でもありません。検証した後に書いた仮説は、たまたま観察したことから逆算して作られるため、どれも当てはまってしまい、候補を絞り込めません。

最も安価で候補を識別できる仮説から検証してください。 つまり、入力しやすいものではなく、最も多くの候補を排除できるものです。候補を半分に絞るほうが、お気に入りの仮説を裏付けるよりも効果的です。

何も変更しない検証を優先してください。 ユニットを直接呼び出す、新しいプロセスで実行する、途中の値を外部から出力する、といった方法でも、変更を加えるのと同じくらい明確に候補を識別できることがよくあります。何も書き換えない検証なら元に戻す必要がなく、誰かの作業を失わせる心配もありません。コードの変更が本当に必要な場合に限り、台帳を使ってください。最初から使うのではありません。

反証可能な予測を伴う新たな仮説を、もう立てられなくなった時点で終了してください。 これが終了条件であり、恣意的な回数を設定する必要はありません。調査を続けたいエージェントは、次のラウンドを正当化するための具体的な予測を示す必要があります。バグが再現したまま終了条件に達した場合、実行結果は**「再現したが、説明できていない」**となります。これは敗北ではなく、正当な結果です。

4. 証明する

オン／オフテストのみを行ってください。それより弱いものでは不十分です。 原因を取り除いたり戻したりして症状を切り替えられた場合にのみ、原因を特定したと言えます。

1. 原因が存在する → 失敗する。
2. 原因を取り除く → 成功する。
3. 原因を戻す → 再び失敗する。

この3つがすべてそろわなければ、単なる相関です。これが、「診断」と「何かを変更したら止まった」を分ける唯一の関門です。

3つのステップそれぞれについて、証拠を引用してください。 出力が「確認済み」という一言だけの関門では、読者が検証できるような方法でテストしたことになりません。

一度に変更するのは1つだけです。 2つを同時に変更しても、どちらについても何も分かりません。これこそ、このスキルが防ごうとしている失敗を引き起こす仕組みです。

本番環境、実データ、またはユーザーが指定していないシステムで切り替えテストをしてはいけません。 テストは再現環境で実行します。危険なケースに対する例外は不要です。再現の関門ですでに危険なケースは除外されています。切り替えるには危険すぎる原因は、計測計画の分岐に進める必要があります。ここに抜け道を設けるのは、エージェントが最も通りたくなる状況に、証明を省略すると書かれた扉を置くようなものです。

決定性を確保できない場合、切り替えテストは統計的な形式になります。原因が存在する、原因を取り除く、原因を戻す、という3つの条件でそれぞれN回実行し、すべての失敗率を報告します。これを抜け道ではなく、誠実な方法にするためのルールが1つあります。Nは実行前に宣言し、実行後に決めてはいけません。 抜け道は統計そのものではなく、数字が納得できるように見えるまで実行を繰り返すことでした。Nを示し、それぞれの失敗率を示し、フォールバックを使用したことも明記してください。

統計的な形式で求められる証拠の基準： Nは20以上であり、原因を取り除いた条件で失敗がゼロ件、原因が存在する条件と原因を戻した条件のそれぞれで失敗が5件以上であること。失敗率が25%の場合、20回連続で成功する確率は偶然でも約0.3%です。そのため、原因を取り除いた条件で一度も失敗しないことには意味があります。この基準を下回る実行は証明とは言えません。3つの失敗率を添えて**「再現したが、説明できていない」**と報告し、決着をつけるために必要な、より大きなNを示してください。

3つの切り替え、または3つの条件それぞれについて、基準を満たす証拠を引用できたら、このステップは完了です。

5. 報告

終端状態を明示し、必要な情報を提示します。

原因を特定済み。 原因を一文で述べ、オン／オフの証拠、失敗する再現手順、そして修正内容を適用せずに説明します。テストランナーがある場合は、リポジトリ独自のテスト構成で再現手順を失敗するテストとして記述し、ない場合はコマンドとして記述します。失敗するテストは、修正段階でビルドスキルが受け取る入力なので、翻訳する必要はありません。

再現済み、原因未解明。 縮小した再現手順、排除した仮説すべて、そして各仮説を否定した証拠を示します。原因不明のバグから得られるものとして、これが最も価値があります。次の試みではゼロから始めるのではなく、はるかに絞り込まれた範囲から始められます。

計測計画。 仮説を優先順位順に示し、それぞれを判別する具体的な実験またはログ行を併記します。成果物で答えるのは、次に何を計測するかであり、何が問題かではありません。未検証の仮説に付けた信頼度の割合は、数値を装った再現ゲートが防ごうとしているものそのものなので、付記しないでください。

プローブ台帳

変更を自由に行えるようにする安全性の条件です。デバッグを始めた時点で、ユーザーには未コミットの作業があったものとします。通常はそうであり、プローブを取り消す際にそれまでの作業まで取り消してはなりません。

最初のプローブの前にベースラインを取得します。 台帳は作業ツリーの外部のディレクトリに置き、git status に台帳内のものが表示されないようにします。

snap=$(git stash create)    # an unreferenced commit of tracked changes; empty on a clean tree
git rev-parse HEAD                          > <ledger>/head.pre
git diff --binary --cached                  > <ledger>/index.pre
git status --porcelain=v1 --untracked-files=all > <ledger>/status.pre

git stash create は参照、ファイル、インデックスのいずれにも触れないため、コストはかかりません。オブジェクトが生成されたかどうかを記録します。 クリーンなツリーの場合や、変更が未追跡ファイルだけの場合は、何も出力されず、復旧できるスナップショットはありません。その場合は台帳に none と記入し、存在しないオブジェクトの復旧手順を決して出力しないでください。

スナップショットには未追跡ファイルは含まれません。プローブが未追跡ファイルに触れる可能性がある場合（ファイルを編集する場合、またはそのファイルがあるディレクトリに書き込むコマンドを実行する場合）は、プローブの前にそのファイルを台帳にコピーします。このコピーだけが復旧手段です。

各プローブについて、そのプローブ直前の状態との差分を個別のパッチとして記録します。 各プローブの前に、編集するすべてのファイルを台帳内の新しいプローブ用ディレクトリにコピーします。プローブの後、各コピーと対応するファイルとの差分を取ります。あるファイルに対する最初のプローブの前には、最終確認用の .base コピーも保存します。

cp <path> <ledger>/<name>.base                                # once, before the first probe on the file
cp <path> <ledger>/probe-NN/<name>.pre                        # before every probe
diff -u <ledger>/probe-NN/<name>.pre <path> > <ledger>/probe-NN/<name>.patch   # after it

各パッチには、そのプローブによる変更だけが含まれます。最初に編集する前のコピーを基準に取ったパッチには、それ以前のプローブもすべて含まれるため、そのようなパッチ一式を逆適用すると、以前のプローブを二度取り消したり、失敗したりします。プローブごとに台帳の行を作成し、対象パス、パッチ、実行理由を記録します。

記録したパッチを逆順に逆適用して取り消します。ファイルを復元してはなりません。

patch -R -s <path> < <ledger>/probe-NN/<name>.patch   # correct
git checkout -- <path>                                # banned, without exception

git apply -R ではなく patch -R を使います。 git apply はパッチヘッダーに記載されたパスをリポジトリのルートから解決します。ツリー外のスナップショットから生成したパッチには、解決できないパスが含まれるため、適用されずに invalid path で失敗します。patch -R は指定したファイルに適用し、ヘッダーを無視します。ここで必要なのは、まさにこの動作です。

git checkout -- <path> は反射的に実行しがちな操作であり、既存の未コミット編集を気付かないまま破壊します。ベースライン時にクリーンに見えたファイルも含め、例外はありません。考えながら実行しなければならない禁止事項は、いざというときに自分に言い訳をして破ってしまうものだからです。

逆適用で競合したら、停止して報告します。 強制適用せず、復元に切り替えてもいけません。ファイル名、プローブ、パッチの場所を明記し、ユーザーに解決を委ねてください。

最後に、ベースラインの3つの要素をすべて検証します。 各確認が成功するか、差異が報告されれば、クリーンアップは完了です。

• 追跡対象の内容。 プローブで編集したすべてのファイルが .base コピーと一致し（cmp）、git rev-parse HEAD が head.pre と一致すること。
• インデックス。 git diff --binary --cached が index.pre と一致すること。debugkit はステージングを行わないため、差異があれば報告すべき問題です。
• 未追跡ファイル。 git status --porcelain=v1 --untracked-files=all が、再現テストを除いて status.pre と一致すること。プローブが触れた未追跡ファイルはすべて、台帳内のコピーと一致すること。

再現テストだけは残す書き込みです。 これは原因が立証されたことを示す引き継ぎ用の成果物であり、プローブではないため、台帳には含めず、取り消しません。ステージングせずに失敗した状態のまま残し、絶対パスで示します。意図的にほかのものを残した場合も、絶対パスで報告し、実行中に変更されていないファイルには決して触れません。

毎回、引き継ぎ時にベースラインを出力します。 スナップショットがある場合は1つ目の形式を、git stash create が何も出力しなかった場合は2つ目の形式を使います。

baseline snapshot: <sha> · recover with git stash apply <sha>
baseline snapshot: none (no tracked change at start) · probe patches in <ledger>

誰にも見つけられないオブジェクトは安全策にはなりません。参照されていないコミットは git fsck なしでは見えないからです。git は到達不能オブジェクトを独自のスケジュールでプルーニングするため、これはアーカイブではなく短期間の安全策であることを明確に伝えてください。参照は作成しないでください。参照は実行終了後も残ってしまいます。

Web での検索は解読のためであり、診断のためではありません

情報を調べることは許可されており、多くの場合必要です。境界となるのは、その答えを何に使うかです。

• 許容される範囲。 不明瞭なエラー文字列、ベンダーのステータスコード、未知のライブラリのスタックフレーム、あるいは二分探索でたどり着いたバージョンの変更履歴を解読すること。すでに観測したシグナルを読み解くことです。
• 許容されない範囲。 ブログ記事から仮説を得たり、イシュースレッドで効果があったとされる修正を適用したりすること。それは、他人のバグに対する、他人の診断です。

再現ブランチでは、アイデアの出所に関係なくオン／オフテストが必須なので、このルールは自動的に適用されます。テストされていない提案は、どこから得たものであってもレポートに載りません。

計測計画ブランチでは何もテストしないため、代わりに各項目に判別実験を明記するか、項目を削除することを必須にしています。イシュースレッドから持ち込んだ修正には、実験が添えられていません。「これを実行せよ」と書かれており、「これを測定せよ」とは書かれていないためです。よってこの要件によって構造的に除外され、情報源に関するルールを誰かが覚えておく必要もありません。

成果物

調査の難しさではなく、結果に基づいて判断します。

結果	ファイルは必要か？
再現できたが、説明できていない	常に必要
計測計画	常に必要
原因を特定できたが、原因がコード外（環境、設定、データ、依存関係のバージョン）にある	常に必要
原因を特定でき、原因がコード内にある	不要。レポートにインラインで記載

ルール自体に理由が示されています。ファイルを作成するのは、コミット履歴に残らない情報を記録するためです。 コード内の原因が特定されていれば、修正とテストにすべて記録されるため、文書を作成すると重複します。一方、古くなった環境変数や、すでに否定された仮説の一覧はほかに記録されず、まさに誰もが翌月には忘れてしまう情報です。

ファイルは docs/debug/NNNN-debug-<slug>-YYYY-MM-DD.md に作成します。4 桁の連番、小文字のタイプ接頭辞、短い小文字のケバブケースの主題スラッグ、末尾の ISO 作成日で構成します。連番 NNNN は、この作業ツリー内、git worktree list に記載されたすべての作業ツリー内、および origin/HEAD 内（git fetch origin の後に git ls-tree --name-only origin/HEAD docs/debug/ を実行）にある docs/debug/ の、先頭に付いた 4 桁の連番の最大値を取得し、1 を加えて決めます。該当するものがなければ 0001 から始めます。並行する作業ツリーで同じ連番が使われないよう、3 つすべてを確認します。リモートがない場合など、確認に失敗した情報源はスキップし、git がない場合はディレクトリだけを一覧表示します。連番はディレクトリごとに管理し、再利用しません。ファイルを編集するときも名前全体を変更せず、同じバグに再び取り組むときは、別のコピーを作らず、同じファイルをその場で更新します。リポジトリに事後検証用の既定の場所や命名規則がすでにある場合は、その慣例を優先し、それに従ったことを明記します。

ファイルは長期保存を目的とし、コミット可能です。事後検証の記録は後で読み返すためのものであり、一時作業用ディレクトリではなく、バージョン管理下に置くものです。ただし、debugkit がファイルをコミットすることはありません。

書き込み可能なファイルシステムがない場合（ブラウザー上で動作するエージェントなど）は、正式なパスを見出しに付けて成果物をコードブロックとして出力し、ファイルへの書き込みは省略します。ファイルを作成しないという結果も許容されており、謝罪する必要はありません。

引き継ぎ

このセクションは手順を示す文体で書いてください。各文に指示を1つだけ含め、能動態、現在形を使い、比喩は使わないでください。

変更内容。 最終状態を明記してください。実施したプローブをすべて列挙し、元に戻したことを確認してください。各ベースラインチェックの結果を報告してください。修正を適用していないことを明記してください。再現テストの絶対パスを示し、そのテストがディスク上に残っており、失敗状態でステージングされていないことを伝えてください。意図的に残したファイルがあれば、その絶対パスを示してください。削除できなかった bisect ワークツリーがあれば、その絶対パスを示してください。

到達点。 成果物のパスを示すか、結果にファイルが不要だったと伝えてください。実行のたびに、プローブ台帳で選んだ形式でベースライン行を出力してください。

baseline snapshot: <sha> · recover with git stash apply <sha>
baseline snapshot: none (no tracked change at start) · probe patches in <ledger>

次のステップ。 次のアクションを1つ選び、結果に合わせてください。

• 原因を特定済み → 再現テストと説明した修正内容をビルドスキルに引き継いでください。implementkit がインストールされている場合は、再現テストを入力とする修正ラウンドとして implementkit を指定してください：implementkit fix round: make <test path> pass; cause: <one sentence>。implementkit は最初にテストが失敗することを確認し、テストを保持して、完了ゲートで成功することを示します。それ以外の場合は、次のステップとして修正を書き、テストを保持して、成功することを確認すると明確に伝えてください。
• 再現したが、説明できていない → 調査を再開するために必要な証拠をユーザーに伝えてください。ビルドスキルには引き継がないでください。原因はまだ何も証明されていません。
• 計測計画 → 列挙した計測をデプロイするようユーザーに伝えてください。証拠が得られたら、debugkit を再度実行するよう伝えてください。

次のステップを自分で開始しないでください。

注意事項

• 修正を適用しないでください。 条件付きでも、一行の修正でも、明らかな場合でも適用しないでください。このルールが真価を発揮するのは、一行の修正です。省略しても問題ないと感じるのがまさにそのときだからです。
• ゲートを成功したように見せかけないでください。 証明されていない原因は、未証明として報告してください。オン／オフテストを省略した実行では、何が見つかっていても原因は特定されていません。
• 実行せずに引き継いでください。 次のスキルとその1行の呼び出し方法を示し、呼び出しは行わないでください。診断に基づいて行動するかどうかは、ユーザーが決めます。
• 必須ではなく、候補として案内してください。 ここで推奨する内容は、指定したスキルがない場合でも、通常の作業として実行できる形にしてください。git だけの最小限のリポジトリでも、debugkit は役に立ちます。
• これらの既定値よりもリポジトリの指示を優先してください。 既定の事後分析の保存場所、文書化された規約、またはリポジトリのエージェントガイドファイル（CLAUDE.md または同等のファイル）に記載された方針がある場合は、それに従い、従ったことを伝えてください。