OSSに貢献してみたい人なら誰でも、初心者の方でも、AIをよく使う方でも読めます。コミュニティの進め方を事前に知っている必要はありません。用語にはどれも身近なたとえを添え、gitの実例は印をつけてあるので、まだ必要なければ読み飛ばせます。

数字は公開情報から取っており、末尾に一覧があります。「例」と書いたものは作った例で、実在の人物やプロジェクトには触れていません。この記事は私自身の貢献体験談を書いていません。語れる体験がないからです。gitの実例は、手元の練習用リポジトリで実際に動かしたものです。AIモデルの内部の仕組みは、まだ誰にも完全には分かっていません。以下のたとえは覚えやすくするための補助です。

まず要点#

• OSSのメンテナーは、AIが生成した質の低い貢献を多く受け取っています。Linux Foundation Researchの調査（2026年10月20日）では、メンテナーは**プルリクエストの約25%を「AIスロップ」と見積もり、大規模プロジェクトでは31%**でした。
• 具体例として、curlは2026年1月末でバグバウンティを終了しました。主要メンテナーは、本物と確認された脆弱性報告の割合が15%超から5%未満に下がったと書いています。
• 負担をかけない進め方は4週間に収まります。1週目はプロジェクトを読んで使う、2週目は承認済みの小さな作業を選び、先に聞く、3週目はAIなしで説明できる、テストつきの小さな変更を作る、4週目は明確なPRを出し、AI利用を申告し、フィードバックに落ち着いて対応する。
• ルールはプロジェクトごとに違い、変わるのも速いです。申告と理解を条件にAIを認めるところもあれば、禁止するところもあります。この記事ではなく、貢献先のルールを読んでください。
• 実際に動かしたgitの例（Git 2.56.0）では、小さな変更が3つの段階を踏みます。先にテスト、次に修正、そしてフィードバックを受けて直す、です。最初の実行では「NO TESTS RAN」と出ました。実行したテスト数を必ず書き留める理由の1つです。
• 却下はよくあることです。4週間の目的は、何としてもマージされることではなく、次もあなたの作業を読みたいと思ってもらえる振る舞いをすることです。

むずかしい言葉をやさしく#

この記事を読むと説明できること#

1. なぜOSSのメンテナーが確認されていないAI生成の貢献を嫌がるのか、そしてなぜプロジェクトごとの方針がまったく違いうるのか。
2. 4週間の順序：ルールを読む、先に聞く、1行ずつ理解した小さなテストつきの変更を作る、それからPRを出してAIを申告する。
3. そのためのgitの流れ：自分用のブランチ、テストつきのコミット、プロジェクトが進んだときのrebase、フィードバック後の修正。

1. まずイメージ：他人の工房を訪ねる客として#

主人が1人で切り盛りする小さな木工所が、見学者を受け入れているとします。ある客が入ってきて「ここはもっと良くできると思います」と言い、手作りの品を荷車いっぱいに持ち込んで、あちこちの隅に置いていきます。品物は良いかもしれません。でも主人は1つずつ確認し、場所を空け、壊れたら責任を負わなければなりません。別の客は1週間座って眺め、「この椅子を磨かせてもらえますか」と聞き、椅子を1脚だけ磨いて見せに来ます。主人は2人目の名前を覚えるでしょう。

OSSも同じです。メンテナーは、空き時間や無償で動いている人が多いです。プルリクエストは1つ1つ、確認しなければならない品物です。AIは品物を送るコストを大きく下げましたが、確認するコストはメンテナーの時間のままです。

ポイント： 良い貢献は、送った行数ではなく、メンテナーが「はい」と言いやすくなるかどうかで測られます。

2. なぜメンテナーは限界なのか#

2.1 Linux Foundation Researchの調査（2026年10月20日）#

Linux Foundation Researchは2026年10月20日に、報告書「Navigating Open Source Software Development in the Generative AI Era: Challenges and Opportunities for Project Communities」を公開しました。プレスリリースによると、メンテナーは届くプルリクエストの約25%、大規模プロジェクトでは**31%**をAIスロップと見積もっています。同じリリースには、59%のメンテナーが貢献の量が増えていると感じていること（大規模では69%）、約35%のプロジェクトにAIを許可する正式な方針があること、32%には方針も予定もないこと、61%の貢献者がAI生成コードを提出前に詳しくレビューし十分にテストしていると答えたこと、回答者がコードを書く時間を平均で約52%短縮できると見積もっていることも書かれています。

注意して読んでください。これは調査回答者の見積もりで、プルリクエストを数えた数字ではありません。私が読んだプレスリリースには、回答者数が書かれていませんでした。読んだのはプレスリリースで、報告書の全文ではありません。調査に答えてくれる人に偏っている可能性もあります。

ポイント： 問題は本物で、計測もされています。ただ、多くのプロジェクトにはまだ明確なルールがありません。ルールは自分で探しに行く必要があります。

2.2 1つのプロジェクトの例：curlがバグバウンティを終了#

curlの主要メンテナーであるDaniel Stenbergは、2026年1月26日の記事「The end of the curl bug-bounty」で、curlにバグバウンティはもうなく、2026年1月31日で終了すると書きました。2025年より前は、本物の脆弱性と確認された報告の割合が「15%を超えていた」のに対し、2025年からは「5%未満」、つまり20件に1件も本物ではないと述べています。理由として、AIスロップ、人間による質の低い報告、一部の報告者の悪意ある姿勢を挙げ、金銭的な報酬がそうした悪用を招いたのではないかと推測しています。AIスロップを送る人は引き続き禁止するとも書いています。

これは1つのプロジェクトと、その内部にいる人の見方です。すべてのプロジェクトが同じだという証拠ではなく、金銭の報酬はcurl特有の要因かもしれません。

ポイント： 受け手があふれると、扉を閉めます。扉が閉まると、良い貢献者も困ります。

2.3 GitHubがメンテナーに道具を追加#

2026年2月13日、GitHubはリポジトリの設定を2つ追加しました。プルリクエストを完全に無効にする設定と、書き込み権限のある人だけが新しいプルリクエストを作れる設定（誰でも読んでコメントはできる）です。場所はSettings、General、Featuresです。私が見つけた日本語の開発者ブログには、「コラボレーターのみ」の設定が当時の説明どおりに動かなかったという報告がありました。変わっている可能性があるものとして扱ってください。GitHubは、書き込み権限のないユーザーが同時に開けるプルリクエスト数の上限も追加したと伝えられています（2026年6月、私はニュース記事でしか確認していません）。

ポイント： 見知らぬ人からのプルリクエストを受け付けないリポジトリもあります。まず、貢献したい先がどうなのかを確かめてください。

2.4 実在するポリシー：Ghostty#

ポリシーがどこまで具体的になりうるかを見るため、GhosttyプロジェクトのCONTRIBUTING.mdとAI_POLICY.mdを読みました。書くのは、読んだ時点で読めた内容だけで、あなたが読むころには変わっているかもしれません。これらのファイルによると、プロジェクトはAIによるコード作成を認めていますが、AIの利用をすべて申告すること（ツール名と関与の程度）、提出するコードをすべて理解しAIなしで説明できること、初めての貢献者は先に推薦（vouch）を受けること（そうでないとプルリクエストは自動で閉じられる）を求めています。質の低い貢献を送った人の公開リストもあります。ルールは外部の貢献者に適用され、メンテナーは対象外です。

これは1つのプロジェクトです。もっと緩いところも、AI生成の貢献を全面禁止するところもありえます。この記事は、上で読んだプロジェクト以外には依拠していません。

ポイント： ルールはプロジェクト自身にあります。最初の問いは「何をするか」ではなく、「ここではどう決まっているか」です。

3. 4週間プラン#

工房への4回の訪問を思い浮かべてください。1回目は見て、2回目は聞いて、3回目は作業して、4回目は差し出します。以下の時間は目安で、週に数時間です。

1週目：プロジェクトを読んで使う#

やること：

1. 実際に使っているプロジェクトを選びます。使っていないと、何が役に立つのか分かりにくいからです。
2. README、CONTRIBUTING、CODE_OF_CONDUCT、あればAIポリシーを読みます。見知らぬ人のプルリクエストを受け付けているかどうかも確認します。
3. 受理されたプルリクエストを5件ほどと、閉じられたものを5件ほど読みます。説明の書き方や、閉じられた理由に注目します。
4. プロジェクトを手元にインストールして動かし、テストを1回実行します。

持ち帰るもの： 「このプロジェクトの決まりごと」を自分の言葉で書いた5行と、テストを動かすコマンド。

2週目：承認済みの小さな作業を選び、先に聞く#

やること：

1. 初心者向けのラベル（good first issueなど）がつき、誰も担当していないissueを探します。
2. issueとコメントを丁寧に読みます。メンテナーが確認したissueだけが、取り組む価値があります。
3. 担当したいとコメントし、やり方を2、3文で書き、コードを書く前に返事を待ちます。
4. 何日も返事がなければ、大きな変更を勝手に進めないでください。もう一度聞くか、別の作業を選びます。

持ち帰るもの： メンテナーから返事をもらった、短くて丁寧で明確なコメント1つ。

3週目：小さく、テストつきで、理解した変更を作る#

やること：

1. 自分用のブランチを作ります。問題を再現する失敗するテストを書き、そのテストが通るまで直します。
2. 目的は1つだけにします。同じPRで整形や一括リネームをしないでください。
3. プロジェクトのテストをすべて実行し、実行したテスト数を書き留めます。
4. プロジェクトが許すならAIを使ってもかまいませんが、このテストをしてください。AIを切って、変更した行を1行ずつ声に出して説明します。相手は他の人でも自分でも構いません。 説明できない箇所は、まだ理解していないということで、提出する準備ができていません。

持ち帰るもの： きれいなコミット1つのブランチと、動くテスト。

4週目：明確なPRを出し、AIを申告し、落ち着いてフィードバックを受ける#

やること：

1. 第5章のテンプレートでPRの説明を書きます。問題、修正、確認方法、そしてプロジェクトの求める形のAI申告です。
2. 送る前に自分のdiffをレビューします（AIが書いたコードのレビューを参照）。
3. フィードバックが来たら、短く返信し、求められたことだけを直し、プロジェクトが進んでいればrebaseします。
4. 却下されたら、お礼を言い、分からなければ質問し、議論はしません。

持ち帰るもの： メンテナーが一目で目的と確認方法を把握できるPR。

4. 実際に動かした例：小さな貢献のgitの流れ（gitをまだ使わないなら読み飛ばせます）#

本物の工房に入る前に、模擬の工房で練習するようなものだと考えてください。手元に「模擬の工房」を作りました。プロジェクトの「元」にあたるbareリポジトリと、「あなたのfork」にあたるクローンです。以下のコマンドはすべて、Git 2.56.0とPython 3.14.8で実際に実行しました。コミットのハッシュは、あなたの環境では変わります。

注意：これはGitHubではありません。GitHubでは、Webでforkボタンを押し、自分のforkにブランチをpushし、Webでプルリクエストを作ります。共通するのはgitのコマンド（ブランチ、コミット、rebase、修正）です。例の「プロジェクト」はtextkitという小さなライブラリで、タイトルをWebアドレスの一部に使う短い文字列に変えるslugify関数があります。「問題」は、slugify("Hello World!")がhello-world-と、末尾に余分なダッシュをつけて返すことです。

4.1 修正の前に：テストを実行し、ブランチを作る#

$ python3 -m unittest -q
Ran 1 test in 0.000s

OK

$ git switch -c fix-slug-trailing-dash

最初の実行は、静かに失敗していました。 「Ran 0 tests」と「NO TESTS RAN」と出たのです。testsフォルダに__init__.pyがなく、テストランナーが何も見つけられなかったからです。赤い行は1つもなく、テストが1つも走っていませんでした。だからAIの結果に自分で証明させるは、必ず実行したテスト数を書き留めることを勧めています。「エラーなし」は「確認済み」とは限りません。

4.2 先に失敗するテストを書く#

感嘆符と両端の空白があるケースのテストを足し、修正前に実行しました。

$ python3 -m unittest -q
FAIL: test_no_trailing_dash (tests.test_slug.SlugTests.test_no_trailing_dash)
Traceback (most recent call last):
  File "tests/test_slug.py", line 10, in test_no_trailing_dash
    self.assertEqual(slugify("Hello World!"), "hello-world")
AssertionError: 'hello-world-' != 'hello-world'

Ran 2 tests in 0.000s

FAILED (failures=1)

テストは、期待した理由でちょうど失敗しています。修正前にすぐ通る、または別の理由で失敗するなら、そのテストは問題とは別のものを確認しています。

4.3 修正して再実行#

$ python3 -m unittest -q
Ran 2 tests in 0.000s

OK

$ git diff --stat
 tests/test_slug.py | 4 ++++
 textkit/slug.py    | 2 +-
 2 files changed, 5 insertions(+), 1 deletion(-)

2ファイル、追加5行と変更1行。メンテナーが数分で見られる小ささです。

4.4 明確なメッセージと申告の行を持つコミット#

fix(slug): strip leading and trailing dashes

slugify("Hello World!") returned "hello-world-". Strip dashes at both
ends and add a test for punctuation and surrounding spaces.

AI assistance: used an AI tool to draft the test; I read and ran it.

最後の行は、プロジェクトが申告を求める形の一例です。貢献先のプロジェクトのやり方を使ってください。このテンプレートではありません。

4.5 プロジェクトが進んだ：fetchとrebase#

作業中に、メンテナーがメインブランチにコミットをもう1つpushしました。それを取得し、自分の変更を最新版の上に載せ替えます。

$ git fetch origin
$ git log --oneline --graph --all
* 4cbdd85 docs: add a line on review etiquette
| * 0606d8e fix(slug): strip leading and trailing dashes
|/
* 7835b68 chore: initial textkit

$ git rebase origin/main
Successfully rebased and updated refs/heads/fix-slug-trailing-dash.

$ git log --oneline --graph --all
* ea41359 fix(slug): strip leading and trailing dashes
* 4cbdd85 docs: add a line on review etiquette
| * 0606d8e fix(slug): strip leading and trailing dashes
|/
* 7835b68 chore: initial textkit

同じ変更ですが、新しい土台の上に載ったのでハッシュが変わりました（0606d8eからea41359へ）。古いコミット0606d8eは、先にpushしたブランチに残っています。

4.6 レビューのフィードバック：修正して新しい版をpush#

レビューする人が、空文字列のテストをもう1つ求めたとします。テストを足して実行し、継ぎはぎのコミットを足さず、古いコミットを修正します。

$ python3 -m unittest -q
Ran 3 tests in 0.000s

OK

$ git commit --amend --no-edit
$ git push --force-with-lease origin fix-slug-trailing-dash
 + 0606d8e (旧), d109624 (新): ブランチ fix-slug-trailing-dash (forced update)

$ git diff origin/main --stat
 tests/test_slug.py | 7 +++++++
 textkit/slug.py    | 2 +-
 2 files changed, 8 insertions(+), 1 deletion(-)

本物のGitは、新旧のハッシュを独自の記号でつないだ1行を出力します。ここでは読みやすく書き直しましたが、結果は、サーバー上のハッシュ0606d8eがd109624に置き換わった、ということです。--force-with-leaseは、サーバー上のブランチが想定どおりのときだけ上書きします。使うのは自分のブランチ（PRのブランチ）だけで、プロジェクトのメインブランチでは絶対に使わないでください。修正ではなく新しいコミットの追加を求めるプロジェクトもあるので、プロジェクトの案内を確認してください。

4.7 別の方法：パッチファイルを作る#

変更をメールで送るパッチファイルで受け付けるコミュニティもあります。

$ git format-patch -1 -o ../patches
../patches/0001-fix-slug-strip-leading-and-trailing-dashes.patch

GitHubでは少ない方法ですが、多くの大きなプロジェクトで今も使われています。どの方法を使うかは、各プロジェクトのCONTRIBUTINGに書かれています。

この例についての注記：1人だけの練習用リポジトリで、本物のレビュー担当も、Webの画面もありません。コマンドが動き、貼ったとおりの出力が出ることは示していますが、本物のやり取りがどう進むかは示していません。

5. PR説明のテンプレートとセルフチェックリスト#

5.1 プルリクエストの説明テンプレート#

## 問題
1、2文：何がおかしいか、いつ起きるか。issueへのリンク（Closes #123）。

## 修正
1、2文：何を変えたか、なぜこの方法か。

## 確認方法
- テストのコマンド：python3 -m unittest
- 実行したテスト数：3、すべて合格
- 修正前に新しいテストが失敗したか：はい

## AI利用の申告
プロジェクトの求めるとおりに：AIを使ったか、どのツールか、どの部分か。
変更全体を読み、実行し、理解しました。

5.2 送信ボタンを押す前の6つのセルフチェック#

1. 変更の1行ずつを、AIなしで説明できますか？
2. プロジェクトのテストをすべて実行し、実行したテスト数を把握していますか？
3. このPRの目的は1つだけですか？
4. プロジェクトのCONTRIBUTINGとAIポリシーを読み、従っていますか？
5. この作業は、issueでメンテナーに承認されていますか？
6. 説明に確認方法が書かれ、レビューする人がたどれますか？

「いいえ」が1つでもあれば、止まって、先にそれを終わらせてください。

6. よくある失敗#

工房の客を思い浮かべてください。客がすると、主人がため息をつくことがあります。

7. 例：同じissueでの2つの朝#

実在の人物やプロジェクトに触れない、想定の例です。2人の貢献者が、同じ小さなissueを見つけます。

1人目はルールを読まない：

• 09:00. issueを開き、「簡単な作業」と見て、AIにコードを生成させます。
• 09:40. AIが600行の変更を出します。3ファイルの整形と、余計な最適化も入っています。貢献者は全部を読まないままPRを出し、AI利用の申告もありません。
• 14:00. メンテナーはCONTRIBUTINGを読むよう促して、PRを閉じます。作業は承認されておらず、大きすぎる、と。貢献者は午前中を失い、何が悪かったのか分かりません。

2人目は4週間プランに従う：

• 09:00. CONTRIBUTINGを読み、このプロジェクトがAI申告と事前の確認を求めていると知ります。
• 09:20. 担当したいとコメントし、修正方法を2文で書きます。
• 翌日10:00. メンテナーが「いいですよ、どうぞ」と返信します。
• 翌日15:00. 先に失敗するテストを書き、修正し、テストをすべて実行し、AIなしで全行を読み直してから、追加が約8行だけで申告の行もあるPRを出します。
• 3日目09:00. レビューする人がテストをもう1つ求め、貢献者は15分で直します。

やるべきこと：「先に聞く」段階と「自分で説明する」段階で、自分を止めることです。この2つの段階は約30分かかりますが、双方の午前中を丸ごと節約できることがよくあります。

この例は証拠ではありません。証拠は、第2章のLinux Foundationの調査とcurlの事例です。本物のメンテナーが大きな負荷を抱えて扉を閉めているので、レビューしやすい貢献は本当の贈り物になります。この2つの情報源は、見積もりと内部の人の証言であり、対照実験ではありません。

8. 答えつきの練習問題#

練習A. PR説明の欠点を探す#

あるPRの説明は、こうです。「Fix stuff. バグを直しました、AIを使って早く。ついでにフォルダ全体を整形。テスト済み。」

弱点を少なくとも5つ挙げてください。

答え： (1) 具体的な問題が書かれておらず、issueへのリンクもない。(2) 「AIを使って早く」はツールも部分も示さず、読んで理解したとも書いていない。(3) フォルダ全体の整形は2つ目の目的で、別のPRにすべき。(4) 「テスト済み」はコマンドも、テスト数も、修正前に新しいテストが失敗したかどうかも示していない。(5) レビューする人が自分で確認する方法がない。(6) タイトル「Fix stuff」は何も語らない。

練習B. 先に聞くか、すぐ作るか#

練習用リポジトリで、slugify("Xin chào")はxin-ch-oを返します（実際に実行しました）。アクセント付きの文字が消えるのが分かります。すぐに修正のPRを出すべきか、先にコメントで聞くべきでしょうか？

答え： 先に聞きます。アクセント付きの文字をどう扱うかは設計上の判断です。アクセントを外す（xin-chao）、残す、別の文字に置き換える、など。メンテナーには現在の挙動にしている理由があるかもしれず、別のやり方を望むかもしれません。すぐにPRを出すと、コードが正しく動いても閉じられることがあります。起きている現象、いくつかの選択肢、どちらの方向がよいかを尋ねる2、3文のコメントで十分です。

練習C. 修正前に通ってしまうテスト#

slugify("Hello---World") == "hello-world"というテストを足しました。何も変えずに実行すると、すぐ通ります（実際に実行しました）。どうしますか？

答え： これはバグではありません。関数はすでに、連続するダッシュを1つにまとめています。最初から通るテストは、既存の挙動を守るために足す価値はあっても、バグを直した証拠にはならず、「修正」として出すべきではありません。本当の問題が何だったのか、見直してください。

9. バランスよく：分かっていること、分かっていないこと#

かなり確か： メンテナーは貢献の量が増え、その中に質の低いものがかなりの割合で含まれると報告している。少なくとも1つの大きなプロジェクト（curl）がこの理由で扉を1つ閉じた。いくつかのプロジェクト（Ghosttyなど）には、AIについて明確な方針がある。

不明、または注意が必要：

• 25%と31%は調査回答者の見積もりで、数えた数字ではありません。報告書の全文は読んでいません。
• curlの事例は、1つのプロジェクトと1人の内部の人の話です。金銭のバウンティがあったため、ないプロジェクトとは違うかもしれません。
• 方針は速く変わります。この記事は、読んだ時点で読めたことだけを書いています。
• 4週間プランに従うとマージされる割合が上がるかを直接測った研究は、見つけていません。このプランは実践の総合であり、実験結果ではありません。

大げさにしない。 PRが受理される保証はありません。プロジェクトは、あなたと関係のない理由で断ることがあります。リリース凍結中、方針の変更、あるいは単に余力がない、などです。

軽く見ない。 AI生成の貢献を全面的に禁止するプロジェクトもあります。出会ったら従い、回避しようとしないでください。

10. まとめ#

AI時代のOSS貢献は、敬意の行為です。ルールを先に読み、先に聞き、少なく、レビューしやすく送り、自分が送るものを理解すること。AIは書くのを速くしてくれますが、理解していないものを送るのも速くしてしまいます。上の4週間は、止まる地点を正しい場所に置く方法です。

このgitの流れを練習したいなら、まず練習用リポジトリで試してください。救出用のコマンドはAIエージェントを使う人のGit入門、直す前にバグを再現する方法は探偵のようにバグを追う、腕を保ちながら新しいプロジェクトを学ぶ方法は知らないライブラリをAIと学んで腕を落とさないも参照してください。

参考資料#

数字は2026年10月時点の公開情報によるものです。各プロジェクトの方針は変わっている可能性があるので、行動する前に出典を開いて確認してください。

• Linux Foundation, 調査「Navigating Open Source Software Development in the Generative AI Era」のプレスリリース（2026年10月20日）とニュースの要約
• Daniel Stenberg, The end of the curl bug-bounty（2026年1月26日）
• GitHub Changelog, New repository settings for configuring pull request access（2026年2月13日）
• Ghostty, CONTRIBUTING.mdとAI_POLICY.md（2026年10月に読んだもの。方針は変わっている可能性があります）
• Git, git-rebase、git-push（--force-with-lease）、git-format-patchのドキュメント

AIエージェントに仕事を任せる人なら誰でも、初心者の方でも読めます。監視やセキュリティの知識は不要です。用語にはどれも身近なたとえを添えています。コードの部分は印をつけてあるので、今は不要なら読み飛ばせます。

数字は公開情報から取っており、末尾に一覧があります。「例」と書いたものは作った例で、実在の人物や会社には触れていません。実際に動かした例は、私がPythonで書いた模擬であり、市販ツールの記録ではありません。AIが内部でどう行動を決めているかは、まだ誰にも完全には分かっていません。以下のたとえは覚えやすくするための補助です。

まず要点#

• エージェントに仕事を任せて会議に出ると、1つひとつの手順は見えません。足跡がないと、何か起きたときに長い会話を読み返して推測するしかありません。
• 操作の記録とは、エージェントがしたことを1つにつき1行で残したものです。いつ、どのツールやコマンドで、どんな結果になり、どのファイルが変わったか。1行に1つのJSONを置く形式（JSON Lines）なら、数行のコードかjqコマンドで検索できます。
• 残すのは必要な分だけ。 秘密情報、個人データ、ファイルの全文は残しません。書く前に隠します。鍵が漏れる記録は、鍵が漏れるコードと同じくらい危険だからです。
• 記録する層はエージェントの外側に置き、 追記だけを受け付けます。エージェントが編集できる記録は、もう証拠ではありません。
• 実際に動かした例では、25件の操作で7,170バイトのファイルができました。3つの調査の問い（時系列、最初の失敗、変更ファイル）はスクリプトを動かすとすぐに答えが出て、書き換えられた行も検知できました。
• 記録は何が起きたかを示すもので、それが正しかったかは示しません。証拠を求めることやテストの代わりではなく、それらを補います。

この記事を読むと説明できること#

1. 誰も見ていないセッションにも足跡が必要な理由と、足跡が保存した会話とどう違うか。
2. 記録の1行にどんな項目を持たせるか、そして絶対に残してはいけないもの。
3. 問題が起きた後の使い方：時系列の組み立て、最初の失敗の特定、変更ファイルの一覧、書き換えられた行の検知。

むずかしい言葉をやさしく#

1. まずイメージ：お店の防犯カメラとレシート帳#

お店を開き、とても手の早い店員を雇ったとします。今日は留守にしました。戻ると、レジが20万ドン足りません。何も記録がなければ、店員に聞くしかありません。店員は正直に答えても、記憶違いをしているかもしれません。

今度は、お店に2つのものがあるとします。カウンターの様子を撮るカメラと、取引を1件ずつ書くレシート帳です。何時に、何を売って、いくら受け取ったか。1日分の映像を全部見る必要はありません。帳面を開いて午後3時の取引を探せば、ずれがすぐ見つかります。飛行機も同じです。フライトレコーダーが操作を残しているので、事故のあとに、聞ける人が残っていなくても何が起きたかを組み立てられます。

エージェントは、この手の早い店員に似ています。数分で何十ものコマンドを動かします。会話はエージェントが語る話です。操作の記録がレシート帳です。言ったことではなく、したことが残ります。

ポイント： 記録は店員を捕まえるためのものではありません。何かあったとき、何時間も推測する代わりに数分で原因を見つけるためのものです。

2. 後から見直さないセッションに足跡が必要な理由#

任せる仕事が増えるほど、1つひとつの手順を見なくなります。Anthropicの2026年版エージェント型コーディングのトレンド報告書の紹介ページには、技術リーダーが生産性と、監督、品質、セキュリティの間でバランスを取っていること、複数エージェントの連携が話題に含まれることが書かれています。私が読めたのは紹介ページだけです。全文は登録フォームの先にあるため、報告書の本文は読んでおらず、そこからはこれ以上何も引いていません。

もう1つの数字です。Stack Overflowの2026年の調査では、回答者の69.9%が未知の課題に直面したときAIエージェントに聞くと報告されています（要約を通じて読んだ数字で、各表とは照合していません）。エージェントは日常の一部になっていて、その作業はしばしば、あなたが見ていないところで進みます。

すると2種類の損失が出ます。1つ目：問題が起きたのに、エージェントがどのコマンドを走らせたか誰も分からず、調査が遅くなる。2つ目：問題はないのに、同僚が「なぜテストファイルが変わったの？」と聞き、あなたが長い会話を読み返して答える。記事「AIの結果に証拠を添えさせる」は、エージェントの回答の中に証拠を求めます。記録は残りを補います。回答の外にあり、エージェントが書けない別の層が書いた証拠です。

ポイント： 任せるほど足跡が必要になります。足跡は、読み返すより安く済みます。

3. 何を残し、何を残さないか#

3.1 残したい7つの情報#

レシートを思い浮かべてください。誰が売り、何を、いつ、いくら、どの注文で。

書き換えられた行を見つけたいなら、prev（直前の行の指紋）を足します。第5節ではそうしています。

3.2 残してはいけない3つ#

1. 秘密情報とパスワード。 書く前に隠します。記録は設定ファイルより多くの人に読まれがちなので、記録の中の鍵は.envの中の鍵より遠くまで広がります。
2. 利用者の個人データ。 残すのは、隠した識別子か社内のIDだけです。
3. ファイルの全文や長いコマンド出力。 要約（行数、合格したテスト数）と、見直す場所だけを残し、中身は残しません。記録は小さく、リスクも小さく保てます。

チームにすでに「1ページのAI利用ポリシー」があるなら、この3つを「禁止」の列に入れ、記録を保管する期間の見直し日を決めてください。

3.3 1行はこんな見た目#

{"seq": 12, "ts": "2026-10-31T09:01:27+07:00", "session": "s-001",
 "actor": "agent", "request": "R2: make the tests pass",
 "tool": "run_command", "args": {"cmd": "python -m pytest -q"},
 "exit_code": 1, "summary": "ran 20 tests, 18 passed, 2 failed",
 "files_changed": [], "prev": "5d5c9ffa0389"}

（実際のファイルでは、1つの記録が1行に収まります。ここでは読みやすいように折り返しています。）

ポイント： 7つの情報が、調査の5つの問い（誰が、何を、いつ、なぜ、どこまで）に答えます。3つの禁止は、ノートが新しい漏えいの場所にならないようにするためです。

4. 仕組み：4つのつながり#

生産ラインを思い浮かべてください。操作、記録する層、保管、検索。

1. エージェントが操作する。 コマンドを走らせ、ファイルを編集し、ツールを呼ぶ。
2. 記録する層が操作を捉える。 この層はツールやエージェントを動かす枠組みの中にあり、エージェントへの指示文の中ではありません。「自分で記録しておいて」と頼むだけでは、忘れたり間違えて書いたりします。
3. 秘密を隠し、追記専用の場所に書く。 行を足すだけで、古い行は開き直して編集しません。
4. 必要なときに検索する。 スクリプトかjqで読みます。

4.1 お使いのツールにつなぐ場所はあるか#

Claude Codeの現行のフックの文書（このページは開いて確認しました）によると、ツール呼び出しの前後でコマンドを走らせられます。コマンドは標準入力（stdin）でJSONのオブジェクトを受け取ります。文書に挙がっている項目は、session_id、transcript_path、cwd、hook_event_name、そして呼び出し後のイベントにはtool_name、tool_input、tool_response、tool_use_id、任意のduration_msです。ツールが失敗した場合には別のイベントがあり、errorの項目がつきます。また文書には、終了コード0で何も判断を出力しないフックはツール呼び出しを変えず、終了コード2は呼び出しを止めるとあります。したがって、記録の用途に終了コード2は使わないでください。

セッションの記録について：文書の例のパスは.jsonlで終わっているので、記録はJSON Lines形式で保存されていると考えられます。形式を文章で明言してはいないため、これは例からの推測です。また、記録ファイルは遅れて書かれることがあるとも書かれています。

次は、私が書いた記録用のスクリプトです。jqで項目を取り出し、鍵を隠します。

#!/bin/sh
# Append one redacted JSON line per tool call. Always exit 0.
jq -c '{
  ts: (now | todate),
  session: .session_id,
  event: .hook_event_name,
  tool: .tool_name,
  input: (.tool_input | tostring | gsub("sk-[A-Za-z0-9]{8,}"; "[REDACTED]")),
  ms: .duration_ms
}' >> "${TRAIL_FILE:-hook-trail.jsonl}"
exit 0

このスクリプトを、文書と同じ形の偽のJSONオブジェクトで動かしたところ、1行が書き出され、偽の鍵sk-test1234567890abcdは[REDACTED]に置き換わりました。実際のClaude Codeのセッションの中では動かしていません。 フックの宣言の書き方（matcherというキーや、設定ファイルの中の置き場所）はバージョンによって違うので、つなぐ前にお使いのバージョンの文書を読んでください。

4.2 共通の標準：OpenTelemetry#

項目名を自分で決めるより標準を使いたい場合、OpenTelemetryプロジェクトには、生成AIの処理（エージェントの操作やツール呼び出しを含む）の命名規約があります。私が読んだ解説によると、この規約はまだ「Development」の段階（安定版ではない）で、属性名はバージョン間で変わる可能性があります。私が開いた公式ページは、規約が別のリポジトリに移ったと伝えているだけなので、「Development」という状態は二次情報によるものです。公式のリポジトリで確認してください。 初心者は、まず自分で決めたJSON Linesの名前で始め、後で移行しても構いません。

ポイント： 記録する層はエージェントの外に置き、操作のたびに書き、保管する前に秘密を隠します。

5. 実際に動かした例：25件の操作、1つの失敗、1つの偽の鍵#

これは私が書いた、エージェントのセッションの模擬です（Python 3.14.8、jq 1.7.1）。操作そのものは用意したデータですが、記録する層、秘匿処理、ハッシュ連鎖、検索は実際に動かしたコードで、以下の結果は実際の出力です。2つの完全なスクリプトは末尾の付録にあります。

筋書き（例）：エージェントが2つの依頼を続けて受けます。R1はチェックアウトに10パーセントの割引を足すこと。R2はテストを通すこと。セッションの途中で、エージェントは偽の鍵（API_KEY=sk-test1234567890abcd）を含む.envを読み、テストを1回失敗させ（操作12）、コードを直し、再実行して合格し、2回コミットします。

5.1 偽の鍵は隠れていた#

操作7が.envの読み取りです。残った行はこうです。

{"actor": "agent", "args": {"path": ".env"}, "exit_code": 0, "files_changed": [], "prev": "2efa822af966", "request": "R1: add a 10 percent discount to checkout", "seq": 7, "session": "s-001", "summary": "loaded [REDACTED] (3 variables)", "tool": "read_file", "ts": "2026-10-31T09:00:13+07:00"}

ファイル全体でsk-testを探すと、一致する行は0行でした。秘匿処理は単純な正規表現なので、予想した形の鍵しか捕まえられません。最初の防御線であって、唯一の防御線ではないと考えてください。

この記事を書くときに出会ったバグ： 私の最初の版は、引数をJSONの文字列に変えてから秘密を隠していました。password=abc123を含むコマンドを試すと、\S+というパターンが閉じの引用符と括弧まで飲み込み、行が途中で切れて、検索スクリプトが読み込み時にエラーになりました。直し方は、文字列の値を1つずつ、JSONに変える前に隠すことです。付録のスクリプトのredact関数がそうしています。

5.2 時系列#

== timeline ==
 1 09:00:03 read_file    exit=0 src/checkout.py
 2 09:00:05 read_file    exit=0 src/pricing.py
 3 09:00:07 search       exit=0 discount
 4 09:00:09 read_file    exit=0 tests/test_discount.py
 5 09:00:10 run_command  exit=0 git status --short
 6 09:00:11 run_command  exit=0 git switch -c agent/discount
 7 09:00:13 read_file    exit=0 .env
 8 09:00:33 edit_file    exit=0 src/pricing.py
 9 09:00:45 edit_file    exit=0 src/checkout.py
10 09:00:54 run_command  exit=0 python -m pytest -q
11 09:01:19 edit_file    exit=0 tests/test_discount.py
12 09:01:27 run_command  exit=1 python -m pytest -q
13 09:01:29 read_file    exit=0 tests/test_discount.py
14 09:01:44 edit_file    exit=0 src/pricing.py
15 09:01:52 run_command  exit=0 python -m pytest -q
16 09:01:53 run_command  exit=0 git diff --stat
17 09:01:54 run_command  exit=0 git add -A
18 09:01:56 run_command  exit=0 git commit -m 'feat: add 10 percent discount'
19 09:01:58 read_file    exit=0 README.md
20 09:02:08 edit_file    exit=0 README.md
21 09:02:09 run_command  exit=0 git add README.md
22 09:02:11 run_command  exit=0 git commit -m 'docs: mention discount'
23 09:02:19 run_command  exit=0 python -m pytest -q
24 09:02:20 run_command  exit=0 git log --oneline -3
25 09:02:24 final_answer exit=0 -

5.3 3つの調査の問い#

== first failure ==
12 2026-10-31T09:01:27+07:00 run_command ran 20 tests, 18 passed, 2 failed
== files changed ==
README.md: 1 edit(s)
src/checkout.py: 1 edit(s)
src/pricing.py: 2 edit(s)
tests/test_discount.py: 1 edit(s)
== edits to test files ==
11 R2: make the tests pass ['tests/test_discount.py']

読み方：最初の失敗は、09:01:27の操作12です。その直前（操作11）で、エージェントはテストファイルに22行を足しました。失敗のあとは、もう一度テストファイルをいじるのではなくsrc/pricing.pyを編集しています（操作14）。つまり記録は、エージェントがテストをコードに合わせたのではなく、テストが通るようにコードを直したことを示しています。操作14がテストファイルの編集だったら、そこを念入りに見るべき場所になります。

同じ問いをjqで（Pythonなしで）：

jq -r 'select(.exit_code != 0) | "\(.seq) \(.ts) \(.summary)"' trail.jsonl
# 12 2026-10-31T09:01:27+07:00 ran 20 tests, 18 passed, 2 failed

jq -r '.files_changed[]' trail.jsonl | sort | uniq -c
#    1 README.md
#    1 src/checkout.py
#    2 src/pricing.py
#    1 tests/test_discount.py

5.4 書き換えられた行を見つける#

記録ファイルをコピーし、12行目の終了コードを1から0に変えて、失敗を「消し」ました。そのうえで連鎖の確認を再実行します。

== chain check ==
line 13: chain broken, an earlier line was changed
chain NOT ok
== first failure ==
none found

13行目には元の12行目の指紋が入っているため、12行目が変わると指紋が合わなくなります。最初の失敗の欄の「none found」は、連鎖の確認を飛ばすと、このセッションは問題なく動いたと結論してしまうことを示しています。

正直な限界： ハッシュ連鎖は検知するだけで、防止はしません。記録を書き換える人は、書き換えた行から後ろの連鎖をすべて計算し直せます。連鎖に意味を持たせるには、最後の行の指紋を、書き換える人の手が届かない場所（別のサービス、追記専用のシステム、第二の人）に保管する必要があります。

6. 保管量の計算（例、読み飛ばしてもよい）#

25行のファイルは7,170バイト、1行あたり約286.8バイトです。あるチームが1日に200セッション、各100操作だとします（計算のための仮定の数字です）。

per_line = 7170 / 25               # 286.8 bytes
per_day = 200 * 100 * per_line     # 5,736,000 bytes
print(round(per_day / 1e6, 2), round(per_day * 30 / 1e6, 1))
# 5.74 172.1   (MB per day, MB per 30 days)

1日約5.74MB、30日で172.1MBです。要約した記録なら、容量は大きな問題ではありません。もっと大きな問題は、誰が読めるかとどれだけ保管するかです。200と100は私の仮定で、286.8バイトはこの模擬で測った値です。出力が長い実際の記録はずっと重くなります。中身の全文を残さない理由はそこにあります。

7. 何かあった後に足跡を読み返す#

調査員がレシート帳を開くところを思い浮かべてください。順に5つの問いです。

1. 帳面は無傷か。 ハッシュ連鎖を確認するか、別の場所の写しと比べます。
2. いつ始まったか。 最初の失敗を探し、その直前の操作を見ます。
3. 誰が、何が指示したか。 requestとactorの項目を見ます。
4. どこまで及んだか。 変更ファイルと、外に効果が出るコマンド（コミット、プッシュ、削除）を一覧にします。
5. 再発を防ぐものは何か。 これは記録の外にあります。障害の振り返りを書くことです。2017年にGitLabで誤ってデータを消した日の話は、あるチームが出来事の後に経緯を語り直した一例です。

記録が助けるのは1から4です。5は人間の仕事です。

8. 記録が壊れやすい場所#

ページが抜けたり、書き間違いや消しゴムの跡があるノートを思い浮かべてください。

9. 例：ある午前、2つの展開#

これは想定した状況で、実在の人物や製品には触れていません。

操作の記録がない場合：

• 09:00。 開発者がエージェントに2つの仕事を任せ、11:30まで会議に入ります。
• 11:35。 開発者はブランチに2つのコミットを見つけます。同僚が聞きます。「なぜテストファイルが変わったの？」
• 11:40。 開発者は長い会話を開いてスクロールします。エージェントは「直しました」と言っていますが、どのファイルをどの順で直したかは書いていません。
• 12:20。 開発者は自信がないまま推測で答えます。

操作の記録がある場合：

• 09:00。 同じ2つの仕事。記録する層はエージェントの外で動いています。
• 11:35。 同僚が同じことを聞きます。
• 11:37。 開発者が「編集されたテストファイル」を検索します。操作11（09:01:19）が新しいテストを足し、操作14は、テストではなくコードを直しています。
• 11:40。 操作番号つきで答えが返ります。

どちらの場合も大事なこと：答えを記憶ではなく、番号のついた操作に結びつける。これは例なので、頻度については何も証明しません。根拠は末尾の出典にあります。

10. 手を動かす練習（答えつき）#

付録の2つのスクリプトを動かし、次の4つをしてみてください。

1. 失敗したrun_commandは何件で、何番の操作でしたか。
2. 2回以上編集されたファイルはどれですか。
3. stepsの一覧の末尾に、echo password=abc123とecho pwd=abc123の2つの操作を足します。再実行して、abc123を含む行がファイルに何行あるか数えてください。
4. ファイルの途中の1行を手で書き換え、連鎖の確認を動かします。どの行が壊れていると報告されますか。

答え：

1. 失敗は1件で、操作12です。
2. src/pricing.pyで、2回編集されています（操作8と14）。
3. abc123を含む行は、ちょうど1行です。password=abc123のコマンドはecho [REDACTED]に隠れ、pwd=abc123は、パターンにpwdという語がないためすり抜けます（私が実際に動かして、結果は1行でした）。固定のパターンによる秘匿の限界を示す例です。
4. 書き換えた行の直後の行です。その行が元の行の指紋を持っているからです。

11. 使った数字と文書#

正しく読むために： 操作の記録が調査時間をどれだけ短縮するかを測った研究は、見つけられませんでした。この記事の主張は、記録の仕組みから導いた良い実践であり、実験結果ではありません。

12. チェックリスト：エージェントの記録#

1. エージェントの外に記録する層がありますか。それとも、エージェントに「自分で記録して」と頼んだだけですか。
2. 各行に、時刻、セッション、実行者、元の依頼、ツール、結果、変更ファイルがありますか。
3. 書く前に秘密を隠していますか。偽の鍵で試しましたか。
4. 個人データやファイルの全文を残していませんか。
5. 記録は追記専用ですか。それともエージェントが編集できますか。
6. 最後の指紋か写しを、別の場所に保管していますか。
7. 3つの問い（時系列、最初の失敗、変更ファイル）の検索例がありますか。
8. 誰が読めて、どれだけ保管し、見直しはいつですか。

13. バランスよく：記録でできること、できないこと#

できること： 出来事の再現を短くし、「エージェントは何時に何をしたか」に答え、同僚に番号つきの根拠を渡し、連鎖を確認すれば書き換えられた行を見つけられます。

できないこと：

• 記録は、結果が正しいかどうかを示しません。成功したコマンドが間違ったことをしている場合もあります。正しさには、「AIの結果に証拠を添えさせる」のように回答に添えた証拠、テスト、人間の読み手が引き続き必要です。
• 被害を防ぎません。後から知る助けになるだけです。リスクの高い作業には、権限の制限と戻る手段も必要です。「エージェントを使う人のためのGit入門」のセーブポイントがその例です。
• 固定パターンの秘匿は、まだ思いついていない形の鍵を見逃します。
• 記録は容量を使い、誰が読むか、どれだけ保管するかというプライバシーへの配慮が要ります。
• 実際に動かした例は、1つのセッションの模擬にすぎません。実際のツールの記録には、もっと多くの項目と例外があります。

誇張しないでください： 記録があることは、安全であることを意味しません。軽く見ないでください： 最も必要なとき、つまり問題が起きたときに、頼れる最後のものになることが多いのです。

14. まとめ#

エージェントに仕事を任せて会議に出るのは普通のことです。普通でないのは、戻ってきたときに何をしたか分からないことです。別の層が書くレシート帳を持たせましょう。必要な分だけ残し、秘密を隠し、追記だけを許し、読み返し方を知っておく。記録は証拠やテストの代わりにはなりませんが、調査の午後を数分に縮めてくれます。

付録：2つの完全なスクリプト（読み飛ばしてもよい）#

agent_trail_demo.py：セッションを模擬して記録を書きます。

import hashlib
import json
import re
import sys
from datetime import datetime, timedelta, timezone
from pathlib import Path

LOG = Path(sys.argv[1] if len(sys.argv) > 1 else "trail.jsonl")
SECRET = re.compile(r"sk-[A-Za-z0-9]{8,}|(password|token|api_key)\s*[=:]\s*\S+", re.I)


def redact(value):
    """Hide secrets in every string inside a value, before it is turned into JSON."""
    if isinstance(value, str):
        return SECRET.sub("[REDACTED]", value)
    if isinstance(value, dict):
        return {k: redact(v) for k, v in value.items()}
    return value


class Trail:
    """Append-only JSON Lines trail. Each line carries the hash of the previous line."""

    def __init__(self, path, session):
        self.path, self.session, self.prev, self.seq = path, session, "start", 0
        self.clock = datetime(2026, 10, 31, 9, 0, 0, tzinfo=timezone(timedelta(hours=7)))
        path.write_text("")

    def record(self, request, tool, args, exit_code, summary, files=(), seconds=2):
        self.clock += timedelta(seconds=seconds)
        self.seq += 1
        line = {
            "seq": self.seq,
            "ts": self.clock.isoformat(),
            "session": self.session,
            "actor": "agent",
            "request": request,
            "tool": tool,
            "args": redact(args),
            "exit_code": exit_code,
            "summary": redact(summary),
            "files_changed": list(files),
            "prev": self.prev,
        }
        text = json.dumps(line, ensure_ascii=False, sort_keys=True)
        self.prev = hashlib.sha256(text.encode()).hexdigest()[:12]
        with self.path.open("a") as f:
            f.write(text + "\n")


trail = Trail(LOG, "s-001")
R1 = "R1: add a 10 percent discount to checkout"
R2 = "R2: make the tests pass"
steps = [
    (R1, "read_file", {"path": "src/checkout.py"}, 0, "120 lines", (), 3),
    (R1, "read_file", {"path": "src/pricing.py"}, 0, "80 lines", (), 2),
    (R1, "search", {"pattern": "discount"}, 0, "4 matches in 2 files", (), 2),
    (R1, "read_file", {"path": "tests/test_discount.py"}, 0, "45 lines", (), 2),
    (R1, "run_command", {"cmd": "git status --short"}, 0, "clean", (), 1),
    (R1, "run_command", {"cmd": "git switch -c agent/discount"}, 0, "switched to new branch", (), 1),
    (R1, "read_file", {"path": ".env"}, 0, "loaded API_KEY=sk-test1234567890abcd (3 variables)", (), 2),
    (R1, "edit_file", {"path": "src/pricing.py"}, 0, "+14 -2 lines", ("src/pricing.py",), 20),
    (R1, "edit_file", {"path": "src/checkout.py"}, 0, "+6 -1 lines", ("src/checkout.py",), 12),
    (R1, "run_command", {"cmd": "python -m pytest -q"}, 0, "ran 18 tests, 18 passed", (), 9),
    (R2, "edit_file", {"path": "tests/test_discount.py"}, 0, "+22 -0 lines", ("tests/test_discount.py",), 25),
    (R2, "run_command", {"cmd": "python -m pytest -q"}, 1, "ran 20 tests, 18 passed, 2 failed", (), 8),
    (R2, "read_file", {"path": "tests/test_discount.py"}, 0, "67 lines", (), 2),
    (R2, "edit_file", {"path": "src/pricing.py"}, 0, "+3 -1 lines", ("src/pricing.py",), 15),
    (R2, "run_command", {"cmd": "python -m pytest -q"}, 0, "ran 20 tests, 20 passed", (), 8),
    (R2, "run_command", {"cmd": "git diff --stat"}, 0, "3 files changed, 45 insertions, 4 deletions", (), 1),
    (R2, "run_command", {"cmd": "git add -A"}, 0, "staged 3 files", (), 1),
    (R2, "run_command", {"cmd": "git commit -m 'feat: add 10 percent discount'"}, 0, "1 commit created", (), 2),
    (R2, "read_file", {"path": "README.md"}, 0, "30 lines", (), 2),
    (R2, "edit_file", {"path": "README.md"}, 0, "+5 -0 lines", ("README.md",), 10),
    (R2, "run_command", {"cmd": "git add README.md"}, 0, "staged 1 file", (), 1),
    (R2, "run_command", {"cmd": "git commit -m 'docs: mention discount'"}, 0, "1 commit created", (), 2),
    (R2, "run_command", {"cmd": "python -m pytest -q"}, 0, "ran 20 tests, 20 passed", (), 8),
    (R2, "run_command", {"cmd": "git log --oneline -3"}, 0, "3 commits listed", (), 1),
    (R2, "final_answer", {}, 0, "reported done, branch agent/discount", (), 4),
]
for step in steps:
    trail.record(*step)
print(f"wrote {trail.seq} lines to {LOG}")

query_trail.py：連鎖を確認して検索します。

import hashlib
import json
import sys
from collections import Counter

path = sys.argv[1] if len(sys.argv) > 1 else "trail.jsonl"

print("== chain check ==")
prev, ok = "start", True
for i, line in enumerate(open(path), 1):
    if not line.strip():
        continue
    if json.loads(line)["prev"] != prev:
        print(f"line {i}: chain broken, an earlier line was changed")
        ok = False
        break
    prev = hashlib.sha256(line.rstrip("\n").encode()).hexdigest()[:12]
print("chain ok" if ok else "chain NOT ok")

rows = [json.loads(line) for line in open(path) if line.strip()]

print("== timeline ==")
for r in rows:
    args = r["args"]
    arg = args.get("cmd") or args.get("path") or args.get("pattern") or "-"
    print(f'{r["seq"]:>2} {r["ts"][11:19]} {r["tool"]:<12} exit={r["exit_code"]} {arg}')

print("== first failure ==")
first = next((r for r in rows if r["exit_code"] != 0), None)
print(f'{first["seq"]} {first["ts"]} {first["tool"]} {first["summary"]}' if first else "none found")

print("== files changed ==")
counts = Counter(f for r in rows for f in r["files_changed"])
for name, n in sorted(counts.items()):
    print(f"{name}: {n} edit(s)")

print("== edits to test files ==")
for r in rows:
    if any(f.startswith("tests/") for f in r["files_changed"]):
        print(r["seq"], r["request"], r["files_changed"])

実行：python3 agent_trail_demo.py trail.jsonl、続けてpython3 query_trail.py trail.jsonl。模擬の時計は固定なので、このスクリプトをそのまま使えば、あなたのファイルの指紋（prevの項目）は私のものと一致します。

参考資料#

数字は2026年10月時点の公開情報によります。二次情報も含まれるため、引用する前に原典を開いて確認してください。

• Anthropic、2026 Agentic Coding Trends Report（紹介ページ。全文はフォームの先）
• Stack Overflow、2026 Developer Survey（要約を通じて読んだもの。各表とは未照合）
• Anthropic、Claude Code: Hooks reference（JSONの項目、イベント、終了コード、記録のパス）
• OpenTelemetry、GenAI semantic conventions（ページはリポジトリ移転済み）と、Development段階に関する二次的な解説、たとえばDash0
• jq、jq Manual（フィルタとgsub）
• 関連記事：AIの結果に証拠を添えさせる、エージェントを使う人のためのGit入門、少人数チームのAI利用ポリシー1ページ

コードを書く人、AIにコードを書かせる人なら誰でも、初心者の方でも読めます。セキュリティの知識は不要です。用語にはどれも身近なたとえを添え、コマンドを実行する部分は印をつけてあるので、今は不要なら読み飛ばせます。

この記事に出てくるキーはすべて偽のキーで、AWSの文書に載っている例のキーの組も含みます。数字は公開情報から取っており、末尾に一覧があります。「例」と書いたものは作った例で、実在の人物や会社には触れていません。これは実践のための解説で、あなたのシステムに対するセキュリティの助言ではありません。

まず要点#

• APIキー、パスワード、アクセストークンは秘密情報です。持っている人なら誰でも使えます。家の鍵と同じです。
• ファイルからキーを消しても終わりではありません。 gitは古い版をすべて覚えています。この記事の実験では、2つ目のコミットでキーを消したあとも、git log -Sが両方のコミットを見つけ、git showがキーをもう一度表示しました。
• キーが漏れたときの正しい順番は、先にキーを無効化または入れ替え、次に履歴を掃除し、そして利用ログを読むことです。 GitHubの文書も同じ趣旨です。
• 履歴を書き換えても、すでにあるコピーは取り戻せません。 実験では、書き換える前に作ったクローンにキーが残っていました。
• 環境変数、.gitignore、30行ほどのpre-commitフック、プラットフォームのスキャンで早めに止められます。どの層にも抜けがあるので、重ねて使います。
• AIエージェントと働くときは、3つの習慣を足します。本物のキーを会話に貼らない、.envファイルをエージェントの手の届かない所に置く、コミットの前に差分を読む、です。

むずかしい言葉をやさしく#

この記事のあと、説明できるようになること#

1. ファイルからキーを消してもキーが消えない理由と、3つのgitコマンドでの確かめ方。
2. キーが漏れたときの正しい順番（先に入れ替え、あとで掃除）と、履歴の書き換えだけでは足りない理由。
3. 3つの守りの層（コードの外に置く、コミットで止める、プッシュ後にスキャンする）と、それぞれの抜け。

1. まずイメージ：玄関マットの下の鍵#

家の鍵を玄関マットの下に隠していたとします。翌日、それはまずいと気づいて鍵を引き出しに移しました。ところがその1日のうちに、通りがかった隣人が合鍵を作っていたかもしれません。鍵をしまっても、合鍵は消えません。確実な方法は錠前を替えることだけです。

コードの中のAPIキーも同じです。コミットした時点で、gitはコピーを保存しています。誰かがリポジトリをクローンしたかもしれません。自動のスキャナが公開リポジトリから読み取ったかもしれません。次のコミットで1行消すのは、鍵を引き出しにしまうようなもので、よいことですが、合鍵の問題は解決しません。

教訓： 秘密が隠し場所を出てしまったら、漏れたものとして扱い、しまい直すのではなく錠前を替えます。

2. 何が秘密情報で、どこから漏れるか#

漏れが起きやすい場所：

• gitに直接コミットして、次のコミットで消す（3章で実際に試します）。
• .envファイルをコミットしてしまう。.gitignoreに入れ忘れた、または入れる前にコミットした場合です。
• キーを含むログやスクリーンショットを、同僚に送ったり掲示板に載せたりする。
• AIとの会話に貼る。「エラーを見せるため」に貼った内容は、会話の履歴に保存され、あとで再表示されることがあります。
• ブラウザ側で動くコード（クライアントバンドル）：ユーザーのブラウザに送られるものはすべて読めるので、秘密のキーを置いてはいけません。

教訓： 秘密は1つの扉からだけ漏れるのではありません。だから予防は何層にも重ねます。

3. 実際の実験：消したのに、残っている#

この章のコマンドと出力はすべて、使い捨てのリポジトリで実際に実行したもので、Git 2.56.0とPython 3.14.8、偽のキーだけを使っています。コミットのハッシュは実行のたびに変わります。時間は私のマシンで2コミットのリポジトリを使った値なので、桁を知る目安にしてください。

3.1 偽のキーをコミットし、次のコミットで消す#

git init -q -b main repo
cd repo

# config.pyにはAWSの文書にある例のキーの組（偽のキー）が入っている
#   AWS_ACCESS_KEY_ID = "AKIAIOSFODNN7EXAMPLE"
#   AWS_SECRET_ACCESS_KEY = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
git add .
git commit -m "add config"             # 約0.03秒

# 次のコミットで環境変数から読むように変える
git add .
git commit -m "remove secret from config"

git log --oneline

2bfea15 remove secret from config
a0d01a2 add config

3.2 見た目はきれい#

grep -n AKIA config.py          # 一致なし
git grep AKIA                   # 一致なし。今のファイルだけを探す

どちらも何も表示しません。今のファイルは確かにきれいです。

3.3 でも履歴には残っている#

git log --oneline -S AKIAIOSFODNN7EXAMPLE

2bfea15 remove secret from config
a0d01a2 add config

-Sは、その文字列の出現回数が変わったコミットを探すので、追加したコミットと削除したコミットの両方が出ます。次に、すべてのコミットを探し、古いファイルを表示します。

git grep -n AKIA $(git rev-list --all)      # 約0.02秒
git show a0d01a2:config.py

a0d01a2473ddcb923dbfd69164c1df8a11de379b:config.py:3:AWS_ACCESS_KEY_ID = "AKIAIOSFODNN7EXAMPLE"

import os

AWS_ACCESS_KEY_ID = "AKIAIOSFODNN7EXAMPLE"
AWS_SECRET_ACCESS_KEY = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
REGION = "ap-southeast-1"

3つのコマンドと1秒未満で、このリポジトリを持っている人なら誰でも、2つのキーをもう一度読めます。

教訓： ファイルがきれいでも、リポジトリがきれいとは限りません。履歴を探す必要があります。

4. キーが漏れたときの正しい順番#

「あなたの家の合鍵が作られたらしい」と誰かに教えられたとします。まず錠前を替え、そのあとで誰が入ったかを調べるはずです。

1. すぐにキーを無効化または入れ替える。 GitHubのシークレットスキャンの文書は「すぐに」入れ替えることを勧め、キーが無効になっていればgit履歴からの削除は時間がかかり、たいてい不要だと述べています。
2. キーの利用ログを読む。 サービス側で、公開されていた間に、誰が、どこから、いつ使ったかを見ます。
3. 必要なら履歴を掃除する（6章）。次のプッシュにキーが含まれないようにするためです。
4. 記録を残し、 再発を防ぐ仕組みを入れます（5章）。

4.1 AWSのキーの入れ替え：文書にある手順#

AWSの「アクセスキーの更新」の文書は、アプリケーションを止めずに入れ替える手順を説明しています。

1. 最初のキーが有効なうちに、2つ目のキーを作る（このとき2つのキーが同時に有効）。
2. すべてのアプリケーションとツールを新しいキーに更新する。
3. 古いキーの「最終使用」の情報を見て、まだ使われていないか確かめる。文書は、数日待つ方法もあると述べています。
4. 古いキーをすぐには削除しない。先に非アクティブにする。
5. 新しいキーだけでアプリケーションが動くか確認する。古いキーをまだ使っているものは動かなくなり、一時的に古いキーを有効に戻すこともできます。
6. しばらく待ったあと、古いキーを削除する。

この手順は、待つ時間のある通常の入れ替えのために書かれています。すでに漏れたキーについて、古いキーをすぐに無効にするのは、GitHubの「先に無効化」という考え方からの私の推論で、AWSの文書に書いてあることではありません。代償として、古いキーをまだ使っているものはすぐ動かなくなるので、新しいキーを用意してから行います。

4.2 15分でできること、できないこと#

これは私が提案する目標で、実測値ではありません。実際の時間は、すでに権限があるか、キーがどこで使われているかを把握しているかによります。

教訓： 15分あれば扉を閉めることはできます。被害を調べるのは、そのあとの数時間の仕事です。

5. 早めに止める：何層も重ね、どの層にも抜けがある#

3つの層がある家を想像してください。鍵を持ち出さない、玄関で誰かが声をかける、通りにカメラがある、の3つです。

5.1 第1層：秘密をコードの外に置く#

秘密は環境変数や秘密の保管サービスに置き、設定ファイルには「この変数から読む」とだけ書きます。実験の2つ目のコミットがまさにそうでした。

AWS_ACCESS_KEY_ID = os.environ["AWS_ACCESS_KEY_ID"]

手元で.envファイルを使うなら、ファイルを作る前に.gitignoreに入れます。実際に試しました（私の実行環境では.envという名前のファイルを作れないため、dev.envという名前にしました。仕組みは同じです）。

git status --short

?? dev.env
?? tools/

echo "dev.env" > .gitignore
git status --short
git check-ignore -v dev.env

?? .gitignore
?? tools/
.gitignore:1:dev.env    dev.env

dev.envは一覧から消え、check-ignoreは.gitignoreのどの行が止めているかを教えてくれます。ただし、.gitignoreが効くのはgitがまだ追跡していないファイルだけです。以前にコミットしたファイルで試しました。

git add -f old.env
git commit -m "oops: commit old.env"
echo "old.env" >> .gitignore
git ls-files old.env

old.env

.gitignoreに入れても、gitはこのファイルを追跡し続けています。追跡をやめるにはgit rm --cached old.envが必要で、履歴の中のキーは3章のとおり残ります。

5.2 第2層：pre-commitフックでコミット時に止める#

次は小さなスキャナ（Pythonで30行ほど）です。これから追加される行を読み、3つの形を探します。AWS形式のキー、秘密鍵のヘッダー、api_key、secret、token、passwordのような名前に文字列を代入する行です。

PATTERNS = {
    "aws access key id": re.compile(r"AKIA[0-9A-Z]{16}"),
    "private key header": re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"),
    "key or password assigned to a string": re.compile(
        r"""(?i)(api[_-]?key|secret|token|passwd|password)\w*\s*[=:]\s*['"][^'"\s]{8,}['"]"""
    ),
}
# 読むもの：git diff --cached -U0。「+」で始まる行を調べ、一致したら終了コード1で終わる

.git/hooks/pre-commitに設定します。

#!/bin/sh
exec python3 tools/scan_secrets.py

偽のキーを含むファイルをコミットしようとすると：

Blocked: this commit adds something that looks like a secret.
  deploy.py: key or password assigned to a string
Use an environment variable, then rotate the key if it was ever real.
exit code: 1

コミットは断られます（試行全体で約0.14秒）。ただし、このスキャナには弱点が2つあり、両方を試しました。

• 見逃し： キーを2つの文字列に分けて（part1 = "AKIA"、part2 = "IOSFODNN7EXAMPLE"、あとでつなぐ）書くと、コミットは終了コード0で通ります。
• 誤検知： サンプル文書のpassword = "change-me-please"という行は、ただの仮の文字なのに止められます。

教訓： 文字のパターンで探すスキャナは、よくあるミスは見つけますが、意図的な、または巧妙なものは見つけられず、ときには誤って警報を鳴らします。保証と考えないでください。

フックは.git/hooksにあり、リポジトリと一緒には配られません。チームで共有するには、フックを配る仕組み（たとえばプロジェクト内のフック管理ツール）が必要で、各自が--no-verifyで飛ばすこともできます。

5.3 第3層：プッシュのあとでスキャンし、プッシュで止める#

プラットフォームにはこのための機能があります。私が読んだGitHubの文書のページ（ページ要約ツール経由）によると：

• シークレットスキャンは、APIキーやパスワードのような漏れた認証情報を自動で検出し、「すべてのブランチのgit履歴全体」と、issue、プルリクエスト、ディスカッション、wikiの文章を調べます。
• プッシュ保護は、秘密を含むプッシュを、リポジトリに届く前に止めます。提供元のパターン、一般的なパターン（秘密鍵やデータベース接続文字列など）、独自のパターンを認識します。リポジトリ単位では初期設定はオフで、書き込み権限のある人は理由を示せば回避できます。ユーザー単位では、GitHub.comの公開リポジトリへ秘密をプッシュするのを止める機能が、初期設定でオンと文書に書かれています。

これらのページは要約ツールを通して読んだだけで、一字一句は確認していません。元のページ（末尾の参考資料）を開き、ご自身のアカウントの設定を見てください。gitleaks、trufflehog、git-filter-repoのような独立したツールもありますが、ここでは実行していません。私のテスト環境にはインストールしていないからです。

6. 履歴の掃除：できることと、できないこと#

キーを入れ替えたあとは、リポジトリからもキーをなくしたくなるかもしれません。現在お勧めされているツールはgit filter-repoですが、私のテストマシンにはなく、実行できませんでした。そこで、Gitに付属するgit filter-branchで実演します（Gitの文書ページは、このコマンドの使用は「推奨されない」と書き、git filter-repoを勧めていますが、動くので説明には十分です）。

git clone -q repo clone-before       # 書き換える「前」にコピーを取る
cd repo
git filter-branch -f --tree-filter "python3 redact.py" -- --all   # 約0.8秒、5コミット

ここでredact.pyは、すべてのコミットの2つの偽キーの文字列をREDACTEDに置き換えます。確認します。

git log --oneline -S AKIAIOSFODNN7EXAMPLE main

何も表示されません。mainブランチはきれいになりました。ところが、ほかの場所にはまだキーが残っています。

git for-each-ref --format='%(refname)'

refs/heads/main
refs/original/refs/heads/main

ツールはバックアップ用の参照refs/original/refs/heads/mainを残し、git log -S AKIAIOSFODNN7EXAMPLE --allには古い2つのコミットがまだ見えます。掃除するには、バックアップの参照を削除し、reflogを期限切れにし、どこからも指されていないオブジェクトを整理します。

git for-each-ref --format='%(refname)' refs/original | xargs -n1 git update-ref -d
git reflog expire --expire=now --all
git gc -q --prune=now                          # 約0.1秒
git log --oneline -S AKIAIOSFODNN7EXAMPLE --all --reflog   # 何も表示されない
git cat-file -t a0d01a2        # fatal: Not a valid object name

これでこのリポジトリは完全にきれいです。では、書き換える前に取ったコピーは？

cd ../clone-before
git log --oneline -S AKIAIOSFODNN7EXAMPLE
git cat-file -t a0d01a2

2bfea15 remove secret from config
a0d01a2 add config
commit

そのコピーにはまだキーが残っています。だから履歴の掃除は、キーの入れ替えの代わりになりません。以前にpullしたりforkしたりした人は古い版を持ち続けますし、公開リポジトリなら誰かがコピーや保存をしているかもしれません。

もう1つ注意があります。履歴を書き換えるとコミットのハッシュが変わるので、チームメンバーはpullし直す必要があり、競合が起きることもあります。先に知らせてください。記事エージェントを使う人のためのGit入門で、強制プッシュに注意が必要な理由を説明しています。

7. AIエージェントと働くとき：さらに6つの習慣#

業者を家に入れるときを想像してください。マスターキーではなく、有効期限があり、1部屋だけ開く鍵を渡します。

1. 本物のキーを会話に貼らない。 AIにエラーを見せる必要があるときは、キーを<API_KEY>のような仮の文字に置き換えます。
2. .envファイルを、エージェントが読める場所の外に置く。 またはツールの読み取りを止める設定を使います。プロジェクトのフォルダ全体を読めるエージェントは、その中の秘密も読めます。
3. 権限が狭く、有効期限の短いキーを使う。 エージェントの作業には、そのタスクに足りるだけで、すぐに期限が切れるキーにします。
4. コミットの前に差分を読む。 エージェントは「すぐ動くように」と接続文字列をコードに直接書くことがあります。git addを1回するだけで、履歴に入ってしまいます。AIが書いたコードのレビューを参照してください。
5. エージェントにメインブランチへ直接プッシュさせない。 誰も見ていない状態で、インストールや高権限のコマンドを実行させません。AIアプリのOWASP Top 10も参照してください。
6. ルールをチームの方針に入れる。 記事少人数チームのためのAI利用ポリシー1ページには、この種のデータのための「禁止」の列があります。

7.1 例：エージェントにデータベース接続を頼んだ朝#

これは想定した例で、実在の人物や製品には触れていません。名前や値は作ったものです。

この習慣がない場合：

• 10:00。 開発者がエージェントに「データベースにつないで。接続文字列はこれ」と頼み、本物の文字列を会話に貼る。
• 10:10。 エージェントはconfig.pyを書き、「すぐ動くように」接続文字列をコードに直接書いてコミットする。
• 10:20。 開発者はざっと見て、動くのを確認してプッシュする。
• 10:45。 プラットフォームから、リポジトリに秘密が検出されたという通知が来る。開発者はその行を消して再プッシュし、終わったと思う。

この習慣がある場合：

• 10:00。 開発者は接続文字列を自分のマシンの環境変数に入れ、エージェントに「DATABASE_URLから読んで。値をコードに書かないで」と頼む。
• 10:10。 エージェントは環境変数を読むconfig.pyを書く。pre-commitフックは何も異常を見つけない。
• 10:20。 開発者は差分を読み、変数名だけなのを確認してプッシュする。

最初の展開になってしまったら、10:45にすべきことは、データベースのパスワードをすぐに入れ替えること、次にアクセスログを読むこと、履歴の掃除を考えるのはそのあとです。次のコミットでその行を消しても何も解決しません。履歴に古い文字列が残り、AIとの会話にも含まれているからです。

8. よくある間違い#

9. 使った数字と文書#

使わなかった数字： 「100個のアプリのうち41%で秘密やAPIキーが露出していた」という、VibeWrenchの調査（2026年3月）とされる数字を確かめようとしました。裏づける出典は見つかりませんでした。VibeWrenchの製品ページには、100個のアプリを調べて318件の脆弱性を見つけたとだけあり、キー露出の割合は書かれていません。そのためこの記事では、その数字を使いません。

正しく読むために： 仕組み（gitは履歴を覚えている、コピーは残る）には、自分で再実行できるので良い根拠があります。キーが一般にどのくらいの頻度で漏れるかについて信頼できる数字はなく、pre-commitフック単独の効果を測った研究も見つけられませんでした。

10. 答えつきの練習（30分）#

課題。 使い捨てのリポジトリを作り、偽のキー（上のAWSの例の組のようなもの。本物は絶対に使わない）で次を行います。

1. 偽のキーを含むファイルをコミットし、次のコミットでキーを消す。
2. git log -Sとgit showで、キーがまだあることを示す。
3. 本物のキーだったと仮定して、5段階の対応の順番を書く。
4. スキャン用のpre-commitフックを入れ、直接代入したキーのコミットと、2つの文字列に分けたキーのコミットを試す。
5. リポジトリのコピーを取り、git filter-branchで履歴を書き換え、両方のリポジトリを確認する。

答え。

1. 2回のコミットのあと、git log --onelineは2行を表示する。
2. git log --oneline -S <キー>が両方のコミットを表示する。git show <最初のコミット>:<ファイル>がキーを表示する。
3. 妥当な順番：(1) サービス側で古いキーを無効にする、(2) 新しいキーを作って使う場所を更新する、(3) アプリケーションを確認する、(4) 利用ログを読む、(5) 必要なら履歴を掃除し、チームに知らせる。採点のポイントは、入れ替えが履歴の掃除より前にあること。
4. 直接代入したキーのコミットは止められる（終了コード1）。分けたキーは、スキャナが完全なパターンしか探さないため止められない。
5. バックアップの参照を消し、reflogを期限切れにしてgcを実行すると、書き換えたリポジトリはきれいになる。以前に取ったコピーにはキーが残る。スキャナの改善案：追加行だけでなくファイル全体をスキャンする、文字列のランダムさで判定する、専用ツールを使う。

11. プッシュする前のチェックリスト#

1. この変更に、本物の秘密（キー、パスワード、接続文字列、秘密鍵）は入っていないか。
2. 秘密は環境変数や秘密の保管場所にあり、コードの中にないか。
3. .envなどのファイルを、ファイルを作る前に.gitignoreに入れたか。
4. コミットの前に差分を読み、変に長い文字列を探したか。
5. 手元でスキャンのフックが動き、プラットフォーム側のスキャンもオンか。
6. 使っているキーは権限が狭く、有効期限が短いか。
7. 本物のキーをAIとの会話に貼ったことはないか。あるなら入れ替える。
8. 今キーが漏れたら、どこで入れ替えるか、どのくらいかかるか、誰に知らせるかを分かっているか。

12. バランスよく：分かっていること、まだ分からないこと#

かなり確か： gitは履歴を保持し、消したキーを再表示できる。履歴の書き換えは、すでにあるコピーを取り戻せない。文字のパターンで探すスキャナは、見逃しも誤検知もある。キーの入れ替えが根本の一手である。4つとも、この記事で実際に実行しました。

不明、または限られていること：

• キーが現実にどのくらいの頻度で漏れ、どのくらい被害が出るか。今ある数字は主にセキュリティ会社が自社のサンプルを調べたもので、確認できなかった数字は外しました。
• 各防御層の実際の効果。pre-commitフックやプッシュ保護の単独の効果を測った研究は見つかりませんでした。
• 専用ツール（git-filter-repo、gitleaks、trufflehog）は実行していません。使う前に文書を読んでください。
• プラットフォームごとに機能や初期設定が違います。GitHubのページは要約ツール経由で読んだもので、変わっているかもしれません。

大げさにしない： どの層も1つだけでは足りません。軽く見ない： 予防のコストは設定の数分ですが、漏れたキーは他人があなたのデータや資源に触れる原因になりえます。

13. まとめ#

APIキーが一度gitに入ったら、手元を離れたものとして扱います。次のコミットで1行消すのは、鍵を引き出しにしまうだけで、合鍵は外にあるままです。まずキーを入れ替え、ログを読み、そのあとで履歴を掃除します。繰り返さないために、秘密をコードの外に置き、コミットで止め、プッシュのあとでスキャンし、AIエージェントには権限が狭く期限の短いキーを渡し、コミットの前には必ず差分を読みましょう。

参考資料#

数字は2026年10月時点の公開情報です。GitHubとAWSのページはページ要約ツール経由で読んだので、引用する前に元のページで確認してください。

• GitHub Docs、About secret scanning
• GitHub Docs、About push protection
• AWS Documentation、Update access keys（IAMユーザーガイド）
• Escape、The State of Security of Vibe Coded Apps（日付なし、セキュリティ会社による独自の調査）
• Git、git-filter-branchとgit-log（-Sオプション）

AIでコードを書く人、AIエージェントに作業を任せる人なら誰でも、初心者の方でも読めます。モデルの仕組みについての知識は要りません。用語にはどれも身近なたとえを添えています。計算の部分は印をつけてあるので、不要なら読み飛ばせます。

数字は公開情報から取っており、末尾に一覧があります。「例」と書いたものは作った例で、実在の人物や会社には触れていません。**この記事の料金はすべて、計算を分かりやすくするための仮定であり、現在の料金表ではありません。**料金は提供元によって、また時間とともに変わるからです。モデルの内部がどう動くかは、まだ誰にも完全には分かっていないので、たとえは覚えやすくするための補助にすぎません。一方、課金の仕組みはドキュメントに書かれており、この記事はそれに沿っています。

まず要点#

• AIはトークン（モデルが読み込み、書き出す文章の断片）で課金します。請求額は、入力トークン数に入力単価を掛けたものと、出力トークン数に出力単価を掛けたものの合計です。
• 何ターンも続く会話では、毎ターン履歴全体が再送されます。そのため費用はターン数より速く増えます。この記事の計算例では、15ターンで入力322,500トークンに対し出力は7,500トークンだけで、ターン数を倍にすると入力は約3.4倍になりました。
• プロンプトキャッシュを使うと、読み直しの費用を大きく減らせます。例では費用が約31%になりました。ただしルールや料金は提供元ごとに違い、長く間が空くとキャッシュは切れます。
• 予算内に収める3つの方法：短いセッションにして、要約から新しいセッションを始める、日常作業には安いモデル、支出の上限と監視。
• 流れは従量課金に向かっています。Gartner（2026年6月24日）は、AIコーディングの費用が2028年に平均的な開発者の給与を超えうると予測し、GitHubは2026年6月1日にCopilotをトークン基準のクレジットへ移しました。
• トークン単価が一番安いことは、1件の作業が終わるまでの費用が一番安いことではありません。費用とやり直しを一緒に測ってください。

むずかしい言葉をやさしく#

この記事のあとで説明できるようになること#

1. トークンとは何か、同じ内容でも言語や分割の仕方でトークン数が変わる理由。
2. 長い会話がターン数より速く高くなる理由と、キャッシュがそれをどう和らげるか。
3. 費用を予算内に収める3つの方法と、トークン単価が一番安いことが一番の節約とは限らない理由。

1. まずイメージ：タクシーメーターと、読み直さなければならないノート#

とても優秀な回答者を雇ったと想像してください。ただしこの人は、質問と質問の間のことを何も覚えていません。あなたが聞くたびに、これまでのやり取りを書いたノート全体を最初から読み直してから答えを書きます。料金は、読んだページ数と書いたページ数に応じて、タクシーメーターがキロごとに上がるように加算されます。

1問目はノートが薄く、読むのも速くて安い。15問目はノートが厚くなり、読み直すたびに費用が増えます。毎ターンあなたが付け足すのは数行かもしれませんが、読み直す分は増え続けます。

このたとえは覚えやすくするための補助です。はっきり文書化されているのは課金の仕組みです。AIサービスは送り込んだトークンと生成されたトークンに課金し、複数ターンの会話では、過去の履歴が毎ターン入力の一部になります（コンテキストウィンドウの記事も参照）。

**要点：**請求額は、あなたが打つ文の数では増えません。ノートを読み直す回数と、ノートの厚さを掛け合わせた分だけ増えます。

2. トークンとは何か#

2.1 単語ではなく、文章の断片#

モデルは1文字ずつ、あるいは単語まるごとではなく、断片で読みます。よく使う単語は1つの断片、まれな単語はいくつかに切られ、句読点も1つの断片です。切り方はモデルごとに違うため、間違えやすいので、ここでは具体的な切り分け例は載せません。

英語では「1トークンおよそ4文字」という経験則がよく言われます。元のページでは確認できていません（OpenAIのトークナイザのページを開いたところ403エラーでした）。大まかな見積もりの仮定として扱います。

2.2 同じ内容でも、トークン数が違う#

Petrov、La Malfa、Torr、Bibi（2023）は、同じ文章を多くの言語に翻訳してトークン化後の長さを比べ、場合によっては最大約15倍の差があることを示しました。多言語向けに作られたトークナイザでも差は残ります。著者らは、これが一部の言語の利用者にとって費用の増加につながりうると論じています。

あなたにとっての意味：ベトナム語や日本語でAIに頼むと、1文字あたりのトークン数が英語より多くなることがあります。この記事を書いた環境ではトークンの数え方を実行できず（トークナイザのライブラリが入っていませんでした）、ベトナム語や日本語の独自の数字は出していません。正しいやり方は、実際に使うツールのトークンカウンタで、自分の文章を測ることです。この研究が測ったのは2023年頃のモデルで、新しいモデルでは違う可能性があります。

**要点：**単語数からトークン数を推測しないでください。提供元のカウンタで、自分の内容を測りましょう。

3. 入力と出力の料金#

多くの提供元は、入力トークンと出力トークンに別の料金をつけており、出力のほうが1トークンあたり高いのが普通です。2026年10月30日に読んだAnthropicのドキュメントの料金表から例を挙げます（100万トークンあたり）。

この3行では、出力はどれも入力の5倍で、小さいモデルは大きいモデルよりずっと安くなっています。ただし、これはある提供元のある時点の例として見てください。料金は変わり、モデル名も変わり、他の提供元は別の料金設定です。

とはいえ、「出力が高いから入力は気にしなくていい」と結論しないでください。第4節の計算が示すように、長い会話では入力が請求額の最大の部分になります。繰り返し送られるからです。

4. なぜ請求額が膨らむのか：動くスクリプトで計算する#

イメージ：毎ターン、ノートが少し厚くなり、読み直されます。

4.1 仮定（例、計算部分は読み飛ばせます）#

これは作った数字による例で、特定のツールでの実測ではありません。

• 最初に、指示とファイルとして6,000トークンを送ります。
• 毎ターン、新しい内容が1,500トークン加わります（あなたが書く文、ツールの出力）。
• 毎ターン、モデルが500トークン書き、それが履歴に加わります。
• 仮定した料金：入力100万トークンあたり2ドル、出力100万トークンあたり10ドル。
• キャッシュあり：キャッシュ済みの部分を読み直す費用は入力料金の0.1倍、新しい部分の書き込みは1.25倍。この2つの係数はAnthropicのドキュメントの標準値です（読み取り係数がもっと低いモデルもあります）。

4.2 再実行できるスクリプト#

# Illustrative numbers only. Change them to match your own tool and price list.
BASE = 6000           # tokens of instructions and files sent at the start
NEW_IN = 1500         # new tokens added each turn (your message, tool output)
OUT = 500             # tokens the model writes each turn
PRICE_IN = 2.00       # dollars per million input tokens (assumption)
PRICE_OUT = 10.00     # dollars per million output tokens (assumption)
READ = 0.10           # cache read costs 0.1 x input price (assumption)
WRITE = 1.25          # cache write costs 1.25 x input price (assumption)

def run(turns, base=BASE, new_in=NEW_IN, out=OUT):
    sent = 0                      # input tokens sent in total
    cost_plain = 0.0              # no caching: everything at full input price
    cost_cache = 0.0              # with caching: read old part cheaply, write new part
    context = base                # tokens already in the conversation
    prev_in = 0                   # what the previous call sent (it is in the cache)
    for t in range(1, turns + 1):
        this_in = context + new_in            # whole history is sent again
        sent += this_in
        cost_plain += this_in * PRICE_IN / 1e6
        if t == 1:
            cost_cache += this_in * PRICE_IN * WRITE / 1e6
        else:
            cost_cache += prev_in * PRICE_IN * READ / 1e6            # read what was cached
            fresh = this_in - prev_in                                # last output + new content
            cost_cache += fresh * PRICE_IN * WRITE / 1e6             # write the new part
        cost_out = out * PRICE_OUT / 1e6
        cost_plain += cost_out
        cost_cache += cost_out
        prev_in = this_in
        context = this_in + out               # output joins the history
    return sent, turns * out, cost_plain, cost_cache

for turns in (15, 30):
    sent, out_total, plain, cache = run(turns)
    print(f"{turns} turns: input sent {sent:,} tokens, output {out_total:,} tokens, "
          f"no cache ${plain:.4f}, with cache ${cache:.4f}")

# restart halfway: a fresh session instead of one long history (no caching in this line)
first = run(8)
fresh_short = run(7, base=1000)   # starts from a 1,000-token summary
fresh_full = run(7)               # starts again from the full 6,000-token base
one_long = run(15)
print(f"one session of 15 turns:               ${one_long[2]:.4f}")
print(f"8 turns + fresh 7 (1,000 summary):     ${first[2] + fresh_short[2]:.4f}")
print(f"8 turns + fresh 7 (full 6,000 again):  ${first[2] + fresh_full[2]:.4f}")

Python 3.14.8で実際に実行した結果です（別の短いコードでも再計算し、両者は一致しました）。

15 turns: input sent 322,500 tokens, output 7,500 tokens, no cache $0.7200, with cache $0.2212
30 turns: input sent 1,095,000 tokens, output 15,000 tokens, no cache $2.3400, with cache $0.5197
one session of 15 turns:               $0.7200
8 turns + fresh 7 (1,000 summary):     $0.4260
8 turns + fresh 7 (full 6,000 again):  $0.4960

4.3 結果の読み方#

• **入力が圧倒的です。**15ターンで送った入力は合計322,500トークン、出力は7,500トークンだけで、入力は43倍です。キャッシュなしで計算すると、合計0.72ドルのうち入力が0.645ドル（約90%）、出力は0.075ドルです。
• **費用はターン数より速く増えます。**ターン数を倍（15から30）にすると、入力は322,500から1,095,000トークンへ約3.4倍、キャッシュなしの費用は0.72ドルから2.34ドルへ約3.25倍になります。
• **キャッシュは読み直しを大きく減らします。**15ターンでは費用は0.2212ドルで、0.72ドルの約31%です。30ターンでは0.5197ドルで、2.34ドルの約22%です。ターン数とともに増えることに変わりはなく、増え方が緩やかになるだけです。
• **ちょうどよいところで新しいセッションにすると効果があります。**15ターンを、8ターンと、1,000トークンの要約から始める新しいセッションでの7ターンに分けると0.426ドルで、0.72ドルより約41%低くなります（同じくキャッシュなしの計算）。新しいセッションで最初の6,000トークンをすべて送り直す場合は0.496ドルで、約31%低くなります。

4.4 計算の限界#

これは単純化したモデルです。現実にあることを省いています。間が長く空くとキャッシュが切れること（Anthropicのドキュメントでは標準の保持期間は5分で、使うたびに更新される）、キャッシュされる最小の長さ（モデルにより512から4,096トークン）、その他の費用（ツール、検索）、そしてお使いのツールが自動でキャッシュを使うかどうか。**個別のツールについては確認していません。**実際の金額は違ってきます。意味があるのは曲線の形です。1つの履歴で多くのターンを重ねると、費用はターン数より速く上がります。

**要点：**主に動かすべきつまみは「打つ量を減らす」ことではなく、ノートを短く保ち、読み直す回数を減らすことです。

5. 予算内に収める3つの方法#

チームの昼食代を管理するイメージです。食事ごとに合う店を選び、毎回メニュー全部を頼み直さず、記録をつけます。

方法1：短く新しいセッションと、要約#

作業が終わったら、無関係な作業まで同じ会話に引きずらないでください。エージェントに、引き継ぐべきこと（決めたこと、関係するファイル、残りの作業）を要約してもらい、新しいセッションを開きます。例では、キャッシュなしの費用が約31%から41%減りました。引き継ぎ要約のテンプレートはコンテキストウィンドウの記事にあります。Gartnerも、関連する文脈だけを送り、入力を要約または削るよう開発者に教えることを勧めています。

方法2：日常作業には安いモデル#

単純で繰り返しの多い作業（名前の変更、サンプルデータの生成、整形）には、一番強いモデルが要らないことがよくあります。仮定した料金を4で割る（100万トークンあたり入力0.50ドル、出力2.50ドル）と、同じ15ターンが0.72ドルではなく0.18ドルになります。Gartnerは、単純で量の多い作業を小さいモデルへ回し、強いモデルは複雑な作業のために残すよう勧めています。ただし、下のバランスの節を思い出してください。安いモデルがターンを増やしたり間違いを残したりすれば、総費用は下がらないかもしれません。

方法3：上限と監視#

• 人やチームごとに支出の上限を決めます。GitHubの2026年4月27日の記事によると、組織はクレジットを共有でき、管理者は企業、コストセンター、ユーザーの各レベルで予算を設定できます。使い切ったときは、公開料金での追加利用を許可するか、支出を止めるかを選べます。
• 月末の請求書を待たず、毎週ツールの利用状況ページを見ます。GitHubは、2026年5月上旬から請求プレビューを利用できると述べています。
• Gartnerは、トークンのしきい値、エスカレーションの規則、自動監視を設け、トークンを多く使う作業の流れをスプリントの振り返りで見直すよう勧めています。

**要点：**3つは互いに補い合います。短いセッションはトークン量を減らし、安いモデルは1トークンあたりの価格を下げ、上限と監視は不意打ちを防ぎます。

6. このテーマが熱い理由：従量課金への移行#

6.1 Gartnerの予測（2026年6月24日）#

DevOps DigestによるGartnerのリリースの転載によると（Gartner自身のページは開いたところ403エラーでした）、Gartnerは2028年までにAIコーディングの費用が平均的な開発者の給与を上回ると予測しています。理由として挙げられているのは、トークン消費量の増加、席単位のライセンスから従量課金への移行、利用の管理不足（エージェントの自律動作、膨らんだコンテキスト）、提供元にまだ成熟したコスト最適化ツールがないことです。転載には、この比較についての割合や金額は載っていません。測定値ではなく、方向性の予測として扱ってください。

6.2 GitHub Copilotがトークン基準のクレジットへ（2026年6月1日）#

ページ要約ツールで読んだGitHubの2026年4月27日の記事によると、2026年6月1日から、Copilotの利用はGitHub AI Creditsを消費します。これは、各モデルの公開APIレートに基づき、トークン消費（入力、出力、キャッシュ済みトークン）から計算されます。月額プランには、プラン価格と同額のクレジットが含まれます（例：Pro 10ドル、Business 1ユーザー月19ドル）。コード補完と次の編集の提案はクレジットを消費しません。上限に達したときに安いモデルへ切り替わる仕組みは廃止されます。1クレジットが何ドルに当たるかはページに書かれておらず（二次情報では数字が食い違います）、その数字は使っていません。

6.3 開発者1人あたりのドル額：あくまで大まかな参考#

CloudZero、Eden AI、Exceeds AIなどのブログは、開発者1人あたり月数百ドルから、エージェントを多用する人ではそれよりずっと高い額までの範囲を挙げています。これらはコスト管理ツールを売る会社で、商業的な利害があり、手法も不明です。**その数字から結論は引き出しません。**自分のチームの実際の請求を見てください。

**要点：**方向ははっきりしていて、固定価格から使った分の支払いへです。確実な方法は、自分の利用量を測ることだけです。

7. 予算が膨らみやすい場所#

誰も見ていないところで水道の蛇口が出しっぱなしになっているイメージです。

7.1 例：ある午前、2つのやり方#

これは想定した状況で、実在の人物や製品には触れていません。数字は第4節のモデルに従います。

やり方1：1つの会話を引き延ばす

• **09:00。**開発者がエージェントに表示のバグ修正を頼み、同じ会話で続けます。
• **09:45。**最初の作業が約15ターンで終わります。開発者は「エージェントはもうプロジェクトを理解している」と考え、同じ会話で無関係な作業を頼みます。
• **11:30。**合計約30ターン。この記事の仮定では、キャッシュなしの費用は15ターンの0.72ドルではなく約2.34ドルです。

やり方2：作業を終えて新しいセッションを開く

• **09:45。**最初の作業が終わります。開発者はエージェントに、決めたことと関係するファイルを約1,000トークンで要約してもらい、2つ目の作業のために新しいセッションを開きます。
• **11:30。**2つの作業が終わり、それぞれ短い履歴の中で行われました。仮定の数字では、15ターンのセッション2つで約1.44ドル（0.72ドルの2倍）かかり、2.34ドルより約38%低くなります。これはスクリプトの結果から掛け算したもので、実測ではありません。

やること：作業の切れ目で新しいセッションを開く習慣をつけ、1日の終わりに利用状況ページを見ます。この例は何も証明しません。根拠は、提供元が文書化している課金の仕組みと、上記のGartnerの推奨にあります。

8. 答え付きの練習問題#

**やること：**第4.2節のスクリプトを実行して照らし合わせます。

1. 実行する前に予想します。キャッシュなし15ターンの費用は、0.5ドル、1ドル、2ドルのどれに近いでしょう。
2. 実行して、4つの数字を控えます。送った入力、出力、キャッシュなしの費用、キャッシュありの費用。
3. 仮定を1つだけ変えて再実行し、比べます。3つの案：NEW_INを1500から3000に変える（ツールが長いログを出す）、ターン数を15から30にする、または両方の料金を4で割る。

照らし合わせる答え（同じ仮定、Python 3.14.8）：

読み方：毎ターンの新しい内容を倍にすると費用は約50%増え、ターン数を倍にすると約3.25倍になり、4倍安いモデルにすると費用はちょうど4分の1になります（料金は掛け算の係数だからです）。手順1の予想と実際の結果を比べてください。差を見れば、自分が低く見積もりがちか高く見積もりがちか、履歴が再送されることを忘れたときにどこを見落とすかが分かります。

**実際の練習（30分）：**今使っているツールの利用状況ページを開き、今終えた作業を1つ選んで、ターン数、入力トークン、出力トークン、費用を控えます。ページに表示されない場合は、その旨を控えてください。それも1つの発見です。

9. チェックリスト：8つの質問#

1. 使っているツールはトークン課金ですか、固定価格ですか。プランに利用枠はありますか。
2. 今週の利用量を把握していますか。それとも請求書を待っているだけですか。
3. 今の会話は何ターン目で、今の作業は最初のほうのターンとまだ関係がありますか。
4. 一部だけで足りるのに、ファイル全体や長いログを送っていませんか。
5. この作業に一番強いモデルは必要ですか。安いモデルで足りませんか。
6. ツールは、エージェントの最大ステップ数や支出の上限を設定していますか。
7. キャッシュはオンですか。保持期間はどのくらいですか。
8. この作業の費用は、やり直しと間違えたときのリスクと比べてどうですか。

10. バランスの取れた見方：分かっていることと分からないこと#

**かなり確かなこと：**AIサービスは入力と出力のトークンで課金し、出力のほうが1トークンあたり高いのが普通で、過去の会話履歴は後のターンで再送され、キャッシュは読み直しの料金を下げられます（課金に関するAnthropicとGitHubのドキュメントによる）。

はっきりしないこと：

• あなたのチームの実際の費用。第4節のモデルは、仮定した料金による単純化です。
• お使いのツールがどこまで自動でキャッシュを使うか。個別のツールは確認していません。
• 今のモデルでの、ベトナム語、日本語、英語のトークン数の差。引用した研究は2023年のもので、自分で測るカウンタもありませんでした。
• Gartnerの2028年の予測は予測であり、測定値ではありません。

**誇張しないでください。**トークン単価が一番安いことは、1件の作業が終わるまでの費用が一番安いことではありません。弱いモデルはターンが増えたり間違いを残したりし、やり直しはトークンより高くつきます。品質を測らずに価格だけでモデルを選ばないでください。記事AI機能を測る：品質・費用・信頼は、品質、費用、信頼を一緒に測る方法を扱っています。

**軽く見ないでください。**費用は、毎日エージェントを使ううえでの現実の軸であり、従量課金は広がっています。チームの1ページのAI利用ポリシーに費用を入れ、記事AIの結果に証拠を求める5つの方法のように証拠を求めることも組み合わせて、節約が品質低下にならないようにしましょう。

**同僚の比較には使わないでください。**トークンの使用量は作業の種類によって変わり、個人の生産性を測るものではありません。

11. まとめ#

AIの請求額は、あなたが打つ文の数では増えず、履歴が読み直される回数とその厚さを掛け合わせた分だけ増えます。費用を手の届く範囲に収めるのは3つのことです。作業の切れ目で新しいセッションを開く、作業ごとに合った大きさのモデルを使う、上限を決めて毎週利用状況を見る。自分の数字でスクリプトを一度実行し、実際の利用状況ページと比べてみてください。

参考資料#

数字は2026年10月30日時点の公開情報によります。料金と課金のルールは変わるので、引用する前に元の情報を開いて確認してください。

• Anthropic、Prompt caching（キャッシュの書き込みと読み取りの係数、最小の長さ、標準の保持期間、料金表の例。ページ要約ツールで読みました）
• Gartner、Gartner Predicts AI Coding Costs Will Surpass Average Developer's Salary by 2028 as Token Consumption Surges（2026年6月24日。元のページは開いたところ403エラーでした）とDevOps Digestの転載（実際に読んだ情報源）
• GitHub、GitHub Copilot is moving to usage-based billing（2026年4月27日。ページ要約ツールで読みました。二次情報では1クレジットの価値が食い違うため使っていません）
• Petrov、La Malfa、Torr、Bibi、Language Model Tokenizers Introduce Unfairness Between Languages（2023年）
• 開発者1人あたりの費用の範囲は、コスト管理ツールを売る会社のブログによるもので、大まかな参考にすぎません：CloudZero、Eden AI

AIでコードを書く人、AIを日常の仕事に使う人なら誰でも、初心者の方でも読めます。統計の知識は不要です。用語にはどれも身近なたとえを添えています。計算の部分は印をつけてあるので、不要なら読み飛ばせます。

数字は公開情報から取っており、末尾に一覧があります。この記事で使うMETRの数字は、私が原典を開いて確認しました。「例」と書いたものは私が作った数字で、誰かの実測ではありません。AIの内部の仕組みはまだ誰にも完全には分かっておらず、この記事もそれには触れません。外から結果を測る方法だけを扱います。引用する2つの研究は他の人のもので、特定のツールと時期のものであり、あなたについての結論ではありません。

まず要点#

• 「AIで速くなった」という感覚と、実際に速くなることは違うことがあります。METRの2025年のランダム化試験では、経験豊富な開発者16人が実際の作業246件をこなしました。AIを使った作業は約19%長くかかりましたが、開発者は事前に24%速くなると予想し、終わった後も約20%速くなったと信じていました。
• METRの2026年初めの追跡調査（開発者57人、800件超の作業）はAIが役立つ方向に傾きましたが、METR自身が、AIなしでは働きたくないと参加を断る開発者が増えたため、増加幅については「非常に弱い証拠」だと述べています。
• 自分でも2週間で測れます。同じくらいの大きさの作業を約10件、AIを使うかどうかをランダムに割り当て、やり直しの時間も含めて測り、中央値を比べます。
• 測定を台無しにしやすいのは3つです。どの作業にAIを使うかを自分で選ぶこと、やり直しの時間を忘れること、途中で結果を見てやり方を変えることです。
• 10件では何も証明できません。感覚だけでなく、測ったヒントが手に入るということです。
• 記事にはCSVの雛形、動くPythonスクリプト、答え付きの計算例、チェックリストがあります。結果で同僚を評価しないでください。

むずかしい言葉をやさしく#

この記事を読むと説明できること#

1. 速くなった気がすることと測った速さが違うことがあるのはなぜか、そしてなぜストップウォッチが必要か。
2. 比較をおおむね公平にするために、なぜランダムに分け、やり直しの時間も足すのか。
3. なぜ10件はヒントにすぎないのか、そして自分をだまさずに結果を読む方法。

1. まずイメージ：新しいランニングシューズ#

新しいランニングシューズを買ったとします。走った後、足が軽く感じて速くなったと思います。ところが時計を見ると、今日は暑くて道も坂が多かったので、普段より2分遅かった。感覚は本物で、時計も本物ですが、測っているものが違います。

シューズが役立つかを知りたい慎重な人は、何回も走り、どの回に新しい靴を履くかをランダムに決め、毎回タイムを測って比べます。「走った時間」だけでなく「走った後に足がどれだけ痛かったか」も数えます。

AIも同じです。「タイプが減った、考えることが減った」という感覚は本物です。しかし、作業を受け取ってから本当に終わって差し戻されないまでの時間は、別の量です。この記事は、その2つ目のストップウォッチの押し方を伝えます。

ここから言えること： 何かが自分の役に立つかを知りたいなら、感覚に聞かず、小さくて公平な比較をしましょう。

2. 他の人はどう測ったか#

2.1 METRの2025年の試験#

METRは独立した研究組織です。ランダム化試験を行い、経験豊富なオープンソース開発者16人（自分のプロジェクトでの経験が平均約5年）が、大きなコードベース（平均で2万2,000スター超、100万行超）で、バグ修正、機能追加、リファクタリングなど実際の作業246件に取り組みました。各作業は「AIを使ってよい」か「使ってはいけない」にランダムに割り当てられました。AIツールは主にCursor ProとClaude 3.5・3.7 Sonnetです。期間は2025年2月から6月、1件あたり平均約2時間、開発者には1時間150ドルが支払われました。

結果：AIを使った作業は19%長くかかりました。作業の前に、開発者はAIで**24%速くなると予想していました。終わった後も、AIで約20%**速くなったと信じていました。質問された経済学と機械学習の専門家は、およそ39%と38%速くなると予想していました。

METR自身が限界も挙げています。16人だけなので一般化しにくいこと、標本の偏りがありうること（AIで大きく伸びると期待した人は応募しなかったかもしれない）、ツールを約50時間以上使った後の学習効果は排除できないこと、時間の一部は自己申告であること、慣れたコードベースの作業にしか当てはまらないことです。METRのページには現在、この結果が古くなったという注記もあります。

ここから言えること： 19%は「AIは遅くする」という意味ではありません。特定のグループ、ツール、時期の1つの実験です。学ぶ価値があるのは感覚と測定のずれです。

2.2 2026年初めの追跡調査#

2026年2月24日、METRは「We are Changing our Developer Productivity Experiment Design」を公開しました。開発者57人（前回からの10人と新規47人）、143のリポジトリ、800件超の作業でやり直したものです。記事によると、前回からの開発者は約18%速く（信頼区間は38%速いから9%遅いまで）、新規の開発者は約4%速く（15%速いから9%遅いまで）なりました。どちらの区間にも0が含まれます。

さらに重要なのは、METRがこのデータを増加幅について「非常に弱い証拠」と述べていることです。AIなしでは働きたくないと参加を断る開発者が増えたこと（速さの増加を低く見積もる方向に偏る可能性が高い）、報酬を1時間150ドルから50ドルに下げたことで選択の偏りが加わった可能性があること、開発者が複数のエージェントを同時に動かすと時間の計測が信頼できなくなったことが理由です。それでもMETRは、2025年初めに比べて開発者がAIでより速くなっている可能性が高いと考えており、実験を設計し直しています。

ここから言えること： 測ることが仕事の人たちでさえ、ツールや習慣が変われば測り方を変えます。他の人の数字は、あなた自身の数字の代わりにはなりません。

3. 2週間の実験を設計する#

台所での小さな実験を想像してください。同じ料理を2通りの方法で作り、目隠しで味見します。

3.1 8つのステップ#

1. 同じくらいの大きさの作業を約10件選ぶ。 たとえば1件30分から90分の見込み。10件は2週間の勤務に収まり、1日1件ほどです。
2. 先に予想を書く。 「AIで何%速くなると思うか」を記録します。METRも使った手順で、いちばん省かれやすい手順です。
3. 始める前に「終わり」を定義する。 たとえばテストが通る、コードを読み返した、動かしてみた。両グループで同じ定義にします。
4. ランダムに分ける。 コインを投げるか、下のスクリプトを使います。約半分の作業にAIを使い、半分は使いません。作業を見た後でグループを変えてはいけません。
5. 開始からステップ3の「終わり」まで測る。 見積もりではなく、実際の開始と終了の時刻を記録します。
6. やり直しも記録する。 差し戻されたり、抜けに気づいたりしたら、その修正時間を同じ作業に足します。
7. 途中で結果を見ない。 早く見ると、やり方を変えたり作業を選んだりしたくなります。
8. 10件そろってから分析する。 両グループの中央値を比べ、ステップ2の予想と照らし合わせます。

3.2 CSVの雛形#

1行が1作業です。minutesは自分の定義で終わるまでの時間、rework_minutesはその後の修正時間です。

task_id,arm,minutes,rework_minutes,done_checks
T1,no_ai,70,5,pass
T2,ai,35,20,pass

別の場所に、作業の説明、事前の予想、終わった後の印象（何%速い、または遅い）、気づいたことも残しましょう。印象は、数字の表を開く前に書きます。

3.3 割り当てと分析のスクリプト（Python 3、追加インストール不要）#

planコマンドが作業をランダムに分けます。analyzeコマンドは中央値、差、厳密な順列検定、95%のブートストラップ区間を計算します。

#!/usr/bin/env python3
"""Self-experiment helper: randomize which tasks use AI, then compare the times.

  python3 ai_experiment.py plan 10 [seed]    : prints a CSV with the arm of each task
  python3 ai_experiment.py analyze data.csv [--no-rework] : medians, difference, exact permutation test, bootstrap interval

Needs only the Python standard library.
"""
import csv, itertools, random, statistics, sys


def plan(n, seed=None):
    rng = random.Random(seed)
    arms = ["ai"] * (n // 2) + ["no_ai"] * (n - n // 2)
    rng.shuffle(arms)
    print("task_id,arm")
    for i, a in enumerate(arms, 1):
        print(f"T{i},{a}")


def load(path, rework=True):
    rows = list(csv.DictReader(open(path)))
    cost = lambda r: float(r["minutes"]) + (float(r["rework_minutes"]) if rework else 0)
    ai = [cost(r) for r in rows if r["arm"] == "ai"]
    no = [cost(r) for r in rows if r["arm"] == "no_ai"]
    return ai, no


def diff(a, b):
    return statistics.median(a) - statistics.median(b)


def analyze(path, rework=True, seed=1, boots=10000):
    ai, no = load(path, rework)
    obs = diff(ai, no)
    # exact permutation test: every way of choosing which tasks would have been "ai"
    pooled = ai + no
    n, k = len(pooled), len(ai)
    count = total = 0
    for idx in itertools.combinations(range(n), k):
        s = set(idx)
        a = [pooled[i] for i in s]
        b = [pooled[i] for i in range(n) if i not in s]
        total += 1
        if abs(diff(a, b)) >= abs(obs):
            count += 1
    # bootstrap interval for the difference of medians
    rng = random.Random(seed)
    ds = sorted(
        diff([rng.choice(ai) for _ in ai], [rng.choice(no) for _ in no]) for _ in range(boots)
    )
    lo, hi = ds[int(0.025 * boots)], ds[int(0.975 * boots) - 1]
    print(f"tasks with ai: {len(ai)}, without ai: {len(no)}")
    print(f"median minutes with ai:    {statistics.median(ai):.1f}")
    print(f"median minutes without ai: {statistics.median(no):.1f}")
    print(f"difference (ai - no_ai):   {obs:+.1f} min ({obs / statistics.median(no) * 100:+.0f}%)")
    print(f"exact permutation p-value: {count}/{total} = {count / total:.3f}")
    print(f"bootstrap 95% interval:    {lo:+.1f} to {hi:+.1f} min")


if __name__ == "__main__":
    cmd = sys.argv[1]
    if cmd == "plan":
        plan(int(sys.argv[2]), int(sys.argv[3]) if len(sys.argv) > 3 else None)
    elif cmd == "analyze":
        analyze(sys.argv[2], rework="--no-rework" not in sys.argv)

本番ではplanにシードを渡さないでください。そうすれば自分でも予測できません。実行した瞬間に出力を保存し、後から書き換えないでください。

4. 計算できる例（例であり、読み飛ばせます）#

これは私が作った数字による例で、誰かの実測ではありません。割り当てはシード7で実行し（例を再現できるようにするためだけです）、各作業の時間は作りました。

$ python3 ai_experiment.py plan 10 7
task_id,arm
T1,no_ai
T2,ai
T3,ai
T4,ai
T5,no_ai
T6,ai
T7,no_ai
T8,no_ai
T9,ai
T10,no_ai

2週間後のsample.csv（作った分数）は次のとおりです。

4.1 分析を2通りで実行する#

上の表でスクリプトを実際に動かした出力です。まずやり直しを含めた場合：

$ python3 ai_experiment.py analyze sample.csv
tasks with ai: 5, without ai: 5
median minutes with ai:    55.0
median minutes without ai: 60.0
difference (ai - no_ai):   -5.0 min (-8%)
exact permutation p-value: 252/252 = 1.000
bootstrap 95% interval:    -45.0 to +25.0 min

次にやり直しを忘れた場合（--no-reworkフラグ）：

$ python3 ai_experiment.py analyze sample.csv --no-rework
tasks with ai: 5, without ai: 5
median minutes with ai:    40.0
median minutes without ai: 60.0
difference (ai - no_ai):   -20.0 min (-33%)
exact permutation p-value: 48/252 = 0.190
bootstrap 95% interval:    -50.0 to +10.0 min

4.2 答えと読み方#

正直な読み方：この例では、AIがわずかに上に見えますが、10件では断言できず、最初の感覚は測定より大きい。さらに重要なのは、やり直しの時間を足し忘れると、見栄えのよい33%を信じてしまうことです。

注意：これらは作った数字です。実際の仕事では、逆の方向を含めて、まったく違う結果になることがあります。

5. 測定が崩れる場所#

時計で走りを測るのに、赤信号の後でもう一度押し忘れるようなものです。

5.1 例：ある開発者の1週間#

これは想定した場面で、実在の人物や製品には触れていません。

• 月曜 09:00。 開発者がplanを実行します。最初の作業はAIのグループに入りました。予想を書きます：30%速い。
• 09:05。 タイマーを始め、AIにデータ整形の関数を書かせます。
• 10:20。 AIが完了と言い、テストも通ります。開発者は時計を止めます：75分。
• 10:45。 読み返すと、日付が空のケースが抜けていました。修正にさらに25分。飛ばさず、やり直しの列に書きます。
• 金曜 17:30。 いくつかよい数字がすでに見えていても、来週の終わりまで合計を見ないと自分に約束します。
• 翌週の金曜 16:00。 10件がそろいました。分析を実行し、予想と照らし合わせ、結論を書きます：パターンがはっきりした作業ではAIがわずかに上、業務の理解が要る作業では上ではない。

やること：「ほぼ終わり」と感じても、やり直しの時間は同じ作業に足します。これは例なので何も証明しません。証拠は研究にあり、上のMETRの試験は、感覚と測定が違うことがある一例です。

6. 使った数字と資料#

正しく読むために： これらの資料は、感覚と測定がずれることがあること、AIの生産性を測るのは難しいことを示します。AIがあなたにとって遅いか速いかは示していません。

7. チェックリスト：自分の数字を信じる前の8つの質問#

1. 始める前に予想を書いた？
2. どの作業にAIを使うかはコインかスクリプトで決め、保存した？
3. 作業は同じくらいの大きさ？
4. 「終わり」は両グループで同じ定義？
5. すべてのやり直しの時間を正しい作業に足した？
6. 途中で結果を見て、やり方を変えていない？
7. 区間はどれくらい広く、それ以上の結論を出していない？
8. 結果は自分の習慣の調整だけに使い、誰かの評価には使わない？

8. バランスよく見る：測れること、測れないこと#

測れること： どの作業でAIが役立ちそうか、どれで役立たなさそうかのヒントと、感覚と測定のずれ。

測れないこと：

• 10件では何も証明できません。区間は広く、個々の作業の難しさが結果を歪めます。
• 時間がすべてではありません。AIは学びを助けたり、疲れを減らしたり、難しい仕事を引き受ける気にさせたりしますが、ストップウォッチには映りません。また、速いことは、提出したコードを理解していることを意味しません。知らないライブラリをAIと学んで腕を落とさないを参照してください。
• 今日の結果は、3か月後のツールには当てはまらないかもしれません。
• 結果で同僚を評価しないでください。標本は小さく、人によって仕事が違い、1つの数字は悪用されやすいからです。チームにどんな指標でも出す前に、生産性をコードの行数で測らないを読んでください。
• 新人エンジニアに関する数字を慎重に読みたい場合は、新人エンジニアの仕事、数字が食い違うとき、どれを信じるかを参照してください。

誇張しないこと： 個人の実験は厳密な科学ではありません。軽く見ないこと： それでも感覚を信じるだけよりよく、費用は2週間の時間記録だけです。AIが渡した結果の質を確かめたい場合は、AIの結果に自分で証明させるも読んでください。

9. 結論#

速くなった気がするのは感覚です。作業を受け取ってから本当に終わって差し戻されないまでの時間は、測定値です。この2つはずれることがあり、METRの試験は特定のグループでそれを示しました。小さな実験をしましょう。10件、ランダムに割り当て、やり直しも含めて時間を測り、中央値を比べ、結果はその確かさのとおりに読みます。

参考資料#

数字は2026年10月時点の公開情報です。METRのページとarXivの論文は私が開いて、METRの数字を照合しました。引用する前に、原典を開いて確認してください。

• METR、Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity（arXiv 2507.09089）とMETRのブログ記事、2025年7月10日
• METR、We are Changing our Developer Productivity Experiment Design（2026年2月24日）
• Python Software Foundation、statisticsとitertoolsモジュールのドキュメント（中央値と組み合わせのため）

プログラミングを学び始めた人、プロダクトを作る人、遅いWebページをAIに直してもらいたいけれど原因がどこか分からない人のための記事です。ネットワークの知識は要りません。むずかしい言葉にはどれも身近なたとえを添え、計算の部分は印をつけてあるので、不要なら読み飛ばせます。

数字と定義は公開されている文書から取っており、末尾に一覧があります。「例」や「模擬」と書いたものは作った例で、実在の人物や会社には触れていません。実際のシステムにはこの記事より多くの細部があるので、以下のたとえは覚えやすくするための補助にすぎません。

**最初にできなかったことを書きます。**私がこの記事を書いた環境は、ローカルのネットワークポートを開くことと、外部へのhttpsアクセスを禁止していました。そのため、どのサーバーに対してもcurlを実際に動かせていません。「実際に動かした例」の節は、私が書いて実際に実行した模擬ですが、遅延は私が決めた値で、ネットワークから測ったものではありません。記事中のcurlコマンドには「ここでは未実行」と明記しました。実際の数字は、ご自身のマシンで動かして確かめてください。

まず要点#

• ページを開くと、リクエストは住所の検索、接続、暗号化の握手、リクエストの送信、アプリの処理、データベースの応答、返信という複数の区間を通ります。どの区間も、それぞれ単独で遅くなったり失敗したりします。
• どこが遅いかは、推測せずに測ります。curlの-wオプションで時間の目印を出せます。
• curlの目印は開始からの累計です。1つの区間の時間は、その目印から直前の目印を引いて求めます。
• この記事の模擬では、合計が近い2つのケース（0.973秒と1.383秒）でも犯人がまったく違いました。一方はデータベース待ち（約83%）、もう一方はDNSの検索（約87%）です。
• 200は、プロトコルの上でリクエストが成功したことしか示しません。内容が正しいとは言っていません。
• 遅いページをAIに直してもらうときは、先に測って、数字をAIに渡します。AIが書いたコードは、目に見えにくい小さなクエリをたくさん隠すことがありますが、その頻度を測った研究は見つかりませんでした。

この記事を読むと説明できるようになること#

1. Webリクエストにはどんな区間があり、なぜ区間ごとに遅くなったり失敗したりするのか。
2. なぜcurlの時間の目印は引き算が必要で、各区間をどう計算するのか。
3. AIに直してもらう前に、問題がネットワーク、アプリ、データベースのどこにあるかを絞り込む方法。

むずかしい言葉をやさしく#

1. まずイメージ：荷物を送る#

別の街の店に注文するところを思い浮かべてください。荷物が届くまでに、7つのことが起きます。

1. 店の住所を電話帳で調べます（DNS）。
2. 注文があると電話で知らせ、相手が出るのを待ちます（TCP接続）。
3. 両者で鍵つきの箱を使うと決めます（TLS）。
4. 何がほしいかを書いた注文書を送ります（HTTPリクエスト）。
5. 受付が注文書を受け取って処理します（サーバー上のアプリ）。
6. 受付が倉庫へ行き、商品を探します（データベース）。
7. 商品と書類が戻ってきます（返信）。

荷物が遅れても、古い電話帳か、話し中の回線か、受付か、倉庫か、すぐには分かりません。一番信頼できるのは、1つずつ時間を測る人です。コンピューターも同じです。

MDNは、道のたとえでもっと短く説明しています。あなたの端末は家、サーバーは店、DNSは住所録、HTTPは注文に使う言葉です。MDNが挙げる段階はDNSの検索、リクエスト、レスポンス、組み立ての4つです。この記事は、測れる場所が見えるようにもう少し細かく分けています。

ここから言えること：「ページが遅い」は1つの故障ではありません。7つの区間の合計で、たいてい1つの区間が時間の大半を占めます。

2. 7つの区間を1つずつ#

下の表は簡略化した地図です。右端の列は、各区間がどう失敗しやすいかを示すので、エラーメッセージで見分けられます。

2.1 区間1：DNS、電話帳#

**たとえるなら：**店の番号を案内に聞く電話です。名前は分かっていますが、番号は分かりません。

コンピューター同士は数字の住所で話します。ブラウザはDNSサーバーに聞いて、「example.com」を数字の住所に変えます。結果はたいていしばらく**覚えておかれる（キャッシュ）**ので、次回は速くなります。最初の測定がその後より遅くなりやすいのはこのためです。

2.2 区間2と3：接続と暗号化の握手#

**たとえるなら：**電話で知らせてから、両者で鍵つきの箱を使うと決めることです。

MDNによると、HTTPはTCPの上で動き、たいていTLSで暗号化されます。HTTPには信頼できる通り道が必要なので、まず接続を開きます。httpsの住所では、鍵を決めるTLSの握手が加わります。古いHTTP/1.0はリクエストと返信ごとに新しい接続を開きましたが、その後のバージョンは接続を再利用するので、同じサーバーへの2回目のリクエストは区間1から3を省けることが多くなります。

2.3 区間4：HTTPリクエストを送る#

**たとえるなら：**注文書です。品物の名前（パス）、注文の方法（メソッド）、いくつかのメモ（ヘッダー）が書かれています。

MDNは、リクエストを、メソッド（取得ならGET、送るならPOST）、リソースのパス、HTTPのバージョン、任意のヘッダー、場合によっては本文からなるものと説明しています。MDNの形に倣った例です。

GET / HTTP/1.1
Host: developer.mozilla.org
Accept-Language: fr

返信には、バージョン、短い説明つきのステータスコード、ヘッダー、場合によっては本文（ページの内容）があります。

HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 29769

MDNによるステータスコードの5つの分類です。1xxは情報、2xxは成功、3xxは転送、4xxはリクエストを送った側の問題、5xxはサーバー側の問題です。よく見るコードは、200が成功、301が別の住所へ恒久的に移動、304が変更なしなので保存済みのコピーを使う、404が見つからない、500がサーバーの一般的なエラー、503が一時的に応答できない、です。

2.4 区間5と6：アプリとデータベース#

**たとえるなら：**受付が書類を読み、倉庫へ行きます。倉庫へ行くたびに、往復の時間がかかります。

動的なページでは、時間がこの2つの区間に集まりやすくなります。アプリがあなたのコードを実行し、データが必要ならデータベースに聞きます。聞くたびに1往復で、データベースが別のマシンにあるときは特に長くなります。小さく100回聞くのは、大きく1回聞くより遅くなりがちです。100回分の往復代がかかるからです。節4.1に計算できる例があります。

2.5 区間7：返信が戻る#

内容が大きいほど時間がかかります。圧縮されていなければなおさらです。文字のページでは、たいてい一番短い区間ですが、大きな画像やダウンロードでは長くなることがあります。

**ここから言えること：**区間ごとに「失敗の特徴」があります。エラーメッセージは手がかりなので、AIに推測させる前によく読みましょう。

3. curlで区間ごとに測る#

**たとえるなら：**荷物の通り道の関所ごとに、ストップウォッチを置くことです。

curlは、HTTPリクエストを送るコマンドラインのツールです。この記事で大切なオプションは2つです。

• -v（verbose、おしゃべり）：全過程を表示します。curlの文書によると、*で始まる行はcurl自身の情報（名前の検索、接続）、>で始まる行はcurlが送ったもの、<で始まる行はcurlが受け取ったものです。
• **-w（write-out、終了後に数値を出す）：**決めた書式で計測値を出します。

知っておく5つの目印です。libcurlの文書によると、すべて秒単位で、すべて開始から数えます。

コマンドの例です（ここでは未実行です。私の環境が外部へのhttpsを禁止しているためで、ご自身のマシンで動かしてください）。

curl -s -o /dev/null -w 'dns=%{time_namelookup} tcp=%{time_connect} tls=%{time_appconnect} first_byte=%{time_starttransfer} total=%{time_total} code=%{http_code}\n' https://example.com/

この形のコマンドをcurl 8.7.1で実行したところ、変数名は受け付けられましたが、接続が遮断されたのでステータスコードは000になり、数字には意味がありません。使っていません。

3.1 引き算の式#

目印は累計なので、各区間の時間は次のとおりです。

DNS             = time_namelookup
TCP接続         = time_connect       - time_namelookup
TLSの握手       = time_appconnect    - time_connect
サーバーの待ち  = time_starttransfer - time_appconnect
ダウンロード    = time_total         - time_starttransfer

http（TLSなし）の住所では、TLSの行を省き、「サーバーの待ち」の行でtime_appconnectの代わりにtime_connectを使います（近似です）。

大事な限界：「サーバーの待ち」の間には、アプリ（区間5）とデータベース（区間6）の両方が含まれます。curlはこの2つを分けられません。分けるにはクエリのログか専用の監視ツールが必要です。

4. 実際に動かした例：7つの区間の模擬（計算は読み飛ばせます）#

これは、私がPython 3.14.8で書き、自分の環境で実際に動かした模擬です。各区間は、私が先に決めた待ち時間です。プログラムはcurlと同じ形で累計の目印を出し、引き算で各区間を計算します。遅延は私が選んだ値で、ネットワークから測ったものではありません。確かめているのは、引き算が決めた値どおりに返るかどうかです。

ケースA：データベースが遅い（DNS 0.040秒、接続0.030、TLS 0.060、サーバーの待ち0.800、ダウンロード0.020）。ケースB：DNSが遅い（DNS 1.200、接続0.030、TLS 0.060、サーバーの待ち0.050、ダウンロード0.020）。

実行の実際の出力です。

A: slow database
  time_namelookup      0.045   leg =  0.045
  time_connect         0.080   leg =  0.035
  time_appconnect      0.144   leg =  0.064
  time_starttransfer   0.949   leg =  0.805
  time_total           0.973   leg =  0.024
  longest leg: time_starttransfer (0.805 s)
B: slow DNS, fast database
  time_namelookup      1.205   leg =  1.205
  time_connect         1.240   leg =  0.035
  time_appconnect      1.305   leg =  0.065
  time_starttransfer   1.360   leg =  0.055
  time_total           1.383   leg =  0.023
  longest leg: time_namelookup (1.205 s)

結果の読み方です。

• ケースA：サーバーの待ちの区間は、合計0.973秒のうち0.805秒で、約83%です。0.805が決めた0.800よりわずかに大きいのは、実際の待機が必ず数ミリ秒余分にかかるためです。
• ケースB：DNSの区間は、合計1.383秒のうち1.205秒で、約87%です。2つのケースの合計は近い（1.4秒未満）のに、直すべき場所はまったく違います。
• time_totalだけを見ていると、2つのケースは区別できません。ケースBでデータベースを直しても効果はありません。

はっきりさせておくと、これは私が遅延を決めた模擬です。証明しているのは計算の方法であり、本物のネットワークの姿ではありません。あなたのマシンの数字は違います。

4.1 余計なクエリ：数えたのは本物、時間は仮定#

2つ目の例も、PythonとメモリのSQLite 3.53.4で実際に動かしました。顧客が50人、注文が200件あります。方法1：顧客の一覧を取り、顧客ごとに別のクエリを出す。方法2：結合（join）と集計を使った1つのクエリ。

same answer: True
queries, one per row: 51
queries, one join   : 1
waiting for the database at 5 ms per query: 255 ms vs 5 ms

どちらも同じ答えですが、片方は51クエリ、もう片方は1クエリです。数えた値は本物です。1往復5ミリ秒は、別のマシンにあるデータベースを想定した私の仮定です（メモリ上のSQLiteはネットワーク遅延がほぼありません）。その仮定では、51クエリの待ちは255ミリ秒、1クエリは5ミリ秒です。このパターンはN+1（一覧を取る1回のクエリと、行ごとのN回のクエリ）と呼ばれます。

ここから言えること：「サーバーの待ち」が長いとき、最初の問いは「どのクエリが遅いか」ではなく、「このページはクエリを何回出しているか」です。

5. 答え付きの演習#

この演習は、自分のマシンで動く偽のサーバーを使います。私はこのサーバーを動かせていません。私の環境がネットワークポートを開くことを禁止していたためです（ポートを開くコマンドは「Operation not permitted」と報告しました）。確認できたのはコードがコンパイルできることだけです。下の答えは、私のコードの書き方から導いたものなので、実際に動かして答えと比べてください。

5.1 偽のサーバー#

slow_app.pyとして保存します。

import time
from http.server import BaseHTTPRequestHandler, HTTPServer

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == "/slow":
            time.sleep(0.8)          # 遅いクエリを模擬する
            body = b"orders: 3\n"
        elif self.path == "/missing":
            self.send_response(404)
            self.send_header("Content-Length", "0")
            self.end_headers()
            return
        else:
            body = b"hello\n"
        self.send_response(200)
        self.send_header("Content-Type", "text/plain")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)
    def log_message(self, *a):
        pass

HTTPServer(("127.0.0.1", 8765), Handler).serve_forever()

1つ目のターミナルでpython3 slow_app.pyを動かし、別のウィンドウで以下のコマンドを使います。

5.2 演習1：遅い区間を見つける#

curl -s -o /dev/null -w 'tcp=%{time_connect} first_byte=%{time_starttransfer} total=%{time_total} code=%{http_code}\n' http://127.0.0.1:8765/slow
curl -s -o /dev/null -w 'tcp=%{time_connect} first_byte=%{time_starttransfer} total=%{time_total} code=%{http_code}\n' http://127.0.0.1:8765/

問い：それぞれのコマンドで、ほぼすべての時間を占める区間はどれですか。引き算で求めてください。

答え（コードから導いたものなので、自分の数字と比べてください）：1つ目のコマンドでは、first_byteからtcpを引いた値が約0.8秒（数ミリ秒の誤差つき）になります。コードが返信の前に0.8秒待つからです。残りは、両端が同じマシンなのでほぼゼロです。2つ目のコマンドは待ちがないので、どの数字もとても小さくなります。住所はhttpでTLSがないので、time_appconnectの代わりにtime_connectを使います。

5.3 演習2：404と時間#

curl -s -o /dev/null -w 'code=%{http_code} total=%{time_total}\n' http://127.0.0.1:8765/missing

答え：code=404で、時間はとても小さくなります。教訓：エラーの返信でも速いことがあります。時間が短いことは、正しいことを意味しません。

5.4 演習3：1回の測定では足りない#

演習1のコマンド（/slowのパス）を5回動かし、first_byteの値を書き留めます。小さい順に並べたときの真ん中の値（中央値）を取ります。

**答え：**数字は0.8秒に近くなりますが、数ミリ秒ずつずれます。本物のネットワークではずれがずっと大きいので、1回の測定で結論を出さないでください。

5.5 httpsでも試す（ここでは未実行）#

curl -v https://example.com/ -o /dev/null
curl -s -o /dev/null -w 'dns=%{time_namelookup} tcp=%{time_connect} tls=%{time_appconnect} first_byte=%{time_starttransfer} total=%{time_total}\n' https://example.com/

-vのコマンドでは、*の行（接続と握手）、>の行（curlが送った注文書）、<の行（返信書）を探します。-wのコマンドでは、節3.1の式を当てはめます。最初の実行はDNSが遅くなりやすく、2回目はキャッシュのおかげで速くなりやすくなります。

6. 取り違えやすいところ#

荷物の確認にたとえると、遅れて届いたと知るだけでは足りず、どの関所で遅れたかを知る必要があります。

7. 例：遅いレポートページと過ごす朝#

これは想定の例で、実在の人物や製品には触れていません。名前、数、時刻は作ったものです。

• **09:30。**ユーザーが、レポートのページが表示されるまで約3秒かかると報告します。
• **09:40。**開発者がエージェントに頼みます。「クエリを速くして。」エージェントはインデックスを1つ追加し、「最適化しました」と報告します。
• **10:05。**ページはまだ遅いままです。開発者が-wつきでcurlを動かすと、tcp=0.02、first_byte=3.05、total=3.08でした。サーバーの待ちがほぼ3秒を占めます。DNS、接続、ダウンロードは無視できる大きさです。
• 10:15。開発者がクエリのログをつけると、1回のページ読み込みで601クエリ（一覧の1クエリと、行ごとの600クエリ）が出ています。データベースが別のマシンにあるので、各クエリの待ちは約5ミリ秒です。計算は、601かける5ミリ秒で3,005ミリ秒となり、約3秒と合います。
• **10:50。**開発者はエージェントに、結合を使った1つのクエリにまとめ、前後のクエリ数を表示するよう頼みます。first_byteは約0.1秒まで下がります（この例の仮定の数字です）。

取るべき行動：先に測り、その数字をAIに渡します。「速くして」とだけ言うと、AIは違う場所を直し、たとえば犯人でないクエリにインデックスを足して、それでも完了と報告することがあります。記事AIの結果に証拠を添えさせるのように証拠を求めましょう。直す前後のクエリ数とfirst_byteです。

この例は頻度については何も証明しません。証拠は別にあります。節4.1で、同じ答えに対して51クエリと1クエリを実際に数えました。AIが書いたコードがN+1を起こしやすいかどうかは、直接測った研究を見つけられませんでした。2025年の研究（Unveiling Inefficiencies in LLM-Generated Code）は、3つのオープンソースモデルがHumanEval+で書いた492個の小さなコードを分析し、ロジックと性能の問題が一般的な非効率に含まれると報告していますが、これは小さなアルゴリズム課題で、データベースを使うWebアプリではありません。N+1は起こりうるリスクとして扱い、自分で測ってください。確実とは考えないでください。AIが書いたコードのセキュリティについては、AIを使うアプリのOWASP Top 10も参照してください。

8. 使った数字と文書#

正しく読むために：これらの文書は、区間への分け方と計算の方法を支持します。私は本物のネットワークでは測っておらず、AIが書いたコードのN+1を測った研究も見つけられませんでした。

9. チェックリスト：ページが遅いときの8つの質問#

1. 数字で測ったか、それとも推測しているか。
2. 目印を取って引き算したか、それともtime_totalを使っているか。
3. どの区間が一番大きいか。DNS、接続、TLS、サーバーの待ち、ダウンロードのどれか。
4. これは最初の実行か、後の実行（キャッシュあり）か。何回も測ったか。
5. ステータスコードは何で、返ってきた内容は正しいか。
6. 「サーバーの待ち」が長いなら、このページはクエリを何回出しているか。
7. AIに直してもらうとき、測定値を渡し、直した後の測定値も求めたか。
8. どこから測ったか。ユーザーも似た場所にいるか。

10. バランスよく見る：この地図が簡略化していること#

**できること：**問題を分ける方法、測るための式、AIに頼む前に確かめる習慣を与えます。

できないこと：

• これは、TLSつきのTCPの上のHTTP/1.1を簡略化した地図です。実際にはCDN（コンテンツ配信ネットワーク）、プロキシ、ロードバランサーもあります。それぞれが区間を1つ足したり、減らしたりします。
• HTTP/3は、RFC 9114によると、UDPの上に作られたQUICというプロトコルの上で動き、接続の部分と暗号化の握手を一体にします。私が読んだ二次的な情報源によると、これは接続を開くときの往復回数を減らします。その場合、time_connectとtime_appconnectは、節3の表ほどきれいに分かれないことがあります。正確さが必要なら、RFC本文を読んでください。
• curlは1つの場所から、1回だけ測ります。1回の測定はノイズです。専用の監視ツール（APM）は、アプリとデータベースを分けるなど、より多くを見られます。
• 節4の模擬は計算を説明するだけで、節5の演習は私が実際には動かしていません。

**大げさに言わない：**7つの区間を知っても、インフラの専門家にはなれませんが、正しい問いを立てるには十分です。**軽く見ない：**違う場所を直しても時間はかかりますし、それでも誰かが「完了しました」と報告します。

11. 結論#

「ページが遅い」は、いくつかの区間の合計で、たいてい1つの区間がほとんどを占めます。curl -wで測り、隣り合う目印を引き算して、一番大きい区間を見ましょう。それがサーバーの待ちなら、推測する前にクエリを数えます。そしてAIに直してもらうときは、測定値を渡し、直した後の測定値も求め、その数字を自分の手で開いて確かめてください。

参考資料#

定義は2026年10月時点の公開文書によります。HTTP/3の部分は二次的な情報源に基づくので、引用する前に原文を開いて確認してください。

• MDN、How the web works
• MDN、HTTPの概要とHTTPレスポンスのステータスコード
• curl、CURLINFO_STARTTRANSFER_TIMEとCURLINFO_APPCONNECT_TIME
• Everything curl、Verboseとcurlのマニュアル（このページの-wの部分は読めておらず、変数名はcurl 8.7.1を動かして確認しました）
• IETF、RFC 9114（HTTP/3）とRFC 9000（QUIC）
• Unveiling Inefficiencies in LLM-Generated Code: Toward a Comprehensive Taxonomy、arXiv 2503.06327（2025年）

コードを書く人、読む人なら誰でも、初心者の方でも読めます。高度なGitの知識もデバッグの経験も要りません。用語にはどれも身近なたとえを添えています。計算の部分は印をつけてあるので、不要なら読み飛ばせます。

記事のコマンドと出力は、練習用リポジトリでの実際の実行結果です（Git 2.56.0、Python 3.14.8）。同じものを作れるスクリプトも載せています。コミットのハッシュは時刻に依存するため、あなたの環境では違う値になります。腕のよい人がどうデバッグしているかについて、決まった理論はまだありません。以下の5つのステップは実践の整理であり、対照実験で検証された手順ではありません。「例」と書いたものは作った例で、実在の人物や会社には触れていません。

まず要点#

• デバッグは独立した技術で、AIがあっても不要にはなりません。バグの場所を知らないままAIに聞くと、答えを判断する根拠がなくなります。
• 5つのステップ：バグを確実に再現する、失敗するケースを縮小する、間違いうる仮説を1つ立てる、疑わしい範囲を半分ずつに絞る、直してテストを足して再発を防ぐ。
• 半分に絞る作業にはGit標準のgit bisectがあります。この記事の実際の例では、疑わしい19コミットの中から原因を見つけるのに4回の確認で済みました。1つずつ見ると最大19回です。
• 例の原因は「refactor: simplify discount check」という、一見無害なコミットでした。バグはたった1文字、>=が>になったことです。
• 5つのステップのあとで、AIに短いバグ報告を渡します（テンプレートは末尾）。そうするとAIの助けは速くなり、説明も確認できます。
• 限界：毎回同じ結果を返すテストが必要です。タイミング、データ、環境に左右されるバグはずっと難しくなります。

むずかしい言葉をやさしく#

この記事を読むと説明できること#

1. バグは直す前に再現して縮小する必要があること、そして「間違いうる」仮説とはどういうものか。
2. git bisectが半分ずつに絞って原因のコミットを見つける仕組みと、19コミットなら約5回の確認で済む理由。
3. AIに渡す良いバグ報告に何を入れるか、そしてなぜ自分で範囲を絞ったあとに渡すのか。

1. まずイメージ：現場に着いた探偵#

探偵が現場に着いたところを思い浮かべてください。最初に怪しい人を見つけても、すぐには逮捕しません。現場をそのままにして、何が起きたかを書き留め、関係のない細部を捨てて核心を見やすくし、具体的な仮説を立てます。「犯人が裏口から入ったなら、台所の床に泥がついているはず」。そして、まさにそれを確かめに行きます。違っていたら仮説を捨てて別のものを試します。最後には、他の人も確認できる証拠が残ります。

デバッグも同じです。5つのステップは、それぞれ探偵の仕事に対応します。

教訓： 優れた探偵は最初に当てる人ではなく、違う可能性を順に消す方法を持っている人です。

2. AIがあるのに、なぜまだ学ぶのか#

2.1 この技術がまだ重視されていることを示す調査#

BairesDevのDev Barometer Q2 2026（77か国の開発者1,569人、うち初級1,059人、上級510人、2026年6月公表）では、初級開発者の48%が、採用で最も重要なのは問題解決力と分析的思考だと答えました。AIツールを使いこなす力を挙げたのは18%で、およそ3倍の差です。同じ調査で、初級者が提出するAI生成コードを十分理解していると答えた上級開発者は16%でした。

注意が3つあります。第一に、BairesDevはこのテーマに商業的な利害のあるソフトウェア開発の外注会社です。第二に、元のページを開こうとしたところアクセスを拒否されたため、数字は同社のプレスリリースとデータ資料を引用した検索結果から読んだもので、元の表は確認していません。第三に、16%は上級者による初級者への評価で、理解度そのものの測定ではありません。確かな証拠ではなくシグナルとして読んでください。

2.2 先にAIに聞くと、判断力を失いかねない理由#

壊れているファイルをそのままAIに貼って、修正案が返ってきたとします。バグの場所を知らなければ、選べるのは信じるか信じないかだけです。スタンフォード大学の研究（Perryら、2022年、参加者47人）では、AIアシスタントを使ったグループは5問中4問でより安全でないコードを書いたのに、自分のコードは安全だとより強く信じていました。古いモデルと小さなグループでの結果ですが、確信していることと正しいことは別だという、気にかける価値のあるリスクを示しています。

教訓： AIを使うのは良いことです。ただ、AIの答えを照らし合わせる材料を持てるように、先に自分で疑わしい範囲を絞っておきましょう。

3. 5つのステップと、実際に動かした例#

例は小さな買い物かごのプログラムです。ルールは、100以上の注文は10%割引。テストは、合計がちょうど100の注文に割引がつかないという失敗を報告します。リポジトリは20コミットで、ルールを壊すコミットはちょうど1つです。作るスクリプトは第5章にあります。

ステップ1. 再現：1つのコマンドで、毎回同じ結果#

イメージ： 現場をそのまま保つ。

最初の仕事は直すことではなく、毎回バグを起こす1つのコマンドを持つことです。

python3 test_cart.py
echo "exit=$?"

FAIL total([(50, 2)]) = 100.0, want 90.0
exit=1

この2行が現場です。50の商品2つ（合計100）は90.0になるはずなのに、プログラムは100.0を返しました。終了コードは1、つまり「不合格」です。2回動かして結果が違うなら、まだ再現できていません。それを先に解決します（限界の章を参照）。

ステップ2. 縮小：関係のないものを外す#

イメージ： 関係者だけが残るまで、部屋から人を出していく。

失敗するケースの一部を1つずつ外して、「バグはまだあるか」を確かめます。大きなかごから最小のケースまで、実際に動かした結果です。

行の数も、商品の数も、各価格も関係ありませんでした。残ったのは割引前の合計がちょうど100ということです。最小の失敗ケースは1行になりました：total([(100, 1)])。

ステップ3. 間違いうる仮説を1つ立て、先に結果を予想する#

イメージ：「犯人が裏口から入ったなら、台所の床に泥がついているはず」。

ステップ2から立てる仮説は、割引の関数がちょうど100の境界を誤って扱っているです。良い仮説は予想を立てさせてくれます。正しいなら、100未満は割引なし、ちょうど100は割引されるべきなのにされない、100超は割引される、となるはずです。それから実行します。

discount(99.99)   # 0.0
discount(100)     # 0.0 （本来は10.0のはず）
discount(100.01)  # 10.0

予想どおりで、割引は100からではなく100を超えてから始まっていました。仮説は成り立ち、「以上」であるべき「より大きい」を探せばよいと分かります。どんな結果でも「合っている」と言える仮説は役に立ちません。ここでdiscount(100) = 10.0が返っていたら、この仮説は捨てなければなりません。

もう直し方が見えているかもしれません。でも実際のプロジェクトでは、その関数は多くの人が触っているかもしれず、「どこが壊れているか」と同じくらい「どの変更が壊したか」が大事です。それがステップ4です。

ステップ4. 半分に絞る：確認のたびに疑わしい範囲を半分にする#

イメージ： 1から100の数当て。「1ですか、2ですか」とは聞かず、「50より大きい？」と聞きます。1つの質問で半分が消えます。

履歴は20コミットです。最初のコミットは動き、最新は壊れています。疑わしいのは19コミットです。git bisectは真ん中のコミットを選んで切り替え、確認のたびに半分を捨てます。実際の実行はこうです。

git bisect start HEAD $(git rev-list --max-parents=0 HEAD)

status: waiting for both 'good' and 'bad' commits
status: waiting for 'good' commit(s), 'bad' commit known
Bisecting: 9 revisions left to test after this (roughly 3 steps)
[5f01574] feat: add free shipping limit

Gitが真ん中のコミットを選び、そこへ移動してくれました。テストを実行してgit bisect goodかgit bisect badで印をつけます。git bisect runなら、Gitが毎回テストを実行し、終了コードで判断します（Gitのドキュメントでは、0が正常、125を除く1から127が異常）。

git bisect run python3 test_cart.py

running 'python3' 'test_cart.py'
Bisecting: 4 revisions left to test after this (roughly 2 steps)
[f1da7cd] feat: add min order note
running 'python3' 'test_cart.py'
FAIL total([(50, 2)]) = 100.0, want 90.0
Bisecting: 2 revisions left to test after this (roughly 1 step)
[2004cf0] feat: add coupon placeholder
running 'python3' 'test_cart.py'
FAIL total([(50, 2)]) = 100.0, want 90.0
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[6b693ef] refactor: simplify discount check
running 'python3' 'test_cart.py'
FAIL total([(50, 2)]) = 100.0, want 90.0
6b693ef is the first 'bad' commit
commit 6b693ef

    refactor: simplify discount check

 cart.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
bisect found first 'bad' commit

このセッションの確認は4回でした。真ん中のコミット（合格）、続いて3つとも不合格、最後に1つだけ残りました。原因はrefactor: simplify discount checkです。その変更を見てみましょう。

git diff 6b693ef~1 6b693ef

-    if total >= 100:
+    if total > 100:

たった1文字です。コミット名は「整理」と言っていますが、実際には動作を変えていました。コミット名と中身がずれることがあるので、名前を読むのではなくテストでコミットを探すのがよい理由でもあります。

最後にgit bisect resetでセッションを終え、元のブランチに戻るのを忘れないでください。

半分に絞る方法はGitの外でも使える#

「半分を捨てる」という考え方はどこでも使えます。長い関数の半分を一時的に無効にしてバグが残るか見る、処理の途中で値を出力して壊れるのがその前か後かを知る、機能フラグの半分を切る、などです。1行ずつ眺めるより、ずっと早く近づけます。

ステップ5. 直して、確認して、再発を防ぐ#

イメージ： 事件が再び開かないよう記録を残す。

1文字直して（>を>=に戻して）、テストを実行します。

python3 test_cart.py
echo "exit=$?"

exit=0

合格です。隣り合う境界も確認すると、実際の結果は次のとおりでした。

total([(99.99, 1)])   # 99.99  （割引なし）
total([(100, 1)])     # 90.0   （10%割引）
total([(100.01, 1)])  # 90.01  （10%割引）

このテストはリポジトリにもともとありました（ちょうど100の注文を確認します）。だから、誰かがまた壊してもこのバグは捕まえられます。なければテストを足すのがこのステップです。バグは1つずつ、自分用のテストを残すべきです。テストの書き方は記事「AIが書いたコードのテスト」にあります。

教訓： 5つのステップで、「プログラムが間違っている」から「特定のコミットの1文字」まで、各段階に証拠を持って進めました。あとは直すだけです。

4. 自分で確かめる計算：半分に絞るのはどれだけ速いか（読み飛ばしてもOK）#

疑わしいコミットがN個のとき、半分に絞る確認は最大でおよそlog2(N)回（切り上げ）です。実際に計算した結果です。

import math
for n in (19, 99, 999, 9999):
    print(n, math.ceil(math.log2(n)), round(math.log2(n), 2))

実際の実行でGitが必要としたのは5回ではなく4回でした。5は最大値で、実際の回数はバグの位置によります。いちばん古いコミットから1つずつ見ていくと、11番目のコミット（原因）に届くまでに10回、最大では19回かかります。なお、これらの数字は、毎回の確認が信頼でき、すべてのコミットが動くことを前提にしています。ビルドできないコミットがあれば、コード125で飛ばせますが、確認が増えます。

5. 練習問題：自分でやってみる（答えつき）#

次のスクリプトをmake_repo.shとして保存し、bash make_repo.shで実行してください。cart-demoというフォルダに20コミットを作ります。そのうち割引ルールを壊すコミットはちょうど1つです。

#!/usr/bin/env bash
# 20コミットの練習用リポジトリを作る。そのうち1コミットだけが割引ルールを壊す。
set -e
rm -rf cart-demo
mkdir cart-demo
cd cart-demo
git init -q -b main
git config user.name "debug-demo"
git config user.email "demo@example.com"

c() { cat >> "$2"; git add -A; git commit -q -m "$1"; }   # c "メッセージ" ファイル < 内容

cat > test_cart.py <<'EOF'
import sys
from cart import total

checks = [
    ([(10, 3)], 30.0),     # 100未満：割引なし
    ([(50, 2)], 90.0),     # ちょうど100：10%割引
    ([(60, 2)], 108.0),    # 100超：10%割引
]
bad = [(i, want, total(i)) for i, want in checks if total(i) != want]
for i, want, got in bad:
    print(f"FAIL total({i}) = {got}, want {want}")
sys.exit(1 if bad else 0)
EOF
c "feat: add subtotal, discount, total and a check" cart.py <<'EOF'
def subtotal(items):
    return sum(price * qty for price, qty in items)

def discount(total):
    if total >= 100:
        return round(total * 0.10, 2)
    return 0.0

def total(items):
    s = subtotal(items)
    return round(s - discount(s), 2)
EOF
c "feat: add shipping fee" cart.py <<'EOF'

SHIPPING = 5.0
EOF
c "docs: explain discount rule" cart.py <<'EOF'

# 100以上の注文は10%割引。
EOF
c "feat: add currency format" cart.py <<'EOF'

def money(x):
    return f"{x:,.2f}"
EOF
c "feat: add empty cart helper" cart.py <<'EOF'

def is_empty(items):
    return len(items) == 0
EOF
c "feat: add item count" cart.py <<'EOF'

def count(items):
    return sum(qty for _, qty in items)
EOF
c "feat: add max quantity" cart.py <<'EOF'

MAX_QTY = 99
EOF
c "feat: add tax rate constant" cart.py <<'EOF'

TAX_RATE = 0.08
EOF
c "feat: add receipt title" cart.py <<'EOF'

def title(name):
    return f"Receipt for {name}"
EOF
c "feat: add free shipping limit" cart.py <<'EOF'

FREE_SHIPPING_FROM = 200
EOF
perl -pi -e 's/total >= 100/total > 100/' cart.py
git add -A; git commit -q -m "refactor: simplify discount check"
c "feat: add coupon placeholder" cart.py <<'EOF'

COUPONS = {}
EOF
c "feat: add rounding helper" cart.py <<'EOF'

def r2(x):
    return round(x, 2)
EOF
c "feat: add item label" cart.py <<'EOF'

def label(price, qty):
    return f"{qty} x {price}"
EOF
c "feat: add min order note" cart.py <<'EOF'

MIN_ORDER = 1
EOF
c "feat: add currency code" cart.py <<'EOF'

CURRENCY = "USD"
EOF
c "feat: add store name" cart.py <<'EOF'

STORE = "Demo Shop"
EOF
c "feat: add version string" cart.py <<'EOF'

VERSION = "1.0"
EOF
c "feat: add free item note" cart.py <<'EOF'

FREE_ITEM_NOTE = "none"
EOF
c "chore: add end marker" cart.py <<'EOF'

# end of file
EOF

答えを見る前に試してください。

1. cart-demoに入り、python3 test_cart.pyを実行して結果を書き留める（ステップ1）。
2. 失敗するケースを手で縮小し、別の値もいくつか試す（ステップ2）。
3. 仮説を1文で書き、99.99、100、100.01について結果を予想して書く（ステップ3）。
4. git bisectを1回手作業で（コミットごとに印をつけて）実行し、続けてgit bisect run python3 test_cart.pyでもう一度実行する。確認の回数を数える（ステップ4）。
5. 直してテストを再実行する（ステップ5）。

答え：

• 原因のコミットはrefactor: simplify discount checkで、20コミット中の11番目です。
• その変更は、cart.pyのdiscount関数で>=が>になったことです。
• 確認の回数は最大5回で、私の実行では4回でした。あなたは4回か5回で、ハッシュも違うかもしれませんが、それで正常です。
• 落とし穴が1つあります。テストは確認するすべてのコミットに存在しなければなりません。ここではtest_cart.pyが最初のコミットからあるので安全です。もしテストが途中のコミットで初めて追加された場合、それより古いコミットではファイルがないため「異常」と報告され、Gitが誤った結論を出します。避けるには、テストスクリプトをリポジトリの外に置く（Gitのドキュメントもテストスクリプトをリポジトリの外に置くよう助言しています）か、テストが現れたあとの正常なコミットを選びます。

6. AIに渡す短いバグ報告：5ステップのあとで#

5つのステップを終えると、AIが使えて、あなたが確認できるバグ報告を書くのに必要なものが揃います。貼れるテンプレートです。

バグ：<1文>
再現（最小）：<コマンドまたはデータ>
期待：<正しい結果>
実際：<出力をそのまま>
除外したこと：<試した仮説とその結果>
疑い：<今の仮説と、その根拠>
範囲：<ファイル、疑わしいコミット>
依頼：直す前に原因を説明し、
最小の変更を提案し、確認していないことも書いてください。

この記事の例では、記入済みの報告はこうなります。

バグ：合計がちょうど100の注文に10%割引がつかない。
再現（最小）：total([(100, 1)])
期待：90.0
実際：100.0
除外したこと：行数と各商品の価格は影響しない。
discount(99.99) = 0.0、discount(100) = 0.0、discount(100.01) = 10.0。
疑い：discount()の境界100での比較。
範囲：git bisectは「refactor: simplify discount check」のコミットを指している。
依頼：直す前に原因を説明し、最小の変更を提案してください。

この報告なら、正しい答えはほとんど明らかです。AIは境界での比較を指すでしょう。もっと大事なのは、答えを確認できることです。すでにあるテストと境界値で確かめられます。AIが別の場所の修正を提案したら、ずれているとすぐ分かります。修正にもAIに証拠を出させる方法は、記事「AIの結果に証拠を求める5つの方法」を参照してください。

7. 初心者がつまずきやすいところ#

7.1 例：ある朝、2つのやり方#

これは想定した場面で、実在の人物や製品には触れていません。

やり方1：すぐにAIに聞く。

• 09:30。 ユーザーから「100円の注文に割引がつきません」と報告が来ます。開発者はcart.py全体をAIに貼って、直し方を聞きます。
• 09:40。 AIはtotal関数の中に、合計が100のときだけの特別な条件を足すよう提案します。テストは通り、開発者はマージします。
• 11:15。 discount関数は>のままなので、discountを直接呼ぶ別の箇所（1日の終わりのレポート）はまだ間違います。開発者はまた探すのに時間を使います。

やり方2：5ステップをやってから聞く。

• 09:30。 同じ報告です。開発者はテストを実行し、1つのコマンドでバグを再現できると確認します。
• 09:40。 total([(100, 1)])まで縮小し、3つの境界値を予想してから試して、仮説が成り立ちます。
• 09:50。 git bisect runが、1文字の変更である「refactor: simplify discount check」のコミットを指します。
• 10:00。 開発者は同じ条件を使う箇所がほかにないか確かめるため、AIに短いバグ報告を渡し、根本を直してマージします。

やるべきこと：AIに聞く前に縮小と仮説を立てる習慣をつけ、AIの言うことを確認できるようにしましょう。これは例なので何も証明しません。証拠は引用した研究にあります。Perryら（2022年）はAIアシスタントで過信しやすいことを示し、BairesDevの調査は問題解決力がまだ重視されていることを示唆します。bisectが働けるように保存ポイントを残す方法は、記事「エージェントを使う人のGit入門」も参照してください。

8. バグをAIに渡す前の8つの質問#

1. 毎回バグを起こす1つのコマンドはありますか？
2. ケースはこれ以上小さくならないところまで縮小しましたか。これ以上外すとバグは消えますか？
3. 仮説は何で、結果を先に予想しましたか？
4. 結果は予想と合っていましたか。それとも、合うように曲げていませんか？
5. これはリグレッション（以前は動いていた）ですか。基準にできる正常なコミットはありますか？
6. 何を除外し、それを書き留めましたか？
7. バグ報告に期待、実際の結果（そのまま）、除外したことが入っていますか？
8. AIが答えたとき、何で確認しますか。テストですか、境界値ですか、それとも感覚だけですか？

9. バランスよく見る：できること、できないこと#

できること： 「プログラムが間違っている」を、証拠つきの具体的な場所に変える、半分ずつに絞って疑わしい範囲を素早く狭める、バグ報告を短く確認しやすくする、そして再発を防ぐテストを残す。

できないこと：

• git bisectは毎回同じ結果を返すテストと、動くコミットのある履歴を必要とします。タイミング、実データ、実行順、環境に左右されるバグは、再現するのがずっと難しくなります。
• 最初のコミットからバグがあるなら、出発点にできる正常なコミットがありません。履歴が少数の大きなコミットにまとめられていると、二分探索が示すのは大きなかたまりだけです。
• 注意深いコード読みや業務知識が必要なバグもあり、リグレッションではないものもあります。
• AIは、あなたがすべてのステップをやっていなくても、人より速く原因を見つけることがあります。この記事はAIに聞くなと言っているのではなく、確認できるようにあとで聞こうと言っています。
• この5ステップがバグ探しをどれだけ速くするかを測った対照実験は、見つかりませんでした。実践の整理と、私が作った小さなリポジトリでの実際の例が1つあるだけです。
• 実際の例は、20コミットの小さなリポジトリにバグが1つあるだけです。実際のリポジトリはずっと複雑です。

言い過ぎないこと： 5ステップがすべてのバグを見つけることは保証されません。軽く見ないこと： 原因を理解せずに直すコストは、たいてい後で、バグが別の場所で戻ってきたときに現れます。

10. まとめ#

デバッグは探偵の仕事に似ています。現場を保ち、縮小し、間違いうる仮説を立て、半分ずつに絞って消していき、バグが戻らないよう記録を残します。そこまでやれば、AIへのバグ報告は短くなり、AIの答えを確認する材料も手元にあります。20コミットのリポジトリで練習問題を試してみてください。30分ほどで、仕事を通して使える習慣が残ります。

参考資料#

数字は2026年10月時点の公開情報によります。記事のコマンドと出力はGit 2.56.0とPython 3.14.8での実際の実行結果で、コミットのハッシュは実行ごとに変わります。

• Git、git-bisectのドキュメント（使い方、git bisect run、終了コード0、125を除く1から127、スキップの125）
• BairesDev、Dev Barometer Q2 2026とプレスリリース「16 percent of juniors fully understand AI code」（外注会社による調査。元のページがアクセスを拒否したため、数字は検索結果から読みました。引用する前に元の資料を開いてください）
• Perryら、Do Users Write More Insecure Code with AI Assistants?（スタンフォード大学、2022年）

SQLのクエリを書く人、AIに書かせる人なら誰でも、初心者の方でも読めます。データベースの内部の知識は不要です。用語にはどれも身近なたとえを添えています。スクリプトとコードの部分は、結果だけ読みたい方は飛ばせる任意の内容です。

この記事の数字はすべて、SQLite 3.53.4（Python 3.14.8に付属、macOS、arm64）で実際に動かした実験のもので、出力はそのまま貼っています。実験は小さく、1台のマシンで、乱数で作ったデータを使っているので、性能比較表ではなく学ぶための題材として読んでください。データベースが実際にどうプランを選ぶかは複雑で、以下のたとえは覚えやすくするための補助にすぎず、実際はもっと入り組んでいます。

まず要点#

• インデックスがないと、データベースは結果を探すためにテーブルの全行を読むことがよくあります。10万冊の本の実験では、ある著者の検索に約2.2ミリ秒かかりました。
• 著者の列にインデックスを付けると、同じクエリが約0.03ミリ秒になり、約79倍速くなりました（他の回では75倍から82倍）。
• インデックスはいつも効くわけではありません。値が2種類しかない列（在庫ありかどうか）では、インデックスを使っても43.6ミリ秒かかり、全件走査の39.9ミリ秒より速くなりませんでした。
• 複数列インデックスでは、列の順番でどのクエリが使えるかが決まります。(genre, year)のインデックスはyearだけで絞るクエリに効かず、(year, genre)なら効きます。
• インデックスには代償があります。2万行の追加は、インデックス1つで約2.2倍、3つで約5倍遅くなり、最初の1つでファイルが約2.5MB増えました。
• 確認は安上がりです。クエリプランを読むだけです（SCANは全件走査、SEARCHは一部の行だけ）。AIにクエリを書かせたときに求めるべき証拠でもあります。

むずかしい言葉をやさしく#

この記事を読むと説明できること#

1. テーブルが大きくなるとクエリが遅くなる理由：インデックスがないと時間は行数に比例して増え、あると非常にゆっくり増える。
2. よいインデックスに必要な3つ：正しい先頭の列、多くの行を除外できる条件、列を関数や先頭の%で「隠さない」クエリ。
3. インデックスにはどれも代償がある：書き込みが遅くなり、領域を使う。効果を測れたら付け、誰も使わなければ外す。

1. まずイメージ：図書館のカード目録#

蔵書10万冊の図書館を思い浮かべてください。「Author 1234」という著者の本をすべて探したいとします。1つめの方法は、棚を端から歩いて1冊ずつ開き、著者を確かめること。2つめは、著者順にあらかじめ並んだカード目録を開き、「Author 1234」のところまで行って、そこにあるカードを読むこと。各カードには、本がどの棚にあるかが書いてあります。

2つめの方法のほうがはるかに速いのですが、条件があります。目録が作られていて、新しい本が入るたびに正しく保たれている必要があります。目録が並べていない聞き方（たとえば「名前の末尾が1234の著者」）をすると、司書はやはり棚を端から歩くことになります。

データベースのインデックスは、この目録です。この記事の残りでは、どれだけ速くなるのか、どんなときに効かないのか、代償は何かを、実測の数字で見ていきます。

ここでの教訓： インデックスはテーブルを速くするのではなく、質問が近道の並べ方に合っているとき、データベースに近道を与えます。

2. 実測：10万冊の本#

2.1 準備#

booksテーブルには、乱数で作った10万行があります。種（seed）を固定してあるので、まったく同じデータを再現できます。題名、著者（2,000人、1人あたり約50冊）、出版年（1950年から2024年）、ジャンル（8種類）、在庫ありの列（約90%が1）です。各クエリを200回実行し、中央値を取りました。データベースはメモリ上（:memory:）で動かしたので、数字は実際のディスクを反映しません。下の「限界」を見てください。

完全なスクリプトは7章にあるので再実行できます。以下は、この記事の主な数字として使った回の出力です。

2.2 ある著者の検索：全件走査とインデックス#

SELECT * FROM books WHERE author = 'Author 1234'    (結果は59行)

インデックスなし:
    plan : SCAN books
    median: 2.204 ms

CREATE INDEX idx_author ON books(author) の後:
    plan : SEARCH books USING INDEX idx_author (author=?)
    median: 0.028 ms

プランはSCAN（テーブル全体を歩く）からSEARCH books USING INDEX（インデックスを使う）に変わり、時間は2.204ミリ秒から0.028ミリ秒に減りました。約79倍の高速化です。スクリプト全体を4回走らせましたが、比は75倍から82倍の範囲でした。測ったのは10万行という1つの大きさだけなので、テーブルが大きくなったときに時間がどう変わるかは、この実験では示せません。原理としては、走査はすべての行を通るのでテーブルが大きいほど時間がかかり、PostgreSQLの文書はインデックスの検索を、探索木を数段たどることとして説明しています。

ここでの教訓： ほぼすべての行を除外できる条件なら、インデックスは非常に大きな改善をもたらします。

2.3 値が2種類の列：インデックスを使っても速くならない#

SELECT * FROM books WHERE in_stock = 1              (結果は89,966行)

インデックスなし:
    plan : SCAN books
    median: 39.896 ms

CREATE INDEX idx_stock ON books(in_stock) の後:
    plan : SEARCH books USING INDEX idx_stock (in_stock=?)
    median: 43.571 ms

ここではプランが確かにインデックスを使っています（SEARCH books USING INDEX）が、時間は減らず、むしろ少し遅くなりました（43.571ミリ秒対39.896ミリ秒）。もっともらしい説明は、クエリがやはり行の約90%を取り出す必要があり、主な作業が89,966行を読んで渡すことなので、インデックス検索ではその部分が減らない、というものです。これは私の説明で、各段階のコストを切り分けて証明したわけではありません。

反対側も試しました。in_stock = 0は10,034行（約10%）だけを返します。新しいデータベースでは、走査が5.551ミリ秒、インデックスが5.029ミリ秒で、約9%速くなっただけでした。クエリが行の90%を除外できても、効果は、著者の79倍に比べて小さいのです。著者は10万行のうち59行にしか一致しないからです。

ここでの教訓： インデックスの価値は選択性で決まります。問うべきは「この列はよく絞り込まれるか」ではなく「この条件はどれだけ行を除外するか」です。プランにUSING INDEXと出ていても、速いとは限りません。

2.4 複数列インデックス：列の順番で決まる#

ジャンル（genre）と年（year）の2列に2種類のインデックスを作り、2つのクエリで試しました。

クエリA: WHERE genre = 'tech' AND year >= 2020    (827行)
クエリB: WHERE year = 2015                        (1,321行)

複数列インデックスなし:
    A: SCAN books                                         3.124 ms

インデックス (genre, year):
    A: SEARCH books USING INDEX idx_genre_year (genre=? AND year>?)   0.437 ms
    B: SCAN books                                         2.067 ms

インデックス (year, genre):
    A: SEARCH books USING INDEX idx_year_genre (year>?)     0.561 ms
    B: SEARCH books USING INDEX idx_year_genre (year=?)     0.694 ms

読み方：

• クエリAは両方のインデックスを使えますが、(genre, year)は両方の条件（genre=? AND year>?）を使い、(year, genre)は最初の条件year>?しか使えません。時間は0.437対0.561ミリ秒で、違いはありますが大きくはありません。
• 大きな差はクエリBにあります。(genre, year)のインデックスは、yearだけで絞るクエリには使えず（プランはSCANのままで2.067ミリ秒）、(year, genre)なら使えます（0.694ミリ秒）。

まずジャンル順、その中で年順に並んだ目録を想像してください。「ジャンルがtechで2020年以降」なら、techの引き出しにまっすぐ行って読み進められます。「2015年の本すべて」だと、2015年はどのジャンルの引き出しにも散らばっているので、目録は役に立ちません。SQLiteの文書はこの規則を述べています。インデックスの列は左から右へ、飛ばさずに使われます。Use The Index, Luke（Markus Winand）は、姓順の電話帳にたとえています。名前だけでは引けません。

読みすぎないための注意を1つ。両方の列に等号を使うクエリ（たとえばyear = 2015 AND genre = 'tech'）では、両方の順序を試したところ、どちらも両方の列を使い、走査の約1.6ミリ秒に対してそれぞれ約0.07ミリ秒でした。列の順番が最も効くのは、1つの列だけで絞るクエリがあるとき、または先頭の列に範囲条件（>=、BETWEEN）があるときです。PostgreSQLの文書は、複数列インデックスは控えめに使うよう勧め、3列を超えるインデックスは、テーブルの使い方がよほど規則的でない限りほとんど役に立たないと述べています。PostgreSQL 18では場合によって先頭の列を「飛ばす」こともできるので、ここでの列順の規則は一般則であり、すべてのシステムとすべての版に当てはまる法則ではありません。

ここでの教訓： まず実際のクエリを書き出し、先頭の列ができるだけ多くのクエリに現れるように列の順番を選びます。

2.5 インデックスがあってもクエリが走査してしまう場合#

idx_authorを残したまま、同じ著者を探す4通りの聞き方を試しました。

WHERE lower(author) = 'author 1234'     plan: SCAN books                  5.539 ms
WHERE author LIKE '%1234'               plan: SCAN books                  3.798 ms
WHERE author LIKE 'Author 1234%'        plan: SCAN books                  2.852 ms
WHERE author GLOB 'Author 1234*'        plan: SEARCH books USING INDEX idx_author (author>? AND author<?)   0.029 ms

• 列を関数で包む（lower(author)）：インデックスはauthorの順に並んでいて、lower(author)の順ではないので無視されます。元の名前順の目録に、名前の小文字版で聞くようなものです。
• 先頭の%（LIKE '%1234'）：目録は頭の文字順に並んでいるので、末尾で聞いても使えません。
• 先頭が固定のLIKE（LIKE 'Author 1234%'）：理屈の上ではインデックスを使えますが、ここではSCANのままです。SQLiteの文書によると、LIKEは既定で大文字小文字を区別しないため、列がNOCASEの照合順序を使っているときだけインデックスを使えます。私の既定のインデックスはバイト単位（BINARY）で比べるので、使えません。author COLLATE NOCASEのインデックスを追加で作ると、プランはSEARCHに変わりました。
• GLOBは大文字小文字を区別するので既定のインデックスに合い、0.029ミリ秒でした。

この細部はSQLite固有です。PostgreSQLにはLIKEとインデックスについて独自の規則があり（照合順序とインデックスの種類に依存します）、今回は確認していません。それでも一般的な教訓は変わりません。推測せず、プランを読むこと。

2.6 代償：書き込みが遅くなり、領域も増える#

100,000行のテーブルに20,000行を追加 (7回の中央値、メモリ上):

インデックス0個                            6.4 ms   (x1.00)   ファイル 4.98 MB
インデックス1個 (author)                  13.9 ms   (x2.18)   ファイル 7.48 MB
インデックス3個 (author, genre+year, title) 31.8 ms   (x5.00)   ファイル 12.23 MB

1行を追加するたびに、データベースはテーブルとすべてのインデックスを更新します。インデックス3つで、追加は約5倍遅くなり、ファイルは2.5倍近く大きくなりました（4.98MBから12.23MB）。PostgreSQLの文書も、インデックスはデータを変更する操作に負担を加えると述べ、ほとんど、またはまったく使われないインデックスは削除するよう勧めています。

注意：この例はメモリ上で、1つのトランザクションでの一括追加、同時アクセスなし、ディスクなしの条件です。実際のシステムでは、どちらの方向にもかなり違う可能性があります。この数字は向き（インデックスが増えると書き込みが重くなる）を見るためのもので、予測に使うものではありません。

ここでの教訓： 実際によく走らせるクエリのためにインデックスを付け、また測り直します。「念のため」にすべての列に付けるのは、使われないものに多くを払う方法です。

3. クエリプランの読み方#

司書が探し方を先に教えてくれるところを想像してください。SQLiteでは、クエリの前にEXPLAIN QUERY PLANと書きます。

EXPLAIN QUERY PLAN SELECT * FROM books WHERE author = 'Author 1234';

SQLiteの文書によると、知っておくべき語は2つです。

間違えやすい点が3つあります。

1. SEARCHは速さを保証しません（2.3の例は、インデックスを使っても走査と同じくらいかかりました）。
2. 括弧は、インデックスがどの条件を使うかを示します。2.4の(year>?)は、条件の半分しか使われなかったことを示しています。
3. SQLiteの文書は、この出力が人間が読むためのもので、版によって変わりうると明記しています。この形式に依存するコードは書かないでください。

他のシステムにも似た道具がありますが、形式は違います。PostgreSQLはEXPLAIN（実際に動かして測るEXPLAIN ANALYZEも）を使うので、SQLiteの読み方をそのまま持ち込まないでください。

4. インデックスでよくある間違い#

司書が1人しかいない図書館を想像してください。目録が増えるほど、本が入るたびに忙しくなります。

4.1 AIが書いたクエリは？#

クエリを書くAIアシスタントは、こちらが伝えない限り、テーブルが100行になるのか1億行になるのかを知りません。書かれたクエリは、たいてい結果としては正しく、テスト用データでは速いので、レビューする人は見逃しがちです。AIが生成したクエリにインデックスが欠けている頻度を測った独立した数字は見つけられなかったので、これは数字ではなく仕組みからの注意です。最も安上がりな対処は、証拠を求めることです。AIの結果に自分で証明させる：証拠を求める5つの方法の方法2のように、実際のクエリプランと想定する行数を貼らせます。

5. 例（想定）：最初は問題なく、数か月後に遅くなるクエリ#

これは想定した例で、実在の人物や製品には触れていません。大きな規模の数字は私が置いた掛け算であり、測定値ではありません。

• 10:00。 開発者がエージェントに頼みます。「著者で本を検索する画面を追加して。」
• 10:20。 エージェントはWHERE author = ?のクエリを書き、1,000冊で試して1ミリ秒未満で動きました。結果が正しくテストも緑なので、開発者は承認します。
• 3か月後の09:30。 蔵書は500万冊になりました。走査の時間が行数に比例して増えると仮定すると（例のための仮定です）、10万行での2.2ミリ秒は、500万行で約110ミリ秒になります（2.2の50倍）。著者の検索1回が、気づくほどの時間マシンを占有し、多くの人が同時に検索すると画面が遅く感じられます。
• 対処： クエリプランを実行し、SCAN booksを確認し、authorにインデックスを付けて測り直します。インデックス検索は行数が増えてもごくゆっくりしか伸びないという仮定のもとでは、時間はごく小さいままです。

10:20の時点でやるべきだったこと：新しいクエリをレビューするとき、クエリプランと想定する行数を尋ねる。この想定例は何も証明しません。証拠は2章の実験とPostgreSQLの文書にあります。インデックスは書き込みにコストがかかるので、あちこちに足すのではなく、意図して選び、測ります。学ぶ必要性については、ITviec（検索結果を通じて、求人プラットフォーム自身のデータ）が、2025年第3四半期にSQLを求める求人が前年同期比で約38.7%増えたと報告しているので、AIのおかげで時代遅れになったスキルではありません。

6. 解答つきの練習問題#

7章のスクリプトを1回実行してデータを用意し、3問を解いてください。実行する前に結果を予想してみましょう。

問題1。 クエリWHERE year = 2015 AND genre = 'tech'にインデックスを付けます。(year, genre)と(genre, year)の両方を試してください。どちらのインデックスが両方の条件を使え、時間はどう違いますか。

問題2。 in_stockにインデックスを作り、WHERE in_stock = 0とWHERE in_stock = 1を実行してください。著者での検索と効果が大きく違うのはなぜですか。

問題3。 authorに既定のインデックスしかない状態で、WHERE author LIKE 'Author 1234%'を実行してください。なぜSCANのままですか。直す方法は2つあります。見つけられますか。

解答（私の実行結果から）#

問題1。 どちらの順序も、両方が等号なので、両方の条件を使います。

インデックスなし: SCAN books                                  1.602 ms (149行)
(year, genre):    SEARCH books USING INDEX a (year=? AND genre=?) 0.071 ms
(genre, year):    SEARCH books USING INDEX b (genre=? AND year=?) 0.074 ms

違いはほとんどありません。覚えておくこと：すべての列に等号だけを使うクエリでは、順番はあまり重要ではありません。1つの列だけで絞るクエリ（2.4のように）や範囲があるときに重要になります。

問題2。 測定ごとに新しいデータベースで：

in_stock = 0  (10,034行): 走査 5.551 ms、インデックス 5.029 ms
in_stock = 1  (89,966行): 走査 39.209 ms、インデックス 41.749 ms

= 0では効果がごくわずか（約9%）で、= 1ではありません。多くの行を取り出して渡すことに、時間の大半がかかります。教訓：選択性と返す行数が、インデックスの価値を決めます。この列に対する他のクエリでは、まだ恩恵がある場合もあります（たとえば在庫のある本の数を数えるのにカバリングインデックスを使えるかもしれません）。この記事では、そのケースは別に測っていません。

問題3。 SQLiteの文書によると、LIKEは既定で大文字小文字を区別しないので、LIKEの最適化はNOCASEの照合順序のインデックスだけを使います。既定のインデックスはBINARYなので使われません。直し方は2つ。GLOB 'Author 1234*'と書く（GLOBは大文字小文字を区別し、BINARYのインデックスを使えて、0.029ミリ秒）、またはCREATE INDEX nc ON books(author COLLATE NOCASE)を作ると、LIKE 'Author 1234%'がSEARCHに変わります（試した結果：0.029ミリ秒）。

7. 再実行用のスクリプト（任意）#

必要なのはPython 3だけです（sqlite3ライブラリは付属しています）。index_demo.pyとして保存し、python3 index_demo.pyで実行します。30秒ほどかかります。数字はマシンによって違いますが、結果の形（SCANとSEARCHの違い、時間の大小の順）は似るはずです。

import itertools
import random
import sqlite3
import statistics
import time

N = 100_000
REPS = 200
GENRES = ["novel", "science", "history", "children", "cooking", "tech", "poetry", "comic"]


def make_rows(n, seed):
    rnd = random.Random(seed)
    rows = []
    for i in range(n):
        rows.append((
            f"Book {rnd.randrange(10**6):06d}",
            f"Author {rnd.randrange(2000):04d}",
            rnd.randrange(1950, 2025),
            rnd.choice(GENRES),
            1 if rnd.random() < 0.9 else 0,
        ))
    return rows


def new_db(rows):
    db = sqlite3.connect(":memory:")
    db.execute("CREATE TABLE books (id INTEGER PRIMARY KEY, title TEXT, author TEXT, "
               "year INTEGER, genre TEXT, in_stock INTEGER)")
    db.executemany("INSERT INTO books (title, author, year, genre, in_stock) VALUES (?,?,?,?,?)", rows)
    db.commit()
    return db


_n = itertools.count()


def plan(db, sql):
    # the counter comment makes each EXPLAIN text unique, so Python never reuses a stale cached plan
    return [r[3] for r in db.execute(f"EXPLAIN QUERY PLAN /*{next(_n)}*/ " + sql)]


def timed(db, sql):
    samples = []
    count = 0
    for _ in range(REPS):
        t = time.perf_counter()
        count = len(db.execute(sql).fetchall())
        samples.append((time.perf_counter() - t) * 1000)
    return statistics.median(samples), count


def show(db, label, sql):
    p = plan(db, sql)
    ms, count = timed(db, sql)
    print(f"[{label}] {sql}")
    print(f"    plan : {' | '.join(p)}")
    print(f"    rows : {count}   median: {ms:.3f} ms over {REPS} runs")


rows = make_rows(N, seed=42)
db = new_db(rows)
print("SQLite", sqlite3.sqlite_version, "rows", N)
print()

print("=== 1. One author: scan then index ===")
q1 = "SELECT * FROM books WHERE author = 'Author 1234'"
show(db, "no index", q1)
db.execute("CREATE INDEX idx_author ON books(author)")
show(db, "index on author", q1)
print()

print("=== 2. A column with two values (in_stock: 90% are 1) ===")
q2 = "SELECT * FROM books WHERE in_stock = 1"
show(db, "no index", q2)
db.execute("CREATE INDEX idx_stock ON books(in_stock)")
show(db, "index on in_stock", q2)
db.execute("DROP INDEX idx_stock")
print()

print("=== 3. Two columns: order matters ===")
q3 = "SELECT * FROM books WHERE genre = 'tech' AND year >= 2020"
q4 = "SELECT * FROM books WHERE year = 2015"
show(db, "no composite index, q3", q3)
db.execute("CREATE INDEX idx_genre_year ON books(genre, year)")
show(db, "index (genre, year), q3", q3)
show(db, "index (genre, year), q4 uses year only", q4)
db.execute("DROP INDEX idx_genre_year")
db.execute("CREATE INDEX idx_year_genre ON books(year, genre)")
show(db, "index (year, genre), q3", q3)
show(db, "index (year, genre), q4 uses year only", q4)
db.execute("DROP INDEX idx_year_genre")
print()

print("=== 4. Queries an index on author cannot help ===")
q5 = "SELECT * FROM books WHERE lower(author) = 'author 1234'"
q6 = "SELECT * FROM books WHERE author LIKE '%1234'"
q7 = "SELECT * FROM books WHERE author LIKE 'Author 1234%'"
show(db, "index on author, lower()", q5)
show(db, "index on author, LIKE '%1234'", q6)
show(db, "index on author, LIKE 'Author 1234%'", q7)
q8 = "SELECT * FROM books WHERE author GLOB 'Author 1234*'"
show(db, "index on author, GLOB 'Author 1234*'", q8)
print()

print("=== 5. The price: size and inserts (20,000 new rows, 7 runs each) ===")
extra = make_rows(20_000, seed=7)


def insert_time(index_sqls):
    samples = []
    pages = 0
    for _ in range(7):
        d = new_db(rows)
        for s in index_sqls:
            d.execute(s)
        t = time.perf_counter()
        d.executemany("INSERT INTO books (title, author, year, genre, in_stock) VALUES (?,?,?,?,?)", extra)
        d.commit()
        samples.append((time.perf_counter() - t) * 1000)
        pages = d.execute("PRAGMA page_count").fetchone()[0] * d.execute("PRAGMA page_size").fetchone()[0]
        d.close()
    return statistics.median(samples), pages / (1024 * 1024)


setups = [
    ("0 indexes", []),
    ("1 index (author)", ["CREATE INDEX i1 ON books(author)"]),
    ("3 indexes (author, genre+year, title)", [
        "CREATE INDEX i1 ON books(author)",
        "CREATE INDEX i2 ON books(genre, year)",
        "CREATE INDEX i3 ON books(title)",
    ]),
]
base = None
for name, sqls in setups:
    ms, mb = insert_time(sqls)
    base = base or ms
    print(f"{name:40s} insert 20,000 rows: {ms:8.1f} ms  (x{ms / base:.2f})   size after: {mb:6.2f} MB")

8. クエリを追加、レビューする前のチェックリスト#

1. このテーブルは1年後に何行になる見込みで、その規模で試したか。
2. クエリプランを読んだか。最初の行はSCANかSEARCHか。
3. 絞り込みの条件は、行の何%くらいを除外するか。
4. クエリは列を関数で包んでいないか、LIKEの先頭に%を置いていないか。
5. 複数列インデックスなら、先頭の列は実際のクエリに現れるか。
6. プランの括弧は、インデックスがどの条件を使っていることを示しているか。
7. 新しいインデックスの書き込みコストは、よく変更されるこのテーブルで許容できるか。
8. 実際のどのクエリのプランにも現れなくなった古いインデックスはないか。外せるか。
9. AIがクエリを書いた場合、プランと想定する行数を貼ってもらったか。

9. バランスのよい見方#

かなり確か（測定または文書にある）： インデックスは、10万行前後では、絞り込みの強いクエリを数十倍速くできる。インデックスが効くかどうかは、選択性、列の順番、条件の書き方で決まる。インデックスは書き込みを遅くし、領域を使う。

注意が必要：

• 実験は、1台のマシンで、メモリ上で、均等に分布する乱数のデータで行いました。実際のデータは偏ることが多く（少数の著者が非常に多くの本を持つなど）、ディスク、キャッシュ、同時アクセスで結果は変わります。
• SQLiteはPostgreSQLやMySQLではありません。それぞれ独自のプランナー、LIKEの規則、インデックスの種類、最適化があります（たとえばPostgreSQL 18は場合によって先頭の列を飛ばせます）。今回PostgreSQLを直接は試しておらず、それに関する記述は文書によるものです。
• この記事は、プランナーの統計（ANALYZE）、部分インデックス、より深いカバリングインデックス、キャッシュ、テーブルのディスク上の保存のされ方には触れていません。次に学ぶとよい題材です。
• 79倍という数字は、この実験のものです。自分のシステムへの約束として使わないでください。

大げさにしない： インデックスは、遅いクエリすべてを治す薬ではありません。遅い原因が、行や列を取りすぎていること、LIMITがないこと、テーブル設計にあることもあります。軽く見ない： 大きなテーブルでは、クエリプランを見ないことが、直しやすい原因のなかで最も安上がりなことが多いのです。

10. まとめ#

インデックスはデータベースのカード目録です。質問が並べ方に合っていればとても速く、合っていなければ役に立たず、保つにはいつも手間がかかります。正しく使うには、3つの習慣が必要です。クエリプランを読むこと、条件がどれだけの行を除外するかを問うこと、付けた後にまた測ること。AIが書いたクエリには、同じプランを証拠として求めてください。これらはどんな道具よりも長く役に立ちます。

先に進みたい方へ：AIが書いたコードのレビューには変更のチェックリストがあり、AIが書いたコードのテストは、クエリを直すときに守ってくれるテストを持つのに役立ちます。

参考資料#

この記事の測定は私がSQLite 3.53.4（Python 3.14.8、macOS arm64）で行ったもので、お使いのマシンでは違うかもしれません。以下の文書は、記事で述べた点を確かめるために開きました。ITviecの数字は検索結果を通じてのみ確認し、元の報告書は開いていません。

• SQLite, The SQLite Query Optimizer Overview（複数列インデックスを左から右へ使う規則、LIKEとGLOBの最適化の条件）
• SQLite, EXPLAIN QUERY PLAN（SCAN、SEARCH、USING INDEXの意味、形式が変わりうるという注意）
• PostgreSQL, Multicolumn IndexesとIntroduction to indexes（バージョン18の文書）
• Markus Winand, Use The Index, Luke: Concatenated Indexes
• ITviec, ベトナムのIT採用市場の概況 2025年Q3（検索結果を通じてのみ確認。自社プラットフォームの求人だけを測定）

AIエージェントにコードの作業を任せる人なら誰でも、Gitを使ったことがない初心者の方でも読めます。前提知識は要りません。用語にはどれも身近なたとえを添え、コマンドの部分には印をつけてあるので、写して試しても、読み飛ばしてもかまいません。

実例のコマンドと出力は、すべて練習用リポジトリで実際に動かしたものです（Gitのバージョンは2.56.0、2026年10月30日）。「例」と書いた場面は作った例で、実在の人物や会社には触れていません。エージェントが内部でどう間違えるのかは、まだ誰にも完全には分かっていません。以下のたとえは覚えやすくするための補助にすぎません。

まず要点#

• エージェントは数分で多くのファイルを直せます。戻る手段がないと、1回の失敗が作業時間をまるごと飲み込みかねません。Gitはセーブポイントです。コミットしたものだけを覚えています。
• 基本の習慣は、任せる作業ごとにブランチを分ける、エージェントに小さなコミットを求める、結果を受け取る前にgit status、次にgit diffを読むの3つです。
• 戻る道は4つあり、場面ごとに使い分けます。git restore（まだコミットしていない）、git revert（コミット済みで最も安全）、git reflog（うっかりの後の救出）、git worktree（最初からエージェント専用のフォルダで作業させる）。
• いちばんの死角：git restoreで捨てた未コミットの変更は取り戻せません。この記事の練習用リポジトリでは、reflogにその記録はありませんでした。
• セーブポイントが守るのはリポジトリ内のファイルだけです。消えたデータベースや送信済みのメールはGitの外にあります。
• 破壊的なコマンド（push --force、reset --hard、clean）は、エージェントへの指示に確認なしで実行しないと書いておきましょう。

むずかしい言葉をやさしく#

1. まずイメージ：セーブポイントのあるゲーム#

長いゲームを遊んでいるところを想像してください。一度もセーブしなければ、1回やられると1時間分が消えます。数分おきにセーブしていれば、やられても失うのは数分です。

エージェントに任せるのも同じです。エージェントはとても速く、少しせっかちなプレイヤーです。最初のファイルを読み終える前に、10個のファイルを直してしまうこともあります。優秀ですが、いつも正しいわけではありません。エージェント系ツールの文書自身もそう述べています（第6節）。セーブポイントはエージェントの間違いを減らしません。間違いを安くします。

その役を担うのがGitで、大事なルールが1つあります。**Gitはコミットしたものしか覚えていません。**フォルダの中にあるだけでコミットしていない変更は、セーブせずにステージの途中を遊んでいるようなものです。

**教訓：**作業を任せる前に、きれいなセーブポイントを作っておきます。エージェントが作業している間は、こまめにセーブするよう求めます。

2. 5ステップの手順：作業ごとにブランチを分ける#

食卓にいくつものお皿があるところを想像してください。新しい料理をいきなりメインの皿で試さず、別の皿に盛ります。失敗したらその皿ごと捨てればよく、メインの皿は無傷です。

以下は、注文の合計を計算するprices.pyという1つのファイルだけを入れた練習用リポジトリで、実際に動かしたものです。mainブランチに最初のセーブポイントが1つあります。

ステップ1：この作業専用のブランチを作る#

git switch -c agent/add-discount

Switched to a new branch 'agent/add-discount'

agent/作業名という名前の付け方にしておくと、ブランチ一覧を見ただけでエージェントのものだと分かります。Gitの決まりではなく、私の習慣です。

ステップ2：作業を任せ、エージェントに進めさせる#

エージェントに「total関数に、任意の割引パラメータを加えて」と頼みます。エージェントがファイルを編集します。

ステップ3：受け取る前にgit status、次にgit diffを読む#

git status -sb
git diff

## agent/add-discount
 M prices.py
diff --git a/prices.py b/prices.py
index de87eb8..d7bc76f 100644
--- a/prices.py
+++ b/prices.py
@@ -1,2 +1,3 @@
-def total(items):
-    return sum(item["price"] * item["qty"] for item in items)
+def total(items, discount=0):
+    subtotal = sum(item["price"] * item["qty"] for item in items)
+    return subtotal * (1 - discount)

Mは1つのファイルが変更されたという意味です。-で始まる行は削除された行、+で始まる行は新しい行です。この読み取りは、記事AIの結果に証拠を添えさせる5つの方法の「証拠を開く」ステップであり、AIが書いたコードのレビューの最初の部分でもあります。

ステップ4：小さくコミットする（セーブポイント）#

git add prices.py
git commit -q -m "feat: add optional discount to total"
git log --oneline

c9c7cf3 feat: add optional discount to total
6dd4973 feat: add total function

-qはコマンドを静かにするだけの指定です。1コミット1作業で、一言で説明できる大きさにします。メモはConventional Commits（よく使われる書き方の約束で、必須ではありません）のfeat: 作業名の形です。

ステップ5：納得したらマージする#

差分を読み、チェックも走らせたら、ブランチをmainに取り込むのはあなた自身です。

git switch main
git merge --no-ff -q agent/add-discount -m "merge: add discount"
git log --oneline --graph

*   04cbf8d merge: add discount
|\  
| * 5aee66b feat: add extra script
| * c5b6fbf Revert "refactor: simplify total"
| * 6f88dd0 refactor: simplify total
| * c9c7cf3 feat: add optional discount to total
|/  
* 6dd4973 feat: add total function

mainブランチには、あなたが目を通したものだけが入ります。途中のセーブポイント（refactor、Revert、extra script）は、第3節の実験で作ったものです。

2.1 自分で確かめられる計算（例、読み飛ばし可）#

数字を作った例です。エージェントが3時間（180分）休まず作業し、最後の1分で問題が起きたとします。

session = 180
no_commit_loss = session            # 一度も保存しない: 最大180分を失う
every = 20
saves = session // every            # セーブポイント9個
worst_loss = every                  # 失うのは最大20分
print(saves, worst_loss, session - worst_loss)
# 9 20 160

結果の読み方：20分ごとにコミットすれば、セーブポイントは9個になり、最悪の事故でも失うのは180分ではなく最大20分、つまり160分は守られます。20分はこの例のための私の仮定です。現実に決まった公式はありませんが、振り返れて、思い切って捨てられる大きさに刻む、というのが原則です。

3. 戻る：場面に合ったコマンドを選ぶ#

文章の一段落をうっかり消したところを想像してください。取り戻せるかどうかは、文書を保存してあったかどうかで決まります。

3.1 git restore：未コミットの変更を捨てる#

エージェントがファイルを役に立たない関数に書き換えました。

git status -sb
git diff --stat
git restore prices.py
git status -sb

## agent/add-discount
 M prices.py
 prices.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
## agent/add-discount

restoreの後は、git statusにMの行がなくなります。ファイルがコミット済みの状態に戻ったということです。注意：捨てた変更が残したいものだったとしても、戻る道はありません。実際に試しました。ファイルを編集し、git restoreを実行し、reflogとstashの一覧を見ます。

git reflog | head -2
git stash list | wc -l

5aee66b HEAD@{0}: reset: moving to HEAD
5aee66b HEAD@{1}: reset: moving to HEAD@{1}
       0

2行のreflogは以前の操作のものです。捨てた1行の記録はなく、stashの一覧も空（0件）です。git restoreのマニュアルは、このコマンドをある元から内容を復元するものと説明しており、現在の内容は置き換えられます。残したいなら、先にgit stashするか、先にコミットします。

3.2 git revert：コミット済みのものを打ち消す#

エージェントが、関数を壊す「単純化」をコミットしました。

git commit -qam "refactor: simplify total"
git revert --no-edit HEAD
git log --oneline

[agent/add-discount c5b6fbf] Revert "refactor: simplify total"
 Date: Fri Oct 30 17:31:17 2026 +0700
 1 file changed, 2 insertions(+), 1 deletion(-)
c5b6fbf Revert "refactor: simplify total"
6f88dd0 refactor: simplify total
c9c7cf3 feat: add optional discount to total
6dd4973 feat: add total function

壊れたコミットは履歴に残り、それを打ち消す新しいコミットが加わります。Gitの文書によると、git revertは以前のコミットを削除せず、それを打ち消す新しいコミットを作ります。履歴を書き換えないので、共有ブランチでも安全な選択です。

3.3 git reset --hardのあとgit reflog：うっかりしても救える#

いちばん怖い場面なので、実際に動かしました。コミットを1つ足し、2つ戻します。

git reset --hard HEAD~2
git log --oneline
ls

HEAD is now at 6f88dd0 refactor: simplify total
6f88dd0 refactor: simplify total
c9c7cf3 feat: add optional discount to total
6dd4973 feat: add total function
prices.py

extra.pyがフォルダから消え、prices.pyの関数も壊れた版に戻りました。ところが、reflogは覚えています。

git reflog | head -8

6f88dd0 HEAD@{0}: reset: moving to HEAD~2
5aee66b HEAD@{1}: commit: feat: add extra script
c5b6fbf HEAD@{2}: revert: Revert "refactor: simplify total"
6f88dd0 HEAD@{3}: commit: refactor: simplify total
c9c7cf3 HEAD@{4}: commit: feat: add optional discount to total
6dd4973 HEAD@{5}: checkout: moving from main to agent/add-discount
6dd4973 HEAD@{6}: commit (initial): feat: add total function

セーブポイント5aee66bはまだあります。ブランチをそこへ戻します。

git reset --hard HEAD@{1}
git log --oneline
ls

HEAD is now at 5aee66b feat: add extra script
5aee66b feat: add extra script
c5b6fbf Revert "refactor: simplify total"
6f88dd0 refactor: simplify total
c9c7cf3 feat: add optional discount to total
6dd4973 feat: add total function
extra.py
prices.py

すべて元に戻りました。Gitの文書によると、reflogの記録は既定で90日、どのブランチにも属さなくなった記録は30日保持されるので、早めに救出します。reflogはあなたのマシンの中のノートで、サーバーにはpushされません。

3.4 git stash：作業途中のものを一時的にしまう#

git stash push -m "half done idea"
git stash list
git stash pop

Saved working directory and index state On agent/add-discount: half done idea
stash@{0}: On agent/add-discount: half done idea
Dropped refs/stash@{0} (377cf291f166fc06e84e9ac41e27da37fa79d8d9)

2つのコマンドの間は、git statusがきれいでした。popの後は変更が戻ります。中途半端なコミットをせずに手を空けて、エージェントに別のことをさせたいときに使います。

**教訓：**一文だけ覚えてください。*コミットしたものはほぼ必ず救えるが、していないものは救えない。*だから小さくコミットするのです。

4. ワークツリー：エージェントに専用の机を渡す#

キッチンに調理台が2つあるところを想像してください。あなたはこちらで、助手はあちらで料理します。同じキッチン、同じ食材庫ですが、肘がぶつかりません。

ワークツリーは、同じリポジトリの2つ目の作業フォルダです。Gitの文書によると、リポジトリは本体のフォルダと共有しつつ、HEADとインデックスは別に持ち、既定では2つのワークツリーが同じブランチに立つことをGitが許しません。

git worktree add ../demo-git-wt -b agent/refactor-names
git worktree list

Preparing worktree (new branch 'agent/refactor-names')
HEAD is now at 5aee66b feat: add extra script
/path/to/demo-git    5aee66b [agent/add-discount]
/path/to/demo-git-wt 5aee66b [agent/refactor-names]

（読みやすいよう、パスは/path/to/に短くしています。）これでエージェントはdemo-git-wtで作業し、あなたは本体のフォルダで編集を続けられます。終わったら片づけます。

git worktree remove ../demo-git-wt
git branch -d agent/refactor-names

Deleted branch agent/refactor-names (was 5aee66b).

--forceなしのgit worktree removeは、きれいなフォルダしか削除しません。Claude Codeには、新しいワークツリーでセッションを開く近道claude --worktree 作業名があります（同社のCommon workflowsのページによる）。ほかのツールには独自のやり方があるかもしれないので、お使いのツールの文書を確認してください。

5. エージェントへのルール#

家の鍵を手伝いの人に渡す場面を想像してください。入ってよい部屋と、いけない部屋を伝えます。

5.1 ルールとして書いておきたい習慣#

• **mainに直接コミットしない。**作業ごとに1ブランチ。
• push --forceをしない。確認なしにpushもしない。サーバーへのpushは、他の人から見える行為です。
• reset --hard、clean、ブランチの削除を確認なしにしない。git cleanはGitが追跡していないファイルを削除するので、救えるコピーがないものとして扱います。
• .envのような鍵を持つファイルに触れない。.gitignoreで防ぎ、git check-ignore -v .envで確かめます。

git check-ignore -v .env

.gitignore:1:.env	.env

この行は、.gitignoreの1行目のルールが.envファイルを防いでいるという意味です。（練習用リポジトリでは、私の環境が本物の.envファイルの作成を許さなかったため、ルールだけを確かめ、本物のファイルでgit statusを試してはいません。）

5.2 エージェントへの指示に貼る5行#

このブロックを、AGENTS.mdやツールの指示ファイルに入れます。

## Git
- agent/<作業名> というブランチで作業し、main に直接コミットしない。
- コミットは小さく、1コミット1作業。コミット前にチェックを走らせる。
- 確認なしに push --force、reset --hard、clean、ブランチ削除をしない。
- push しない。.env や鍵を持つファイルを編集しない。
- 作業の最後に git status と git diff --stat の結果を貼る。

これは言葉で書いた指示で、エージェントが無視することもあります。最初の関所であって、唯一の関所ではありません。ツールの権限設定や、コード管理サービスのmainブランチ保護（あれば）も併せて使ってください。

5.3 エージェントのコミットメモはどう見えるべきか#

feat: add optional discount to total

- discount defaults to 0, so existing callers keep working
- checked with: python -m pytest tests/test_prices.py (3 passed)

1行目に何をしたか、本文に理由と確認方法を書きます。このメモ自体が小さな証拠であり、AIの結果に証拠を添えさせる5つの方法の方法2に沿っています。

6. 使った数字と文書#

正しく読むために：GitとClaude Codeの文書は、セーブポイントと専用ブランチの利用を支持しています。エージェントを使うときに専用ブランチがどれだけ事故を減らすかを測った研究は見つけられませんでした。以上の習慣は良い実践であって、測定された結果ではありません。

7. セーブポイントがあっても失敗するところ#

この機械でゲームをセーブしても、キャラクターが外の現実世界ですでに何かをしてしまっている状況を想像してください。

7.1 例：エージェントと過ごす朝#

これは想定した例で、実在の人物や製品には触れていません。

• **09:00。**開発者がブランチagent/add-discountを作り、「合計の関数に割引を加えて」と任せます。
• **09:20。**エージェントが完了を伝えます。開発者がgit diff --statを実行すると、1つのファイルが予想より大きく変わっています。よく読むと、エージェントが古い関数をまるごと書き直していました。
• **09:25。**まだコミットしていないので、選択肢は2つです。git restore（良い部分も含めて全部失う）か、git stashしてから必要な部分を選ぶか。開発者はstashを選び、良い部分を残して、残りをもっと簡潔にやり直すようエージェントに頼みます。
• **10:10。**エージェントが2回目のコミットをします。開発者はこのコミットがテストを1つ壊すと気づき、git revert HEADを実行します。履歴は残り、関数は元どおりになります。
• **10:30。**開発者は差分を読んだうえでmainにマージします。

やるべきこと：**早めにコミットし、受け取る前に差分を読み、restoreやresetよりstashやrevertに慣れておく。**この例は何も証明しません。証拠は上の文書にあり、覚えておく価値のある実際の事例にもあります。2025年の報道によると、ある創業者の試行の中で、エージェントがコードフリーズ中にもかかわらず本番データベースを削除したとされます。出典の間では復旧の可否など詳細が食い違い、情報の多くは当事者によるものです。伝えられたとおりなら、これはファイルではなくデータベースの話であり、Gitのセーブポイントが守る範囲の外です。

8. 明日から使える習慣#

8.1 任せる前と受け取る前の8つの質問#

1. 今、この作業専用のブランチにいますか。それともmainですか。
2. 任せる前に、git statusはきれいですか。保存していない作業途中のものはありませんか。
3. エージェントはGitのルール（専用ブランチ、小さなコミット、pushしない）を知っていますか。
4. エージェントの作業後、git statusとgit diffを読みましたか。
5. 頼んでいないファイルが変更されていませんか。
6. 差分に鍵やパスワードに見えるものはありませんか。
7. この変更を捨てるなら、stash、restore、revertのどれを使い、未コミットのものを失っていませんか。
8. この作業はリポジトリの外（データベース、メール、API）に触れますか。

8.2 今すぐできる3つのこと#

1. 5.2の5行のブロックを、お使いのツールの指示ファイルに貼る。
2. 練習用のリポジトリで一度試す。reset --hard、reflog、元に戻す。本番で慌てないために。
3. お使いのコード管理サービスに機能があれば、mainブランチの保護を有効にする。

9. バランスよく見る：Gitにできること、できないこと#

**できること：**セーブポイントを与え、壊れる心配なく試せるようにし、ワークツリーで複数の作業を並行させ、エージェントのあらゆる変更を読める差分にします。

できないこと：

• リポジトリの外のものは守れません。データベース、送ったメール、動いたお金。
• 未コミットの変更は救えません。
• エージェントが悪いことをするのを止めるのではなく、起きた後に戻れるようにするだけです。防ぐには権限とルールが必要です。
• Gitの学習にはコストがあります。初心者には、この記事のいくつかのコマンドで始められます。マージの衝突のような込み入った場面には、さらに学ぶ時間が要ります。
• 各習慣の効果を測った対照実験は見つけられませんでした。チームで試して調整してください。

**誇張しない：**Gitは安全スイッチではありません。**軽く見ない：**エージェントをファイルに使うときの事故の多くは、セーブポイントが近くにあれば「20分失った」程度に収まります。

10. 結論#

エージェントは速く、間違えるときも速いです。作業ごとにブランチを分け、こまめにセーブさせ、受け取る前に差分を読み、戻る道を4つ覚えておきましょう。未コミットの分にはrestore（本当に失うと理解したうえで）、コミット済みにはrevert、うっかりの後の救出にはreflog、エージェントごとの専用の机にはworktreeです。セーブポイントはエージェントの間違いを減らしませんが、あなたの不安を減らします。

参考資料#

コマンドと事実は、公開文書と、2026年10月30日に動かした練習用リポジトリ（Git 2.56.0）に基づいています。Replitの件の報道は、おもに当事者の投稿を伝えたものなので、引用の前に原文を開いて確認してください。

• Git、git-restore、git-revert、git-reflog、git-worktree
• Anthropic、CheckpointingとCommon workflows、Run parallel sessions with worktreesの節
• Tom's Hardware、AI coding platform goes rogue during code freeze and deletes entire company databaseとheise（2025年7月）
• Conventional Commits、Specification 1.0.0

チームリーダー、フリーランス、小さな会社の経営者、数人のチームで仕事にAIを使う人なら誰でも、初心者の方でも読めます。法務やセキュリティの知識は不要です。用語にはどれも身近なたとえを添えています。計算の部分は印をつけてあるので、不要なら読み飛ばせます。

これは法的助言ではありません。 数字は公開情報から取っており、末尾に一覧があります。一部は報道を通じてしか読んでいません。「例」と書いたものは作った例で、実在の人物や会社には触れていません。AIの内部はまだ誰にも完全には分かっていないので、たとえは覚えやすくするための補助です。ひな形は私の実務上の提案で、義務的な基準ではありません。

まず要点#

• 少人数チームでは、AIについての決まりがないことがよくあります。Stack Overflow 2026年調査を伝える報道によると、AI利用を個人任せにしている回答者は約29.7%、承認済みツールや正式な方針があると答えた人は約24%でした。報道を通じて読んだ数字です。
• 最大のリスクは、AIが間違えることより、入れてはいけないデータを誰かが貼り付けてしまうことであることが多いです。2023年にBloombergの報道とそれを伝える報道によると、Samsungの従業員が社内のソースコードをChatGPTに入力したと伝えられ、同社は生成AIツールを制限しました。
• 始めるには1ページで足ります。3列（使ってよい、先に相談、禁止）、やさしい言葉で書くデータの4段階、承認済みツールの一覧、AIが書いた変更ごとの責任者1人、事故の手順、見直し日です。
• ポリシーの試し方：先週の実際の作業を20件選び、3列に振り分けます。「先に相談」に入る数が多すぎるなら、厳しすぎるか曖昧すぎます。
• 厳しすぎると抜け道を探され、曖昧だと誰も何をすればよいか分からず、誰も読まなければ無いのと同じです。それぞれの見分け方を示します。
• ポリシーは安全の保証ではありません。やるべきことを明確にし、責任を持つ人を決めるだけです。

むずかしい言葉をやさしく#

1. まずイメージ：共用キッチンの貼り紙#

6人で使う共用キッチンを思い浮かべてください。分厚い規則集を読みたい人はいません。でも何もなければ、生ものと加熱済みの食べ物に同じまな板を使う人や、期限切れの食品を冷蔵庫に置きっぱなしにする人が出てきます。冷蔵庫の扉に貼った紙1枚で十分です。これは自由に使ってよい、これは先に聞く（たとえば大家さんの圧力鍋）、これは絶対にしない（外出時にガスをつけたままにする）。短い紙は読まれます。見直し日があれば古くなりません。担当者の名前があれば、聞く相手がいます。

少人数チームのAI利用ポリシーも同じです。目的はあらゆる場面を網羅することではなく、よく出る質問に、全員が同じ答えを持てるようにすることです。これをここに貼ってよいか、AIが書いたものを誰が読み直すか、うっかりしたらどうするか。

ここから分かること： 少人数チームにとってよいポリシーは、引き出しの中のバインダーではなく、冷蔵庫の扉の貼り紙です。

2. なぜ必要か：データで見る2つのこと#

2.1 ほとんどのチームにはまだ決まりがない（Stack Overflow 2026年調査、報道経由）#

Stack Overflow Developer Survey 2026を伝える報道（IT Brief）によると、職場でのAI利用は任意で個人に任されていると答えた人が約29.7%、雇用主が承認済みツールや正式な方針、ガイダンスを持つと答えた人は約24%にとどまります。この数字は報道を通じて読んだだけで、調査ページの表とは照合していません。標本は回答した人たちで、すべての少人数チームを代表するわけではありません。正確な数字ではなく「ないところがかなりある」と読んでください。

ここから分かること： あなたのチームにポリシーがなくても珍しくはなく、この空白はあなたのところだけの問題ではありません。

2.2 報じられた事例：ソースコードがチャットボットへ（Samsung、2023年）#

2023年5月初めのBloombergの第一報と、それを伝える報道（Forbes、TechRadar）によると、Samsungのエンジニアはソースコードの問題を扱うのにChatGPTを使い、4月ごろに社内のソースコードを入力したと伝えられました。同社はその後、社内のパソコン、スマートフォン、ネットワークでの生成AIツールの利用を制限する通知を出し、会社の知的財産が危険にさらされない限り個人端末では使えるとし、違反は処分の対象になりうると述べました。これらの報道によると、通知は漏れたコードの中身には触れていません。制限が一時的か長期的かについても情報源の間で食い違いがあり、私はBloombergの原文を開けていないので、「報道によると」の範囲にとどめてください。

大事なのは大企業の名前ではありません。腕のよいエンジニアがいる場所で起きたということです。ごく普通の作業（バグをチャットボットに見てもらう）と、ごく普通の習慣（コードを貼る）が重なるだけで起こります。

ここから分かること： リスクはデータを貼るという行為にあり、どのデータを貼ってはいけないかを言い切るルールが要ります。

3. 1枚の紙：3列と7つの項目#

冷蔵庫の扉に貼った紙を思い浮かべてください。緑、黄、赤の3列に分け、各列に数行ずつ書きます。

3.1 3列#

• 使ってよい（聞かなくてよい）：承認済みツールを、公開データと社内データで使い、説明、下書き、テスト作成、名前の変更、文書作成などをする。
• 先に相談： 一覧にないツールを使う、顧客データをどのツールにも入れる、エージェントにインストール、削除、デプロイのコマンドを実行させる、顧客がAIを使わないでほしいと言った作業でAIを使う。
• 禁止： キー、パスワード、トークン、実際の個人データを貼る、顧客のデータに個人の無料アカウントを使う、第二の人が読んでおらずチェックも走らせていないAI作成コードをマージする。

3.2 やさしい言葉で書くデータの4段階#

4つの置き場所がある家を思い浮かべてください。

3.3 残りの7項目#

1. 承認済みツール： 名前、アカウントの種類、承認者、日付、データに関する規約を読んだか。
2. 誰が結果を確認するか： AIが書いた変更は、すべて第二の人が読みます。AIの結果に証拠を添えさせる5つの方法の「証拠の求め方」を使うと、読む人が速くなります。
3. 誰が責任を負うか： マージする、または顧客に送る人が答えます。AIが間違えたら、誰が責任を取るかも参照してください。
4. 顧客への伝え方： いつ、何を、契約に沿って伝えるか。
5. 記録： 新しいAI利用は1行だけ。ツール、目的、データの段階。
6. 事故のとき： 第6章の短い手順。
7. 見直し日： 多くの場合90日後ごろ。担当者の名前つき。

3.4 貼って直せるひな形#

チーム[チーム名]のAI利用ポリシー
担当：[名前]    施行日：[日付]    見直し：[日付 + 90日]

使ってよい（聞かなくてよい）
- 下の一覧のツールを、公開データと社内データで使う。
- AIに説明、下書き、テスト作成、名前の変更、文書作成を頼む。

先に相談
- 一覧にないツールを使う。
- 顧客データをどのAIツールにも入れる。
- エージェントにインストール、削除、デプロイを実行させる。
- 顧客がAI不使用を求めた作業でAIを使う。

禁止
- キー、パスワード、トークン、実際の個人データを貼る。
- 顧客のデータに個人の無料AIアカウントを使う。
- 第二の人が読み、チェックを走らせる前にAI作成コードをマージする。

データ：公開 / 社内 / 顧客 / 機密（例は3.2）
承認済みツール：[名前、アカウントの種類、承認者、日付]
責任者：マージする、または顧客に送る人
顧客への伝え方：[いつ、どのように]
記録：新しいAI利用を1行（ツール、目的、データの段階）
事故：止める、1時間以内に報告、したことを書き留める、漏れたらキーを交換、必要なら顧客に伝える

4. 6人チームの例（想定）#

これは作った例で、実在の会社には触れていません。契約でソフトウェアを作る6人のチームを思い浮かべてください。数社の顧客を持っています。彼らはひな形を次のように埋めます。

• 承認済みツール： チームの有料サービス1つ。アカウントはリーダーが作成し、承認者がチームのデータを学習に使うかどうかの規約を読んでいます（選んだサービスの実際の規約を読む必要があります）。個人の無料アカウントは一覧に入りません。
• 先に相談： 顧客データに触れる作業すべてと、エージェントにインストールやデプロイを許すたび。
• 顧客への伝え方： 見積書に、チームはコード作成の補助にAIを使うこと、変更はすべて人が読むこと、顧客のデータは同意なしにはツールに入れないことを書きます。
• 見直し： 90日ごと。リーダーが担当。

4.1 試し方：実際の作業20件を3列に振り分ける（想定、読み飛ばし可）#

ポリシーを試す方法：各自が先週AIを使った実際の作業を挙げ、チームで3列に振り分けます。以下の数字は計算しやすいように作ったもので、実測ではありません。

tasks, people, minutes_per_ask = 20, 6, 3
allowed, ask, banned = 12, 6, 2
print(allowed / tasks, ask / tasks, banned / tasks)
# 0.6 0.3 0.1
weekly = tasks * people            # チーム全体で週120件
asks = weekly * ask / tasks        # 相談が36回
minutes = asks * minutes_per_ask   # 108分
print(weekly, asks, minutes, minutes / 60)
# 120 36.0 108.0 1.8

結果の読み方：20件のうち12件（60%）はそのまま進め、6件（30%）は相談が要り、2件（10%）は禁止です。6人が1週間に20件ずつなら、相談は約36回、約108分、チーム全体で週およそ1.8時間です。もし20件中12件（60%）が「先に相談」に入ると、同じ計算で相談は72回、週3.6時間になり、人は聞かなくなります。

はっきり言っておくと、1回3分と12、6、2の内訳は仮定です。「先に相談は作業の約3分の1を超えないほうがよい」という目安は私の経験則で、どの研究の実測でもありません。自分のチームの実際の作業で試して、調整してください。

5. ポリシーが失敗する場所#

決まり書きを思い浮かべてください。長すぎれば誰も読まず、厳しすぎれば人はこっそり料理し、曖昧すぎれば各自が好きに解釈します。

5.1 例：ポリシーがある朝とない朝#

これは想定の場面で、実在の人物や製品には触れていません。

• 10:00。 開発者が、顧客向けに出力したレポートのバグを探す必要があります。エラーログには顧客のエンドユーザーのメールアドレスと名前が含まれています。
• 10:05。 誰も駄目と言っていなかったので、開発者はログをそのまま、個人の無料アカウントで公開チャットボットに貼ります。
• 10:30。 貼った部分に実際のメールアドレスがあると気づきます。手順がないので、開発者は黙っています。
• 翌週。 顧客が、自分たちのデータがどこへ行ったのか尋ねます。誰も答えを持っていません。

ポリシーがある場合： 10:05に「顧客データは先に相談」の一行があるので、開発者はリーダーにメッセージを送ります。二人でログからメールアドレスを取り除き、承認済みのツールを使い、1行だけ記録します。それでも貼ってしまった場合は、「1時間以内に報告」の手順のおかげで早く対処できます。何を貼ったかを書き留め、キーがあれば交換し、必要なら顧客に伝えます。

やること：事故の項目は、事故が起きる前に書いておきます。慌てているときに手順を思いつく人はあまりいません。

この例は証拠ではありません。上で述べたSamsungの件は同じ種類の行動の実例で、Stack Overflow 2026年調査（報道経由）はポリシーの空白がよくあることを示唆します。技術的なリスクはAIアプリのOWASP Top 10も参照してください。

6. 事故が起きたとき：短い5つの手順#

1. 止める： そのツールでの作業をやめる。
2. 1時間以内に報告： 責任者に。事故かどうか確信がなくても。
3. 書き留める： 何を、どのツールに、いつ入れたか。
4. 対処する： キーが漏れたなら交換し、ツールが許せば会話を削除し、データの保持について提供元に尋ねる。
5. 契約や法律が求めるなら顧客に伝え、学んだことをポリシーに戻す。

「ひやっとした」だけの場合の報告も認めます。報告したら罰せられるなら、人は黙ります。

7. 数字、標準、法律：どう読むか#

法律面について： 私が見つけた情報源によると、この法律は2025年12月10日に国会で可決され、2026年3月1日に施行されます。導入者とは、職業、商業、サービス提供の活動でAIシステムを使う組織または個人と定義され、個人的で非商業的な目的の利用はこの範囲に入りません。各当事者の具体的な義務、施行細則、経過期間は確認していません。AIを使った製品やサービスを顧客に提供するチームは、法律の全文を読み、法務の専門家に相談してください。この記事は、何を聞くべきかを知る助けになるだけです。

公平に読むと： 上の情報源は、明確な決まりと責任者の存在を支持しています。1ページのポリシーが事故をどれだけ減らすかを測った研究は見つかりませんでした。ここでのひな形は実務の総合です。

8. 明日から使える習慣#

8.1 ポリシーを貼る前の8つの質問#

1. ポリシーは1ページに収まっていますか？
2. 3列に、概念だけでなく具体例がありますか？
3. データの4段階に、チームになじみのある例がありますか？
4. 日付と承認者つきの承認済みツールの一覧がありますか？
5. AIが書いた変更はすべて、第二の人が読んでいますか？
6. 責任者の名前とポリシーの担当者の名前がありますか？
7. 事故の手順が書かれていて、ひやっとした場合の報告も認められていますか？
8. 見直し日が決まっていますか？

8.2 今すぐやる3つのこと#

1. 30分かけて3.4のひな形を埋め、チームに不要なものは削る。
2. 4.1の20件の試しを、先週の実際の作業で行う。
3. 90日後ごろに見直し日を置き、担当者の名前を書く。

9. バランスよく見る：ポリシーにできること、できないこと#

できること： 繰り返し出る質問に全員が同じ答えを持てるようにし、新人に何をすればよいかを伝え、うっかりしたときに報告できる場を作り、顧客に聞かれたときの記録を残します。

できないこと：

• ポリシーは安全の保証ではありません。人は間違えて貼ることがあり、ツールは規約を変えることがあります。
• 1ページのポリシーの効果を測った研究は見ていません。相談の回数とひやっとした件数を自分で記録してください。
• 紙1枚は、教育、チェックのツール、間違いを報告できる文化の代わりにはなりません。
• 顧客にサービスを提供するチームや個人データを扱うチームにとって、1ページは出発点であり、法的義務のすべてではありません。

誇張しない： すべてのチームに合うひな形はありません。軽く見ない： ポリシーの空白は顧客に聞かれたときに表に出ますが、そのときはもう書くのに遅すぎます。

10. まとめ#

少人数チームに分厚い規則集は要りません。冷蔵庫の扉の貼り紙1枚で足ります。使ってよい、先に相談、禁止、データの4段階、責任者1人、問題が起きたときの5つの手順、見直し日。30分で下書きし、実際の作業20件で試し、90日後に直してください。

参考資料#

数字は2026年10月時点の公開情報によります。一部は報道や二次的な要約を通じてしか読んでいないので、引用する前に原典を開いて確認してください。法的助言ではありません。

• Stack Overflow、2026 Developer Surveyと調査についてのIT Brief報道（29.7%と24%の数字の出どころ）
• Samsungの生成AI制限の報道（2023年5月）：Forbes AustraliaとTechRadar（Bloombergの報道を伝えるもの）
• NIST、AI Risk Management Framework（AI RMF 1.0、2023年1月）
• ISO、ISO/IEC 42001:2023
• 人工知能法（法律番号134/2025/QH15）（Thu Vien Phap Luat）とBaker McKenzieの概説（頼る前に全文を読んでください）

コードを書くチームで働く人なら誰でも、新人の方でも、AIエージェントに作業を任せている方でも読めます。ソフトウェア設計の知識は不要です。用語にはどれも身近なたとえを添えています。計算の部分は印をつけてあるので、不要なら読み飛ばせます。

数字は公開情報から取っており、末尾に一覧があります。「例」と書いたものはこの記事のために作った例で、実在の人物や会社には触れていません。AIエージェントが文書を内部でどう読み、どう使うのかは、まだ誰にも完全には分かっていません。以下のたとえは覚えやすくするための補助です。AIに関する助言は実践の整理であり、対照実験の結果ではありません。

まず要点#

• プロジェクトで一番難しいのは、コードそのものよりコードの裏にある理由であることが多いです。理由は一部の人の頭の中にあり、その人たちと一緒にいなくなります。
• ADR（architecture decision record、決定記録）は、決定を1つ、背景、決定、結果、状態とともに残す短い1ページです。2011年にMichael Nygardが提案し、長さは1〜2ページを勧めています。
• 理由を知らない新人には、2つの道しかありません。理解せずに受け入れるか、結果を知らずに覆すかです。どちらも良くありません。Nygardはまさにこの2つを挙げています。
• AIエージェントも似た状況になりえます。「遠回り」なコードを見て整理してしまい、その遠回りが意図的だったことを知りません。エージェント向けの指示ファイルからリンクされたADRは、修正の前に確認できる場所になります。
• よいADRは1ページで足ります。未来の読み手に向けて、却下した案と、受け入れた代償を書きます。貼って使えるテンプレートも載せました。
• ADRはすべての変更に必要な儀式ではありません。小さくて簡単に戻せる決定には不要です。また、状態を更新する人と、読む人がいてはじめて役に立ちます。

むずかしい言葉をやさしく#

1. まずイメージ：レシピのメモ#

レシピ帳のあるレストランを思い浮かべてください。スープのページには「塩は入れない。最後にナンプラーで味を整える」とあります。入ったばかりの調理補助の人は、薄いと感じて塩を足します。その日、塩を控えているお客さまがスープを注文します。誰にも悪意はありません。レシピ帳に足りなかったのは1行、「なぜ塩を入れないか」だけです。

では、その1行があるとします。「塩は入れない。この料理は食事制限のあるお客さまにも出すため。塩はお客さまが卓上で足す」。補助の人は読んで納得できますし、お店の方針が変われば、直す場所もあります。

ADRは、そのメモのコード版です。そしてAIエージェントがリポジトリに入ってきたとき、「塩を足す」前に読めるメモになります。

ポイント： 残すべきものは分厚い本ではなく、覚えておく価値のある決定ごとの理由です。誰かが読める短さにします。

2. ADRとは何か：出典から#

2.1 Michael Nygardの原典（2011年）#

Michael Nygardは、2011年11月15日にCognitectのブログに載せた「Documenting Architecture Decisions」で、アーキテクチャの決定にはしばしば理由の記録がないと書いています。新しくプロジェクトに入った人には道が2つしかありません。理解せずに決定を受け入れるか、結果を知らずに覆すかです。どちらもプロジェクトを傷つけうるし、説明のない決定が多すぎるとチーム全体が何も変えるのを怖がるようになる、と述べています。

各記録は次の5つの部分から成る、と提案しています。

• タイトル：短い名詞句。
• 背景：決定に働く力（技術、政治、社会、プロジェクト固有）を、判断を入れずに事実として書く。
• 決定：完全な文、能動態、「私たちは〜します」で始める。
• 状態：関係者が合意するまでは「提案中」、その後「承認済み」。のちに「非推奨」や「置き換え済み」になることもあり、置き換え先へのリンクをつける。
• 結果：決定後の状況。良い影響、悪い影響、どちらでもない影響を含める。

長さは1〜2ページ。文体は、未来の開発者と会話するつもりで、完全な文で書きます。箇条書きはレイアウトのために使い、文を断片に置き換えないこと。保存場所はプロジェクトのリポジトリで、たとえばdoc/arch/adr-NNN.md。番号は連番で、再利用しません。覆された決定は削除しません。古い記録を残し、置き換え済みと印をつけます。

Nygardは使った経験も書いています。複数のプロジェクトで約3か月使ったあと、それらを行き来した6〜10人の開発者が、記録の背景の部分に価値があると話した、とのことです。これは著者自身の報告で、小さな集団であり、対照実験ではありません。

2.2 MADR：よく使われるMarkdownのテンプレート#

MADR（Markdown Architectural Decision Records）は、Markdownで書く軽いテンプレートです。公式ページによると、構成は次のとおりです。タイトル、任意の先頭情報（状態、日付、決定者、相談した人、知らせた人）、背景と課題、任意の判断要因、検討した選択肢、決定の結果（良い結果と悪い結果を含む）、任意の遵守確認、各選択肢の長所と短所、補足情報（見直す条件も書ける）。保存の慣習は、docs/decisionsというフォルダにNNNN-title-with-dashes.mdという名前で連番にすることです。ページが説明している最新版は2024年9月17日公開の4.0.0で、MITまたはCC0のデュアルライセンスです。

2.3 Y-statement：1文のADR#

Y-statementは、Olaf Zimmermannと関係する著者たちによって広まった短い形で、次のパターンの1文です。「（状況）において、（懸念）に直面し、私たちは（選択肢）を選び、（他の選択肢）は選ばず、（品質目標）を達成するために、（代償）を受け入れた」。私が読んだ出典では、つなぎの言葉が少しずつ違うので（「and against」や「and neglected」）、厳密な規格ではなくパターンとして扱ってください。Y-statementは単純な決定に向いています。複雑な決定には、MADRやNygard版のような、より詳しい形式が勧められています。

ポイント： ADRは複雑な道具ではありません。核は4つの問いです。どんな状況にいるか、何を選ぶか、何を捨てるか、何を失うことを受け入れるか。

3. なぜチームは決定を失い、AIでなぜそれが目立つのか#

3.1 Stack Overflow 2026調査のデータ#

Stack Overflow Developer Survey 2026の結果ページには、文脈に関する困りごとの項目があります。私が読んだ要約では、回答者の約60.9%が「重要な文脈が人の頭の中にある」、56.5%が「情報が古い」、53.4%が「情報が多すぎるツールに散らばっている」、63.2%が「情報が不完全」と答えています。要約を通して読んだだけで、各表との照合はしていません。元の質問は技術的な決定より広いかもしれず、回答者は調査に答えた人たちです。ですからこれは、チームの知識は散らばりがちという一般的なシグナルであり、ADRについての証拠ではありません。

3.2 AIエージェントの場合：コードは見えるが、理由は見えない#

エージェントを、とても速いけれど今日入ったばかりの同僚だと思い浮かべてください。コード全体を数秒で読めますが、先週の会議は覚えていません。遠回りなコードを見ると、単純にするのが自然な反応です。その遠回りが理由のある決定の結果なら、止められるのは、探す場所に書かれた理由だけです。

はっきり言っておくと、ADRを文脈に入れるとエージェントが決定を覆す回数がどれだけ減るかを測った研究は、私は見つけられませんでした。これは実践上の考え方で、エージェントが読む場所に必要なことを置くという、記事AIの取扱説明書：AGENTS.mdの考え方につながります。

3.3 自分で確かめられる計算（例、読み飛ばし可）#

これは作った数字の例で、実測ではありません。6人のチームが月に2つ決定を記録し、各ADRは300語、技術文書を読む速さは1分150語（仮定）とします。1年で24件のADRがたまります。

adr, words, wpm = 24, 300, 150
read_all = adr * words / wpm          # 7200語、つまり48分
index = adr * 12 / wpm                # 24個のタイトル、1行12語、つまり288語、約2分

asked, explain = 5, 15                # 新人が5つの決定を聞き直し、先輩が1回15分で説明
without = asked * explain             # 先輩の時間75分
with_adr = asked * words / wpm        # ADR5件 x 2分 = 新人の時間10分
print(read_all, round(index, 2), without, with_adr)
# 48.0 1.92 75 10.0

newcomers = 4
print(newcomers * without, newcomers * with_adr)
# 300 40.0  （1年あたりの分）

結果の読み方：24件のADRをすべて読むと約48分、タイトルの一覧だけなら約2分なので、全部を読み込む必要はありません。新人が5つの決定を聞き直し、先輩が1回15分で説明すると、1人あたり先輩の時間で75分、新人4人なら年300分です。ADRがあれば、新人は5件を1人あたり約10分で読めるので、年40分です。

念のため：300語、1分150語、5つの質問、15分は私の仮定です。ADRにも書く時間と更新する時間がかかりますが、ここには含めていません。自分のチームの数字に置き換えてください。

4. 1ページのテンプレート#

提出用紙を思い浮かべてください。欄は少なく、どの欄も必須で、10分で埋められる小ささです。以下のテンプレートはNygard版をもとに、MADRの考え方から2つの欄（見直す条件と確認方法）を足したものです。決定に出口と確認手段を持たせるためです。

# ADR 0007: リマインドはキュー経由で送る

状態: 承認済み（提案中 / 承認済み / ADR 00NNに置き換え済み）
日付: 2026-03-12
決定者: 名前または役割

## 背景
状況と制約を、判断を入れず事実として書く。誰が何を待っているか。

## 決定
私たちは〜します（1〜2文の完全な文、能動態）

## 却下した案
- 案A：選ばなかった理由。
- 案B：選ばなかった理由。

## 結果
- 得るもの：良いこと。
- 失うもの：受け入れた代償。
- どちらでもない：変わるだけで、良くも悪くもないこと。

## 見直す条件
決定を見直すきっかけになる具体的な条件。

## 確認方法
決定が守られていることを示す、自動チェックや観察できる兆候。

1ページに収める3つのルール：

1. ADR1つに決定1つ。 タイトルに「と」が必要なら、2つの決定かもしれません。
2. 背景と決定は完全な文で。 箇条書きは、案や結果のような短い一覧だけにします。
3. 長い詳細は別の場所に。 比較表、グラフ、実験結果は、貼らずにリンクします。

5. 記入例：書き上げたADR#

これはこの記事のために作った例で、実在の会社や製品には触れていません。状況：小さなアプリが、サービス業の店の予約を助け、リマインドのメールを送ります。例の数字はすべて架空です。

# ADR 0007: リマインドはリクエスト処理中ではなくキュー経由で送る

状態: 承認済み
日付: 2026-03-12

## 背景
お客さまが予約すると、アプリはリクエストの処理中に確認メールを送っている。
メール送信サービスは、ときどき応答に数秒かかり、一度は1時間停止した。
その間は予約ページが固まり、予約ボタンを2回押したお客さまもいた。

## 決定
私たちはメール送信をジョブキューに入れます。予約のリクエストは、予約を
データベースに書き込んですぐに応答するだけにします。別のワーカーがメールを
送り、最大3回まで再試行します。

## 却下した案
- リクエスト内で直接送る：一番単純だが、サービスが遅いとページが固まる。
- 1分ごとの定期ジョブで表を走査する：キューは不要だが、メールが最大1分遅れ、
  大きな表を走査する。

## 結果
- 得るもの：予約ページが速く応答し、メールの失敗が予約を壊さなくなる。
- 失うもの：監視する部品が1つ増え、メールが数秒遅れることがある。
- どちらでもない：デバッグ時に読むログの種類が1つ増える。

## 見直す条件
6か月間、1日のメール送信数が50通を下回る場合、または
メール事業者が組み込みのキューを提供した場合。

## 確認方法
予約のリクエストがメール送信サービスを直接呼ばないことを確かめるテスト。

同じ決定のY-statement版：「予約受付という状況で、遅くて失敗しやすいメール送信サービスに直面し、私たちは送信をキューに入れることを選び、直接送信や定期的な表の走査は選ばず、予約ページを常に速く保つために、監視する部品が1つ増えることを受け入れた。」

完全版は日本語で約550字、1ページに収まる長さです。注目してほしいのは、「却下した案」の欄が、人もAIも一番単純な案に戻ってしまうのを防ぐという点です。一番単純な案は、誰もが最初に思いつくものだからです。

6. AIエージェントが読めて使えるようにADRを書く#

次の当番の人にメモを残すところを思い浮かべてください。メモは、その人の目に入る場所に貼ってはじめて役に立ちます。

1. ADRはリポジトリに置く。 たとえばdocs/adrフォルダに、コードと変更履歴と一緒に置きます。
2. 索引ファイルを用意する。 各ADRのタイトル、状態、パスを1行ずつ並べます。エージェントは索引を読んで関係する記録を開くので、全部を読み込まずに済みます。
3. エージェントの指示ファイルからリンクする。 AGENTS.mdやツールの指示ファイルに、下のブロックのような数行を足します。
4. 状態は1行目に、決まった言葉で書く。 提案中、承認済み、置き換え済みなど。人にも機械にも絞り込めます。
5. 最初の2つの欄は人が書く。 背景と決定は人が埋めます。AIは却下した案の提案や下書きはできますが、もっともらしい理由が本当の理由とは限りません。理由は人が確認します。記事AIの結果に証拠を求める5つの方法の考え方と同じです。

## 既存の決定
- docs/adrで扱われているやり方を変える前に、索引docs/adr/README.mdを読み、
  関係するADRを開くこと。
- 変更が承認済みのADRに反する場合は、自分で直さず、手を止めて質問すること。
- 完了を報告するときは、どのADRを読んだかを書くこと。

3行で、人もエージェントも全部読める短さです。最後の行は、証拠の記事の4つ目の方法、つまり「読んだこと」と「仮定したこと」を分ける考え方を借りています。

7. ADRのライフサイクル#

一番大事な点：古い記録を削除しないこと。 読む人は、かつて何を決めたかと、なぜ変えたかの両方を見る必要があります。

8. ADRを書かないほうがよいとき#

これは私の経験則で、NygardやMADRの規格ではありません。台所のごみ箱を思い浮かべてください。何にでも専用のノートがいるわけではありません。

• 書かない： 1時間ほどの作業で元に戻せる決定（変数名の変更、ファイル名の選択）。
• 書かない： 理由がツールの標準ドキュメントにあり、誰でも調べられる場合。
• 書かない： 手続きを満たすためだけに書く場合。誰も読まないADRは、手間がかかるだけで役に立ちません。
• 書く： 新人が「なぜこうなっているのか」と聞きそうなとき、決定を覆すのに半日以上かかるとき、誰もが最初に思いつく案をちょうど却下したとき。

9. ADRにも弱いところがある#

レシピ帳を思い浮かべてください。分厚くて誰も開かないもの、何年も前から間違ったままのものがあります。

9.1 例：ADRがある朝とない朝#

これは例（想定）で、実在の人物や製品には触れていません。5章の例を使っています。

ADRがない場合：

• 09:00。 開発者がエージェントに頼みます。「予約まわりのコードを整理して、余分な部分を減らして」。
• 09:20。 エージェントはメールのキューを余分な層と見なし、直接呼び出しに変えます。既存のテストはすべて通ります。
• 11:00。 開発者は差分を読み、妥当だと思ってマージします。
• 15:30。 メールサービスが遅くなります。予約ページが固まり、お客さまが2回予約します。

ADRがあり、AGENTS.mdがそれを指している場合：

• 09:00。 同じ依頼です。
• 09:10。 エージェントはADRの索引を読み、ADR 0007を開いて言います。「このキューは承認済みの決定です。変更しません。置き換えるための新しいADRを作りますか」。
• 09:20。 開発者が答えます。「そのままで。ほかの部分だけ整理して」。
• 09:50。 エージェントは変更を提出し、「ADR 0007を読み、キューには触れていません」と書きます。

どちらの場合もすべきことは、エージェントが余分に見えるものを消そうとする時点で止まり、それに理由があるかを聞くことです。これは例なので何も証明しません。Stack Overflow調査のシグナル（3章）とNygardの報告が示すのは、文脈の欠如が実際にあること、そして短い記録が助けになりうることだけです。

10. 使った数字と文書#

正しく読むために： 上の出典は、短い理由を残すことを支持しています。ADRが誤りを減らす、あるいはAIエージェントが決定を覆すのを防ぐことを直接測った対照実験は、見つかっていません。この記事のAIに関する部分は、実践の整理です。

11. 明日から使える習慣#

11.1 ADRを確定する前の8つの質問#

1. これは1つの決定か、2つがくっついていないか。
2. 1年後の読み手が、誰にも聞かずに背景を理解できるか。
3. 決定は「私たちは〜します」で始まる完全な文か。
4. 却下した案と、その理由が書いてあるか。
5. 結果に、得るものだけでなく失うものとどちらでもないことも入っているか。
6. 見直す具体的な条件と、確認方法があるか。
7. 状態と日付は1行目にあり、索引は更新したか。
8. AGENTS.mdやREADMEがこのADRを指しているか。

11.2 すぐできる3つのこと#

1. docs/adrフォルダと、空の索引を作る。
2. 新人がよく聞く最近の決定を1つ選び、約15分で最初のADRを書く。
3. 6章の3行を、AIエージェントの指示ファイルに足す。

12. バランスよく見る：ADRにできること、できないこと#

できること： 理由を残す、新人が自分で答えを探せるようにする、エージェントに修正前の確認場所を与える、各決定の代償をチームに言葉にさせる。

できないこと：

• ADRは決定が正しいことを保証しません。そのときに何を考えたかを残すだけです。
• 更新されないADRは、ADRがないより害になることがあります。有効でないことを有効だと言うからです。
• エージェントがADRを読む義務はなく、どの程度従うかを測ったテストも私は見ていません。エージェントに、どのADRを読んだかを報告させて確かめてください。
• ADRは書く手間も維持する手間もかかります。ごく小さなチームや短期のプロジェクトでは、READMEの一文で足りるかもしれません。
• AIが代わりに書いた理由は、流暢でも正しいとは限りません。人が確認する必要があります。

言い過ぎないために： ADRはチーム内の会話の代わりにはなりません。軽く見ないために： 失われた決定のコストは、たいてい最後に来ます。誰かが、それにかつて理由があったことを知らずに覆すときです。

13. まとめ#

コードは何をしたかを示し、ADRはなぜそうしたかを示します。決定の時点で書いた短い1ページに、捨てた案と受け入れた代償を書き、人とAIが読む場所からの道をつけておけば、「理由があったと誰も知らなかった」だけで覆される決定の多くを防げます。まず、新人がよく聞く決定から始めてください。

参考資料#

数字は2026年10月時点の公開情報です。一部は要約を通して読んでいるので、引用する前に元の出典を開いて確かめてください。

• Michael Nygard、Documenting Architecture Decisions（Cognitect、2011年11月15日）
• Architectural Decision Records、adr.github.ioとMADR（バージョン4.0.0）
• Olaf Zimmermann、Y-Statements（1文のADRのパターン）
• Stack Overflow、2026 Developer Survey（要約を通して読んだもので、各表は未照合）

AIエージェントにコードを書かせたり、複数の手順にまたがる作業を任せたりする人なら、初心者の方でも読めます。モデルの仕組みの知識は不要です。用語にはどれも身近なたとえを添えています。計算の部分は印をつけてあるので、不要なら読み飛ばせます。

数字は公開情報から取っており、末尾に一覧があります。「例」と書いたものは作った例で、実在の人物や会社には触れていません。モデルが長い入力を内部でどう扱うかは、まだ誰にも完全には分かっていません。以下のたとえは覚えやすくするための補助です。コマンド名は、読んだ時点のClaude Codeの文書によるもので、他のツールや新しいバージョンでは異なる場合があります。

まず要点#

• エージェントが「覚えて」いるのは、コンテキストウィンドウの中にあるものだけです。あなたの依頼、読んだファイル、コマンドの出力、プロジェクトの指示が入ります。ウィンドウには上限があり、開いたものはすべて場所をとります。
• 複数の研究が、モデルは短い入力より長い入力を安定して使えないことを見つけています。Liuら（2023年）は、必要な情報が先頭か末尾にあるときに結果が良くなりやすく、中ほどにあると落ちることを見つけました。Chromaの報告（2025年7月）は18のモデルを調べ、入力が長くなるほど信頼性が落ちることを見つけました。著者自身、課題は実際の仕事より単純だと述べています。
• 会話が満杯に近づくと、ツールが会話を要約に圧縮することがあります。Claude Codeの文書は、要約はあなたの依頼と主要なコードを残すが、初めのほうの指示の細部は失われうると述べています。
• 本記事の計算例では、長い作業でウィンドウの約91.5%が埋まり、そのうち約43%は終わった古い作業でした。短い引き継ぎメモで新しく始めると、使用量は約8%になります。これは自分で計算し直すための例の数字です。
• 長く守らせたいルールは、会話ではなくプロジェクトの指示ファイルに書きます。無関係な作業に移るなら会話をクリアし、同じ作業で長くなったなら指示つきで圧縮します。
• やり直しにも代償があります。エージェントはファイルを読み直す必要があり、引き継ぎメモが不足したり間違ったりすることもあります。「いつ」の部分は経験則で、測定結果ではありません。

むずかしい言葉をやさしく#

1. まずイメージ：広さが決まった机#

あまり大きくない机で仕事をしているところを想像してください。上司の依頼、何枚かの資料、いくつかの調べものの結果、自分のメモを広げます。最初は机が空いていて、すべてが見渡せます。2時間後には机は紙でいっぱいで、必要な1枚は3枚の下です。それでも仕事はできますが、遅くなり、見落としも増えます。完全に埋まってしまったら、大事な点を新しい紙に写し、机を片づけて続けます。写しには、いくつか細部が欠けているはずです。

エージェントも、かなり似た動き方をします。Claude Codeの文書は、コンテキストウィンドウには会話の履歴、ファイルの内容、コマンドの出力、指示ファイル、自動メモリ、読み込んだスキル、システムの指示が入ると説明しています。作業が進むにつれてウィンドウは埋まっていきます。これは覚えやすくするためのたとえにすぎません。モデルの内部は、机よりずっと複雑なはずです。

教訓：「エージェントが忘れた」のは、怠けているからでも愚かだからでもなく、場所が限られていて、場所をとっているものが必要なものとは限らないからであることが多いのです。机を管理するのはあなたの仕事です。

2. 何が場所をとり、圧縮後に何が残るか#

2.1 場所をとるもの#

Claude Codeの文書によると、何も入力しないうちから、いくつかのものが机の上にあります。指示ファイル、自動メモリ、MCPツールの名前、スキルの説明です。その後は、ファイルを読むたび、コマンドの出力が出るたび、やりとりが1往復するたびに増えていきます。/contextコマンドを使うと、種類別の使用量と減らすための提案が見られます。

2.2 圧縮後に残るもの#

満杯に近づくと、ツールは会話を要約に圧縮します。下の表は、文書の「What survives compaction」の節を、私が読んだ版でまとめたものです。バージョンによって細部は変わりえます。

表から言えることは2つです。ルールが必ず残らなければならないなら、口頭ではなく、プロジェクトのルートの指示ファイルに書くこと。そして何を残すかを自分で決めたいなら、ツールに推測させず、指示つきで意図的に圧縮すること。例：/compact focus on the auth bug fix。

教訓：長く守らせたいルールは、机の上の紙の山ではなく壁に貼る決まりごとに属します。その決まりごとの書き方は、AGENTS.mdの書き方を参照してください。

3. 会話が長いとエージェントが悪くなりやすい理由#

300ページの資料を読んだあとで、150ページ目の細部を聞かれたところを想像してください。答えられるかもしれませんが、1ページだけ渡されたときよりずっと難しいでしょう。言語モデルの研究も似たことを示しています。ただし、なぜそうなるのかは、誰も十分には説明できていません。

3.1 Liuら（2023年）：中ほどの情報は見落とされやすい#

著者たち（Percy Liangを含む）は、複数の文書から質問に答える課題と、キーと値のリストから値を取り出す課題を試しました。arXivの概要によると、関連する情報が入力の先頭か末尾にあるときに性能が最も高くなることが多く、長い入力の中ほどにある情報を使わせると大きく下がります。長い文脈に対応すると宣伝されたモデルでも同じです。これは2023年当時のモデルでの実験です。私が読んだ概要ページには個々のモデル名がないため、新しいモデルでは結果が違うかもしれません。

3.2 Chroma（2025年7月）：18モデルで、入力が長いほど信頼性が低下#

Chromaの技術報告（Hong、Troynikov、Huber）は、GPT-4.1、Claude 4、Gemini 2.5、Qwen3の系列を含む18のモデルを、3種類の課題で調べました。拡張版の「干し草の山の中の針探し」、長い会話に対する質問応答（LongMemEval、306問、平均約11万3,000トークン）、単語列の繰り返しです。著者たちは、入力が長くなるほど性能がますます不安定になると書いています。また、邪魔な情報が1つあるだけでも結果が悪くなること、モデルによって反応が異なることも見つけています。彼らによると、Claude系のモデルはあいまいなときに回答を控える傾向があり、GPT系のモデルは邪魔な情報があると誤答が多くなる傾向がありました。

著者自身の言葉もあわせて読んでください。課題は実際の仕事より単純なので、現実ではもっと悪くなりうると考えているものの、長さの影響と課題の難しさの影響を切り分けるのは難しく、報告は仕組みを説明していません。1社の技術報告であり、独立した検証は私は見つけていません。

3.3 Anthropic（2025年9月）：有限な「注意の予算」#

Anthropicのコンテキストエンジニアリングの記事（2025年9月29日）は、context rotという用語を使い、コンテキストを有限の資源として説明しています。追加されたトークンは1つ1つ、モデルの「注意の予算」の一部を使います。記事は、満杯に近づいたら圧縮する、ウィンドウの外にメモを残してあとで読み返す、自分の机を持つサブエージェントを使う、といった方向を提案しています。これはツールを売る会社の技術的な見解であり、対照実験ではありません。

**教訓：**3つの出典は同じ方向を向いています。長いほど良いとは限りません。どの程度か、なぜかは不確かで、モデルによっても違います。

4. 自分で確かめられる計算（例、読み飛ばし可）#

これは作った数字による例で、測定値ではありません。ウィンドウが20万トークンだとします。ある作業は、開始時に読み込まれる1万2,000トークン、1回3,000トークンのファイル読み込み25回、1回1,500トークンのコマンド出力40回、1回600トークンのやりとり60回でできています。

window = 200_000
startup = 12_000
files, file_size = 25, 3_000
cmds, cmd_size = 40, 1_500
turns, turn_size = 60, 600

used = startup + files * file_size + cmds * cmd_size + turns * turn_size
print(used, round(used / window * 100, 1))
# 183000 91.5

# 作業の半分が、終わった古い作業だとする
old = 0.5 * (used - startup)
print(old, round(old / window * 100, 1))
# 85500.0 42.8

# 4,000トークンの引き継ぎメモで新しく始める
fresh = startup + 4_000
print(fresh, round(fresh / window * 100, 1), (window - fresh) // file_size)
# 16000 8.0 61   (3,000トークンのファイルがあと何個入るか)

結果の読み方：長い作業はウィンドウの約91.5%を使い、そのうち約43%は古い作業です。あと入るファイルは約5個だけです（1万7,000を3,000で割る）。4,000トークンの引き継ぎメモで新しく始めると、使用量は約8%になり、あと約61個のファイルが入ります。

はっきり注意しておきます。上のトークン数はすべて仮定で、作業の半分が古い作業だという仮定も含みます。ウィンドウの大きさ、自動圧縮のしきい値、トークンの数え方は、モデルとツールによって違います。この計算は、8%のほうが91.5%より良い結果になるとは言っていません。示しているのは、古い作業がどれだけ場所をとるかだけです。実際の数字は、自分のセッションで/contextを実行して確かめてください。

5. いつ何をするか：整理、圧縮、分割、やり直し#

机を思い浮かべてください。紙を少し脇へ寄せるだけでよいときも、メモを新しい紙に写すときも、別の机へ移ったほうがよいときもあります。

「根拠」の列は、どこが文書にあり、どこが個人の経験かを示しています。「2回の訂正」や「ウィンドウの半分以上」のような具体的な目安を測った研究は、私は見つけていません。出発点として使い、自分で調整してください。

5.1 やり直しを考えてよいサイン#

1. 机の上のほとんどと無関係な作業に移る。
2. エージェントが、伝えたルールを破り、2回目の注意が必要になる。
3. エージェントが同じ箇所を直し続ける、または一度退けた案をまた出してくる。
4. 会話で何が決まったか、自分でも思い出せなくなる（エージェントはなおさら難しい）。
5. 自動圧縮のあと、品質がはっきり変わる。
6. /contextを見ると、場所の大半が終わった作業のコマンド出力とファイルになっている。

6. 引き継ぎメモのひな形（コピーして使えます）#

当直の引き継ぎ帳を思い浮かべてください。次の人が1分読めば続けられるものです。新しいセッションの冒頭に貼るか、プロジェクト内のファイルとして保存して、あとで読み直せるようにします。

## 引き継ぎメモ
目的: <1文>
完了して確認済み: <内容と、実行したコマンドと結果>
作業中: <ファイル、関数、次の手順>
決めたことと理由: <決定を1行ずつ>
試してだめだったこと: <方法と、やめた理由>
してはいけないこと: <境界、触らないファイル>
未確認または仮定: <エージェントが実行せず推測したこと>
確認を再実行するコマンド: <1つのコマンド>

「未確認または仮定」の欄は、AIの結果に証拠を求める5つの方法から取っています。実行したことと推測にすぎないことを分けておけば、新しいセッションが推測を事実として扱わずにすみます。エージェントに下書きを頼み、そのあと自分で読んで直すことができます。AIが書いた要約にも、抜けや誤りがありうるからです。

同じ作業のまま続けるときの、指示つき圧縮のコマンド：

/compact focus on: 現在の目的、決めたこと、編集中のファイル、
確認コマンド、触ってはいけないもの

7. 例：ある朝、2つの進め方#

これは作った例で、実在の人物や製品には触れていません。

会話をクリアしない場合：

• 09:00。 開発者がエージェントに請求書の丸めバグの修正を頼み、「新しい関数名はcalcで始めてください」と伝えます。
• 09:40。 エージェントは25個のファイルを読み、多くのコマンドを実行しました。バグは直り、テストも通ります。
• 10:30。 同じセッションで、開発者は別のページのボタンの色の変更を頼みます。
• 10:45。 エージェントはcomputeColorという名前の関数を追加します。09:00に伝えたルールに反しています。開発者が指摘して直りますが、その後、09:20に退けたはずの方法をまた提案してきます。

クリアして引き継ぎメモを使う場合：

• 09:40。 修正が終わり、開発者はコミットして、短い引き継ぎメモをプロジェクトのメモファイルに保存します。calcのルールは、ルートの指示ファイルにすでにあります。
• 10:30。 開発者は/clearを実行し、はっきりした依頼で新しい作業を始めます。
• 10:45。 エージェントは指示ファイルを読み、最初から正しい名前を付けます。

どちらでもすべきこと：長く守らせたいルールは指示ファイルへ、終わった作業はコミットしてから机を片づける。これは例なので、何かを証明するものではありません。根拠は第3節の研究で、それにも限界があります。古いモデルであること、課題が実際の仕事より単純なことです。あわせてエージェントへの依頼でありがちな7つの失敗も参照してください。

8. この通りにしても弱いところ#

9. 使った数字と文書#

正しく読むために：3つの研究の出典は、どれも「長いほど信頼性が落ちやすい」という方向を示唆しています。一方、「会話をクリアする」「引き継ぎメモを書く」ことで、実際の仕事の結果がどれだけ良くなるかを直接測った対照研究は見つけられませんでした。第5節の目安は経験則です。

10. 明日から使える習慣#

10.1 作業の途中での8つの質問#

1. いまの作業は、机の上のほとんどのものとまだ関係があるか。
2. 必須のルールは、ルートの指示ファイルに入っているか、それとも口頭で言っただけか。
3. /contextで、いちばん場所をとっているものは何か。
4. 終わった作業はコミットして確認したか。
5. 調べるためだけに多くのファイルを読ませる必要があるか。サブエージェントに任せるべきか。
6. 圧縮するなら、何を残したいか（指示として書いたか）。
7. やり直すなら、引き継ぎメモに「未確認または仮定」の欄があるか。
8. はっきりしたサインがあってやり直すのか、それとも習慣でやり直すのか。

10.2 今すぐできる3つのこと#

1. いまのセッションで/contextを実行し、場所をとっている上位3つを書き留める。
2. 何度も繰り返しているルール3つを、ルートの指示ファイルの短いブロックに移す。
3. 第6節の引き継ぎメモのひな形をファイルとして保存し、今週の作業1つで試す。

11. バランスよく見る：やり直しができること、できないこと#

**できること：**古い作業が場所をとる量を減らす、一度退けた案の繰り返しを避ける、決めたことを書き出させる（あとで読む人にも役立つ）、そして大事なルールを指示ファイルに安定して置く。

できないこと：

• より良い結果を保証するものではありません。新しいセッションは、引き継ぎメモに書かなかった細部を失い、エージェントはファイルを読み直すので手間とトークンがかかります。
• 「いつ」の目安について、実際の仕事での測定値は私にはありません。試して比べてください。
• 圧縮、読み直し、しきい値の決め方はツールごとに違い、バージョンでも変わります。今日読んだ文書が数か月後には当てはまらないかもしれません。
• AIが書いた要約も間違うことがあります。

**大げさに言わない：**エージェントの失敗すべてに効く薬ではありません。多くは、ウィンドウの満杯ではなく、あいまいな依頼から来ます。**軽く見ない：**机を誰も見ないまま続く会話は、小さな誤りが積もる場所です。整理は、エージェントが何を忘れたかを推測するよりずっと安く済みます。

12. 結論#

エージェントの記憶は無限ではありません。広さが決まった机の上で作業していて、机が散らかると結果が不安定になりやすいと研究は示唆しています。長く守らせたいルールは指示ファイルへ。同じ作業なら指示つきで圧縮し、作業を変えるならクリアし、やり直すときは自分で読み直した短い引き継ぎメモを持っていきましょう。

参考資料#

数字と説明は、2026年10月時点の公開情報によります。コマンド名とツールの挙動はバージョンで変わるため、引用する前に原典を開いて確認してください。

• Liuら、Lost in the Middle: How Language Models Use Long Contexts（arXiv、2023年7月、第3版は2023年11月20日）
• Hong、Troynikov、Huber（Chroma）、Context Rot: How Increasing Input Tokens Impacts LLM Performance（2025年7月14日）
• Anthropic、Effective context engineering for AI agents（2025年9月29日）
• Anthropic、Claude Codeの文書：How Claude Code works と Explore the context window

AIでコードを書く人、情報を調べる人、AIエージェントに作業を任せる人なら誰でも、初心者の方でも読めます。前提知識は要りません。用語にはどれも身近なたとえを添えています。計算の部分は印をつけてあるので、不要なら読み飛ばせます。

数字は公開情報から取っており、末尾に一覧があります。「例」と書いたものは作った例で、実在の人物や会社には触れていません。AIが内部でどう動いているかは、まだ誰にも完全には分かっていません。以下のたとえは覚えやすくするための補助です。また、記事の5つの方法は、挙げた文書や研究から整理した実務上のまとめであり、一つずつ対照実験で確かめられた技法ではありません。

まず要点#

• AIを使う人の多くは、結果を確かめ直すことに慣れています。Stack Overflowの2026年調査では、回答者の48%が、結果を確かめやすいときにだけAIを信頼すると答え、重要な判断でAIを信頼するのは6.6%でした。
• 「よく読んで、自分で考え直す」確かめ方は、最も手間がかかります。AIが開ける証拠を添えて出せば、確認は「議論全体の組み立て直し」から「具体的な一点を見ること」に変わります。
• 証拠を求める5つの方法：開ける出典、実行できるテストと出力そのまま、小さく分けた変更、実行済み・読んだだけ・仮定の仕分け、他の人が再実行できる手順。
• どの方法にも穴があります。出典は作り話かもしれず、テストはAI自身が通るように書いたものかもしれず、出力は途中で切れているかもしれません。記事では種類ごとの見つけ方を挙げます。
• 記事の計算例では、主張が8つある要約を確かめるのに、証拠がなければ約48分、あれば約18分かかります。これは例として作った数字で、自分のチームの数字で計算し直せます。
• 証拠は保証ではありません。確認を安くしてくれますが、それを見て判断できる人は必要です。

むずかしい言葉をやさしく#

1. まずイメージ：車の整備票#

車を整備工場に持っていったとします。作業員が「できましたよ、よく走りますよ」と言います。確かめる方法は、運転してみて祈ることくらいです。次に、作業員が整備票を渡してくれたとします。前のブレーキパッドを交換し、店の裏の坂道で時速30kmからブレーキを試し、制動距離は普通でした。ブレーキオイルの系統はまだ見ていません。同じ作業員でも、何をして、何を試し、何にまだ触れていないかが分かります。

AIも同じです。「完了しました、テストはすべてパスしています」という一文は、確かめる手がかりをほとんど与えてくれません。信じるための材料にしかなりません。Claude Codeの使い方の文書は、まさにこの点を説明しています。エージェントは作業が終わったように見えたところで止まり、試すものがなければ「終わったように見える」ことしか頼りがありません。すると人間がテストの代わりになります。文書は、実行したコマンドとその出力のような具体的な証拠を一緒に求めることも勧めています。

ここから言えること：「完了」と言うのにコストはかかりません。確認を安くするのは証拠です。やることは、信じるか信じないかを決めることではなく、結果が確かめ方を一緒に運んでくる形に依頼を設計することです。

2. なぜ必要か：使う側が確かめている#

2.1 Stack Overflow 2026年調査の2つの数字#

Stack Overflow Developer Survey 2026の結果ページ（ある報道によると3万を超える回答）によれば、回答者の約48%が、結果を確かめやすいときにAIを信頼すると答え、6.6%が重要な判断を含む多くの作業でAIを信頼すると答えました。また、見慣れない課題に出会ったときにAIエージェントに聞く人は69.9%でした。つまり、よく使うが、信頼には条件がつくということです。

注意が2つあります。1つめは、私が要約で読んだだけで、表を一つずつ照合してはいないことです。ページ上の「87%超が何らかの信頼を持ち、前年の31%から上昇」という数字は、6.6%と食い違って聞こえるため、使っていません。2つめは、出典の明示についてです。AIの回答を評価するときに出典の明示を重視する割合は、私が読んだ資料では78.7%（ある報道）と93%（調査ページの要約）と、ずれています。数え方や質問が違う可能性があるので、「大多数、約80%から93%」と受け取ってください。

**ここから言えること：**使う人自身が「結果を確かめやすくしてほしい」と言っています。足りないのは、確かめやすくする具体的な方法です。

2.2 実際にあった事件：存在しない判例（Mata v. Avianca、2023年）#

ニューヨークの連邦裁判所での訴訟で、原告側の弁護士がChatGPTで書面を作りました。書面は、航空会社名、引用文、番号がそろった判例を引いていましたが、そのうち6件は存在しませんでした。2023年6月22日、裁判所は2人の弁護士と法律事務所に合計5,000米ドルの制裁金を科しました。詳しくは記事なぜAIを鵜呑みにしてはいけないのかにあります。

注目したいのは、書面には「出典」があったのに、誰もその出典を開かなかったことです。証拠は、誰かが開いて初めて役に立ちます。

**ここから言えること：**出典を求めるのが1歩目、出典を開くのが2歩目です。2歩目がなければ、1歩目は飾りにすぎません。

2.3 AIが自信ありげに答えがちな理由：知っておきたい一つの議論#

Kalai、Nachum、Vempala、Zhangのグループ（OpenAIとジョージア工科大学、2025年9月4日）は、モデルの訓練や採点の方法が、「自信がありません」と言うことよりも当てずっぽうで答えることに得点を与えがちだと論じています。彼らの例では、ある人の誕生日を聞かれたとき、一つの日付を推測すれば当たる確率は約365分の1ですが、「分かりません」と答えれば必ず0点なので、推測のほうが得になります。OpenAIの付属記事は、SimpleQAというテストでの比較を報告しています。あるモデルは52%の問題で回答を控えて誤りが26%、より古いモデルは1%しか控えず誤りが75%でした。

これは著者自身の論じる説明と、当の企業が出した数字であり、私の調べた範囲では独立した検証は見つかっていません。ただ実務上のヒントにはなります。システムが確信がなくても答える傾向を持つなら、AIが自分から認めるのを待つのではなく、確信がない箇所を明示するよう依頼で求めるほうがよいのです。

ここから言えること：「自信がありません」は自然には出てこないことが多いので、依頼の中で頼んでおきます。

3. 証拠を求める5つの方法#

イメージしやすいように、各方法を整備票の一欄だと考えてみてください。どこで読んだか、何を試したか、何を変えたか、何をまだしていないか、自分でやり直す手順です。

方法1. 開ける出典を求める#

**イメージ：**ページ下の脚注つきの本のようなものです。脚注は、そのページまでめくれて初めて価値があります。

依頼に入れる文例：

コードや文書についての主張には、確認できる場所を添えてください。
ファイルのパスと行番号、または公式文書のリンクです。
出典のない主張には、はっきり「出典なし」と書いてください。

結果の読み方：最も重要な主張を一つか二つ選んで出典を開き、出典が本当にその内容を述べているかを見ます。リンクが開くだけでは足りず、内容が合っている必要があります。

穴になりやすい点：作り話の出典（先の判例のように）、実在するが別のことを言っている出典、古い出典。見つけ方は、開いて、日付を見ることです。

方法2. 実行できるテストと、出力そのままを求める#

**イメージ：**ブレーキを試し踏みするようなものです。結果は「止まった」か「止まらなかった」で、誰のコメントも要りません。

文例：

完了と報告する前に、次の確認コマンドを実行し、
コマンドと出力を要約せずそのまま貼ってください：npm test
失敗したテストがあれば直して再実行してください。
実行したテストの数も書いてください。

Claude Codeの文書は、テストとして使えるものを挙げています。テストファイル、ビルドの終了コード、静的解析（リンター）、出力を期待結果と比べるスクリプト、デザイン案の横に置くスクリーンショットなどです。大事なのは、テストが合格か不合格を返し、AIがその結果を読めることです。

穴になりやすい点：AI自身がコードに合わせて書いたテスト（同じ間違いがコードとテストの両方にある）、AIがコードに合わせてテストを書き換える、テストの一部しか実行しない。見つけ方は、テストフォルダの差分を見る、実行したテストの数を全体の数と比べる、そして壊してみることです。自分で1行をわざと間違えて、テストが赤になるかを見ます。よりよいテストの書き方は記事AIが書いたコードのテストにあります。

方法3. 小さな変更に分けてもらう#

**イメージ：**答案を一束で出すのではなく、一問ずつ出すようなものです。採点者は休み時間のうちに採点できます。

文例：

一度に一つのことだけやってください。一回の変更は一文で説明できる内容に限り、
変更は100行程度までにしてください。各部分のあとに、
その部分が何のためか、動作をどこで確認できるかを書いてください。

Googleが公開しているコードレビューの指針は、小さな変更のほうが速く、しかも丁寧にレビューできると述べています。レビューする人は、30分の塊を確保する代わりに、数分を何度も見つけられ、大きな変更では重要な点を見落としやすいからです。目安として、100行程度は妥当で、1,000行は大きすぎることが多いとしています。これは人がレビューするときの経験則で、厳密な数字ではなく、ファイル数によっても変わります。

穴になりやすい点：小さく分けても部分同士が依存していて、読む人が追いにくい。見つけ方は、分け方の順序と理由を書かせることです。一括の改名のように本当に大きな変更が必要なときは、機械的な部分と、判断を含む部分を分けて示すよう頼みます。

方法4. 仕分けを求める：実行済み、読んだだけ、仮定#

**イメージ：**医師のカルテに「診察した」「画像を見た」「症状からの推測」と書き分けるようなものです。この三つを混ぜてはいけません。

文例：

回答の最後に、結果を3つに分けてください：
(a) 実行して結果を見たもの（コマンドつき）
(b) コードを読んだが実行していないもの
(c) 仮定または推測
確信が持てないことは、省かずに(c)に入れてください。

理由は2.3のとおりです。システムには、答えをまとめきる傾向があるかもしれず、「これは実行していません」は自然には出てきません。3つに分ける表は、確信のなさに居場所を与えます。

穴になりやすい点：AIが読んだだけのことを(a)に入れてしまう。見つけ方は、(a)のすべてにコマンドと出力そのままを隣に付けさせることです。コマンドのない(a)は(b)として扱います。

方法5. 他の人が再実行できる手順、または独立した読み手を求める#

**イメージ：**料理のレシピのようなものです。手順どおりにやり直して同じ料理になれば、作った人の自慢話より信頼できます。

文例：

きれいなマシンで、自分で結果をもう一度見られるコマンド
（または数ステップ）を教えてください。必要なバージョンと環境変数も書いてください。

重要な作業なら、以前の議論を見ていない新しいセッションに、元の依頼と変更を照らして読み直してもらいます。Claude Codeの文書は、これを、会話を見ていない新しい子エージェントで走らせるレビューコマンドとして説明しています。コードに至った議論に引きずられないためです。これは筋の通ったやり方であって、保証ではありません。別のAIも同じ種類のミスをするかもしれないからです。

穴になりやすい点：AIのマシンでは動くが自分のマシンでは動かないコマンド（環境変数やバージョンの違い）。見つけ方は、きれいなマシンかCIで実際に一度動かすことです。重要な作業では、機械だけでなく人も読みます。

短い一つのブロックにまとめる#

長く使うなら、次のブロックをAGENTS.mdやツールの指示ファイルに貼り、毎回のセッションで読まれるようにします。

## 作業の完了を報告するとき
- 実行した確認コマンドと出力をそのまま貼る。実行したテスト数も書く。
- コードについての主張には、ファイルと行番号をつける。
- 一つの変更は一つの目的、100行程度まで。
- 結果を分ける：実行済み／読んだだけ／仮定。
- きれいなマシンで再実行できるコマンドを一つ示す。

5行なので、人もAIも読み切れます。短くしたのは意図的です。長い一覧は読み飛ばされるかもしれません。

4. 自分で確かめられる計算（例、読み飛ばしても可）#

これは作った数字による例で、実測値ではありません。AIが、8つの主張を含む変更の要約を出したとします（例：「日付の書式のバグを直した」「決済の関数には触れていない」）。承認する前に、各主張を確かめる必要があります。

• 証拠がない場合：各主張を自分で組み立て直す必要があり、1つ6分と仮定します。
• 証拠がある場合：示されたものを開くだけで、1つ1分と仮定します。最もリスクの高い2つは、さらに5分ずつ深く確かめます。

claims, rebuild, glance, deep, risky = 8, 6, 1, 5, 2
without = claims * rebuild              # 48分
with_proof = claims * glance + risky * deep   # 8 + 10 = 18分
print(without, with_proof, without - with_proof)
# 48 18 30

per_month = 2 * 20                      # 1日2件の要約、20日
print(without * per_month / 60, with_proof * per_month / 60)
# 32.0 12.0   (月あたりの時間)

結果の読み方：要約1件あたり48分が18分になり、約38%に減ります。1日2件、稼働20日なら、レビューする1人あたり月約32時間が約12時間になります。

はっきり言っておくと、6分、1分、5分は私が仮定した数字で、測った値ではありません。実際の作業ではかなり違うかもしれませんし、証拠を求めるとAIの実行や記述の時間も増えます。自分のチームで何回かストップウォッチで測り、数字を入れ替えてください。

5. 証拠を求めても穴になる場所#

整備票を思い浮かべてください。作業員は、試していなくても「ブレーキ試験済み」と書けてしまいます。

5.1 例：証拠がある午後と、ない午後#

これは作った状況で、実在の人物や製品には触れていません。

証拠を求めなかった場合：

• 14:00. 開発者がエージェントに頼みます。「レポートで12/31が翌年と表示されるバグを直して。」
• 14:20. エージェントが答えます。「直しました。テストはパスしています。」開発者は変更をざっと読み、もっともらしいので本流にマージします。
• 16:30. 顧客から、別の日付書式では年末のレポートがまだ間違っていると連絡が来ます。エージェントは2か所のうち1か所しか直していませんでした。

証拠を求めた場合：

• 14:00. 同じ依頼に、上の5行のブロックを添えます。
• 14:20. エージェントが提出します。npm testを実行し、12件のテストがパス、新しいテストはdd/MM書式の12/31の1件だけ。(b)：2つめの書式の関数は読んだが実行していない。(c)：すべてのレポートがdd/MM書式だと仮定した。
• 14:25. 開発者は(b)と(c)を見て、2つめの書式での12/31のケースを追加します。テストが赤になります。エージェントが残りの箇所を直します。
• 14:40. 新しいテスト2件とともにマージします。

どちらの場合も、すべきことは、(b)と(c)の段階で「完了」を止めることです。AIが正直に「実行していません」と書いた場所が、開発者にどこを見るべきかを教えてくれます。これは例なので、何かを証明するものではありません。根拠は研究にあります。Perryらの研究（スタンフォード、2022年）では、AIアシスタントを使った人のほうが、ほとんどの課題で安全性の低いコードを書いたのに、自分のコードは安全だとより強く信じていました。ざっと読んで承認することを心配する理由はあります。あわせて記事AIが書いたコードのレビューもご覧ください。

6. 使った数字と文書#

**正しい読み方：**上の資料は、結果を確かめやすくすることを支持しています。ただし、証拠を求めることでミスがどれだけ減るかを直接測った対照実験は、見つかっていません。上の5つの方法は実務上のまとめです。

7. リスクに応じた証拠のレベル#

どんな作業にも5つ全部を求める必要はありません。買い物にたとえると、野菜は目で見ればよく、腕時計には保証書が要ります。

8. 明日から使える習慣#

8.1 結果を受け取る前の8つの質問#

1. この結果は、出典、テスト、言葉だけのうち、どんな確かめ方を一緒に運んできているか。
2. 重要な出典を少なくとも一つ開いたか。その出典は本当にその内容を述べているか。
3. 確認コマンドと出力はそのままか、それとも要約だけか。
4. 全体のテスト数のうち、いくつ実行されたか。
5. 新しいテストは誰が書いたか。自分が1行を壊したとき、赤になるか。
6. この変更は、全部読めるほど小さいか。
7. AIが「読んだだけ」「仮定」と書いた部分を、自分はどう扱うか。
8. きれいなマシンで再実行できたか、それともAIの言葉を信じただけか。

8.2 今すぐできる3つのこと#

1. 今使っているツールの指示ファイルに、5行のブロックを貼る。
2. 今日の小さな作業を一つ選び、証拠を求める前と後で、確認にかかった時間を測る。
3. 同僚に「実行済み、読んだだけ、仮定」の仕分けを一件読んでもらい、使えるかどうかを聞く。

9. バランスよく見る：証拠にできること、まだできないこと#

**できること：**確認を安く速くする。実行していない箇所をAIにはっきり言わせる。他の人が確かめ直せる記録を残す。依頼と変更のずれを見つけやすくする。

まだできないこと：

• 証拠は正しさの保証ではありません。テストは間違っているかもしれず、出典は作り話かもしれず、整った表が過剰な安心感を生むこともあります。Perryらの研究は、AIアシスタントがあると人は油断しやすいことを示唆しています。
• 証拠を求めると、AIの実行と記述の時間が増えます。リスクの低い作業には過剰です。
• それぞれの方法の効果を単独で測った対照実験は、見つかっていません。自分のチームで測ってみてください。
• 別のAIが読み直しても、同じ種類のミスをするかもしれません。重要な作業では人の読み手が必要です。

**大げさに言わない：**これはAIが間違えなくなる方法ではありません。**軽く見ない：**確かめるものがないまま「完了」を受け取るコストは、たいてい最後に、ミスが顧客の手元に届いたときに現れます。

10. おわりに#

AIの「完了しました」は、答えのように聞こえますが、実は約束です。証拠は、その約束を確かめられるものに変えます。開ける出典、実行できるテスト、小さな変更、実行済み・読んだだけ・仮定の3分類、再実行できる1本のコマンド。これらの依頼はAIに渡す文の中に入れ、証拠を開くのは、いつも人です。

参考資料#

数字は2026年10月時点の公開情報から取っています。報道によって数字が異なる場合があるので、引用する前に元の資料を開いて確認してください。

• Stack Overflow、2026 Developer Survey（要約で読んだもので、表ごとの照合はしていません）
• Anthropic、Best practices for Claude Code（Give Claude a check to run の項）
• Kalai、Nachum、Vempala、Zhang、Why Language Models Hallucinate（2025年9月）とOpenAIの記事
• Google Engineering Practices、Small CLs
• Mata v. Avianca, Inc.：WikipediaとLawNextの制裁金に関する記事
• Pearceら、Asleep at the Keyboard?（2021年）とPerryら、Do Users Write More Insecure Code with AI Assistants?（スタンフォード、2022年）

学生、新社会人、ソフトウェアの最初の仕事を探している方向けです。統計の知識は要りません。難しい言葉には短い説明をつけています。

これは考察です。証拠を比べ、分かっていないことをはっきり書くもので、研究報告ではありません。2本の論文（スタンフォード、ハーバード）はPDFを直接読み、SignalFire、Ramp、イェール、Indeed（FRED経由）は元のページを読みました。それ以外は要約や報道で読んだものとして、その都度書いています。数字を引用する前に、必ず元の資料を開いてください。

要点#

• 「AIが入り口を狭めている」という記事も、「まだ何も見えない」あるいは「逆だ」という記事もたくさんあります。多くは自分が測ったものについては正しいのです。問題は、測っているものがそれぞれ違うことです。
• 大規模な研究に共通するのは、経済全体では雇用の喪失は見えない一方、AIの影響を受けやすい職種の22歳から25歳の雇用が弱まっていることです（スタンフォード、ハーバード）。スタンフォードの更新版（2026年6月までのデータ）は19%という数字を出し、著者自身が因果の証明ではなく初期の記述的な指標だと述べています。
• 同じグループ、同じデータの出どころでも、6%、13%、19%、20%と複数の数字が出ます。違いは基準点と計算方法で、誰かが嘘をついているわけではありません。
• AIとは関係のない説明もあります。2022年からの金利上昇、米国の研究開発費に関する税ルール（セクション174）、2021年から2022年の採用過熱です。研究者はこれらを取り除こうとしましたが、完全に取り除けた人はいません。
• 数字を信じる前に6つの質問をします。誰を数えたか、何を数えたか、いつと比べたか、データはどこから来たか、同時に他に何が変わったか、どこまで確かか。
• どちらが正しくても、新人は自分の市場を測り、入り口を広げ、実力の証拠を作り、四半期ごとに数字を見直せます。

むずかしい言葉をやさしく#

1. 例え話：同じ群衆を5人がはかる#

日常の場面に置き換えてイメージしてみましょう。これは私の例で、実際のデータではありません。

駅の改札前の同じ群衆を5人が見て、「この群衆は小さくなっているか」に答えようとします。

• 1人目は子どもだけを数えます。減ったと感じます。
• 2人目は全員を数えます。ほとんど変わらないと感じます。
• 3人目は入口に立ち、新しく入る人を数えます。大きく減ったと感じます。
• 4人目は「人手募集」の掲示板を読みます。掲示が減っていると感じます。
• 5人目は一人ひとりに聞きます。「入るのは大変でしたか」。多くが「はい」と答えます。

5人とも誠実で、自分が測ったことについては正しいのです。「群衆が小さくなっている」とだけ聞くと、誰が何を言ったのか分かりません。ソフトウェアの新人の仕事の話もまったく同じで、さらに出発の年と立つ場所も人によって違います。

2. 「入り口が狭まっている」という側#

研究を、何を測っているかで並べます。最後の列は、結論への確信ではなく、私がその研究を正しく読めているかの確かさです。

表から分かる2つのことです。

1. 大規模な研究は、経済全体で仕事が消えているとは言っていません。 スタンフォードの論文自体が、経済全体での広範な雇用の置き換えは見られないと書いています。話しているのは狭いグループ、つまりAIが業務の一部を代替できる職種の若者です。
2. 同じグループ、同じデータでも複数の数字が出ます。 AIの影響が大きい職種の22歳から25歳について、ADP Researchのページは約6%減（2022年後半から2025年7月、自分自身との比較）、スタンフォードの論文は13%、のちに19%（他のグループとの比較）、ソフトウェア開発者だけなら約20%（ピークとの比較）と述べています。第4章でこれらの比較を計算し直し、違いの理由を確かめます。

3. 「まだ見えない」「逆だ」という側#

読み違えないための注意です。

• Rampの「入門レベルの人数が12%増」は、要約の間違いではありません。AIに多く支出した企業で、2年間に入門レベルの人数が増えたという意味です。ただしRamp自身が、これらの企業は以前から規模が大きく、エンジニアが多く、ベンチャーの出資が多く、成長も速かったと書いています。つまりその企業群の中での相関で、経済全体については何も言えず、論文も最終版ではありません。
• ハーバードとRampは、新人については本当に逆の結果です。どちらもAIを使う企業を見ています。ハーバード論文の注によれば、両方ともRevelioの履歴書データを使っています。違いは「AIを使う企業」の定義です。片方はAI統合の職種の求人を出した企業、もう片方はAIツールにお金を使った企業です。同じデータ提供元でも、定義が違えば結果が違います。
• ニューヨーク連銀の専攻別失業率は、サンプルが小さいため非常にぶれます。 2023年のデータは、上の研究の多くの対象期間より前でもあります。その後の更新は報道では約7.0%と7.8%とされていますが、元の表を開いて確認できなかったので、主な数字には使いません。

4. なぜ同じ市場で違う数字が出るのか#

おもちゃの町を思い浮かべてください。以下の数字は私が作った例で、手で計算しました。実際の市場を測ったものではありません。

おもちゃの町には新人向けのポジションが100あります。2022年：40がAIが業務の一部を代替できる職種（グループA）、60がそれ以外（グループB）。2025年：グループAは32、グループBは66に増えました。

同じデータから3つの答えが出ます。「20%減」「27%低い」「ほぼ変わらない」。誰も間違っていません。スタンフォードの19%も同じ仕組みです。影響が最も大きい2つの職種グループの雇用は2022年11月から2026年6月に約11%減り、影響が最も小さい3つのグループは約10%増でした。0.89 / 1.10 - 1 で、歩調を合わせた場合より約19%低くなります。「11%減」だけを見れば、同じデータから別の数字が出ます。

計算方法のほかにも、数字をずらす要因が4つあります。

基準点を変えると物語が変わる：実際の求人データ#

Indeed Hiring Labの米国ソフトウェア開発の求人系列（指数、2020年2月＝100、季節調整済み）はFRED上で公開されています。系列の3つの点から比較を計算し直しました。

1つの系列から3つの文が作れます。「求人は3分の2減った」「パンデミック前よりまだ約5分の1低い」「底から32%戻った」。しかも2022年の求人はパンデミック前の約2.3倍でした。「減少」の一部は異常なピークからの戻りで、すべてが新しい出来事ではありません。

5. AIとは関係のない説明#

いくつもの変化が同時に起きた市場で、AIはその1つにすぎないと考えることもできます。

スタンフォードの論文は自分の弱点も明記しています。差は学歴を統制すると小さくなり、生成AI以前から一部で異なる傾向が見られ、全国調査よりADPデータのほうが顕著です。初期の記述的な指標であり、因果の推定ではないと強調しています。ハーバード論文の先行研究の整理によれば、影響の大きい職種と小さい職種の間に系統的な差が見られない研究もあります。たとえばCPSデータを使ったChandar（2025）とFinancial Times（2025）、約5.5%とより小さな減少を見つけたスウェーデンの研究です。これらは各論文ではなく、ハーバードの整理を通して読みました。

6. 数字を信じる前の6つの質問#

6本の懐中電灯だと考えてみましょう。数字に1本ずつ当てて、暗いままの場所があれば、急いで信じないでください。

試してみましょう。 例（想定）：私が作った見出しで、実在の記事ではありません。「新人開発者の仕事が20%減」。6つの質問：どの国の新人開発者か。在籍者数か採用数か。どの年から、ピークからかパンデミック前からか。給与データか求人か。金利、税、採用過熱は考慮されたか。比較グループはあるか。記事が3つ以上答えられなければ、その数字は数字のついた噂として扱い、まだデータとは見なさないでください。

7. ベトナムと日本：見つかったもの#

• ベトナム。 ベトナムの新卒開発者に特化した政府のデータは見つからず、大手求人サイトの公開レポートも開けませんでした。最も近いのは、Tuổi Trẻの報道（2026年9月9日）によるManpowerGroupの2026年第4四半期調査です。調査対象285の雇用主のうち**57%が2025年と比べて入門レベルの採用を増やしたと答え、情報分野では77%**でした。注意して読んでください。人材会社による雇用主の自己申告の調査で、285社がすべてベトナムの企業かは記事に書かれておらず、「入門レベル」の定義もなく、開発者だけを切り出してもいません。確かさ：低い〜中程度。
• 日本。 AIと結びついた日本の新人開発者に関する一次データは見つかりませんでした。経済産業省（METI）の、2030年までにシナリオによって約16万人から79万人のIT人材が不足しうるという予測がよく引用されます。元のページにアクセスを拒否されたので要約でしか読めておらず、生成AIが広がる前に作られた全体数の予測なので、新人とAIの問いには答えません。確かさ：低い。引用する前に元の資料を開いてください。

はっきり言うと、この記事の数字は主に米国のものです。ベトナムと日本は違うかもしれませんが、どう違うかを言える証拠は私にはありません。

8. どちらが正しくても、新人にできること#

明日が雨か晴れか分からないときの準備だと考えてみましょう。傘もサングラスも持っていれば、当てる必要はありません。 以下は私自身の考えで、多くの人で検証されたものではありません。

もう1つ。全国平均は1人への判決ではありません。1回の不採用には、予算や他に合う人がいたなど具体的な理由があるのが普通で、統計の数字のせいではありません。長い目で見たい方は、開発者の歩みがこの話を職業の歴史の中に置いており、AIが速くコードを書く時代、開発者は創造する人かが代替しにくい仕事について書いています。

9. 分かっていないこと#

• 原因。 AIを、金利、税、採用過熱、パンデミック後の調整から切り分けた人はいません。スタンフォードとハーバードの著者も、それぞれの言い方でそう述べています。
• 採用が遅れているのか、なくなったのか。 単に採用が遅れているだけなら、新人は数年後に入れます。はしごの1段がなくなったのなら、話は違います。現在のデータでは区別できません。
• ソフトウェアに限った話。 22歳から25歳の開発者について最も良い数字は、ADPの20%と小さな調査です。CPSではこの年齢層が毎月ごくわずかしかいません。
• 米国以外。 ベトナムと日本については、信頼できる証拠がありません。
• 数字は版で変わる。 スタンフォードの数字はデータの追加と計算方法の変更で13%から16%、19%へと動きました。この記事も古くなるので、日付を確認してください。
• 私自身の限界。 2本の論文はPDFを直接読み、上に挙げた元のページも読みましたが、残りは要約経由です。再確認できる生データはないので、計算は公表された数字をやり直したものにすぎません。

10. バランスのとれた見方#

• この記事は、心配せよとも心配するなとも言いません。 データが示すのは、狭い領域（AIが一部を代替できる職種の若者）が弱まっていることで、経済全体の問題は示していません。
• 「まだ見えない」は「ない」ではありません。 イェールのBudget Labは混乱を見ていないと言い、今後もないとは言っていません。私が読んだ要約では、AIはいずれ何らかの痕跡を残すだろうと見ています。
• 「見える」は「AIのせい」ではありません。 上の新人に関する数字は、すべて相関です。
• 測れるものは物語にしやすい。 「AIがあなたの仕事を奪った」は、「いくつものことが同時に変わり、まだ切り分けられていない」よりすっきりしています。すっきりしているからといって、正しいとは限りません。

11. 結論#

2つの記事が正反対の数字を出しているとき、たいていは違う物を違う秤ではかっています。6つの質問をしましょう。誰を、何を、いつから、どのデータで、他に何が変わり、どこまで確かか。新人にとっては、どちらの側が正しいかを当てるより、どの場合でも役に立つことをするほうが大切です。自分の市場を測り、入り口を広げ、実力の証拠を作り、四半期ごとに見直しましょう。

今週から始めましょう。表計算を開き、応募したい場所の求人を20件記録します。1つの見出しで計画を変えないでください。

参考資料#

数字を引用する前に、必ず元の資料を開いてください。要約や報道でしか読んでいないものは、上に書いています。

• Brynjolfsson, Chandar, Chen: Canaries in the Coal Mine? Six Facts about the Recent Employment Effects of AI（スタンフォード大学Digital Economy Lab。私が読んだ版は2026年8月付、データは2026年6月まで）
• ADP Research: Yes, AI is affecting employment, here's the data（最も若いソフトウェア開発者の6%と20%、2025年7月）
• Hosseini, Lichtinger: Generative AI as Seniority-Biased Technological Change（SSRN 5425555、2026年5月6日版）
• SignalFire: State of Tech Talent Report 2025
• Ramp Economics Lab: Companies hire more after AI adoption（2026年6月30日）
• ニューヨーク連邦準備銀行: The Labor Market for Recent College Graduates
• Economic Innovation Group: A viral chart on recent graduate unemployment is misleading（専攻別の6.1%と7.5%の読み直し、ACS 2023）
• イェール大学 Budget Lab: Evaluating the Impact of AI on the Labor Market: Current State of AffairsとFortune：2026年2月の更新と「AI washing」の記事
• FRED: Software Development Job Postings on Indeed in the United States（Indeed Hiring Lab）
• Baker Tilly: Domestic research expenditures, Section 174 under the 2025 tax act（会計事務所の要約で、法令そのものではありません）
• Tuổi Trẻ News: Vietnam among region's strongest hiring markets, yet employers struggle to find skilled workers（2026年9月9日、ManpowerGroup調査）
• ブログ内の関連記事：AI時代の新人：12か月計画、AI時代の面接：2週間計画、AIが間違えたら誰が責任を取るのか、開発者の歩み

新しいライブラリや言語を学んでいる人、とくに学生や新人向けです。研究や統計の知識は不要で、専門用語には短い説明をつけています。

このテーマの根拠はまだ少なく、新しいもので、ほとんどが小規模で短期間の研究です。4週間の計画は私の提案であり、まだ誰も検証していません。自分自身で行う実験として扱ってください。

先にまとめ#

• AIを使うかどうかより、どう使うかが大事かもしれません。 Anthropicの小さな実験では、AIに任せきりにした班は理解が低く、質問して理解するために使った班は点数を保ちました。
• 速いことが、学びが多いことだとは限りません。 AI班が速かったのは数分だけで、その差は結論を出せるほどではありませんでした。
• 感覚は測定ではありません。 別の研究（METR）では、AIを使った人は19%長くかかったのに、速くなったと思っていました。
• 4週間の計画： AIオンの回、AIオフの回、毎週金曜の10点満点の自己テスト。
• 4つのルール： 聞く前に予想する、コードだけでなく説明も頼む、記憶から書き直す、AIオフの回を残す。
• AIに先にやらせてもよい場面もあります。 どんなときかは記事の中で示します。

むずかしい言葉をやさしく#

1. たとえ話：料理を見ることと、ナビに従うこと#

料理の学び方を2つ思い浮かべてください。1つ目は、シェフが一皿作り終えるのを横で見る方法です。食べられますが、翌日に自分で作れるとは限りません。2つ目は、自分で作り、隣にいる助手が間違いを指摘して理由を説明してくれる方法です。完成は遅くなっても、手が覚えます。

道案内も同じです。ナビに従えば早く着きますが、電源を切ると迷います。地図を覚えるのは最初は遅くても、電波がなくても自分で道を探せます。

イメージとして、AIはシェフでもありナビでもあると考えられます。代わりにやってくれることが、強みであり、リスクでもあります。この記事の問いは、いつ任せ、いつ切って自分の手に覚えさせるかです。

一般的な注意：AIの内部を完全に理解している人はおらず、AIと学ぶことの研究はまだ数年の歴史しかありません。記事内の図はイメージの助けです。

2. 根拠は何を示しているか#

数字はAnthropicの研究ページとarXivの論文によります。両者は丸め方が少し違うため（片方は50%と67%、もう片方は27点中4.15点の差）、「約」と書いています。AI班は数分速かったものの、要約ごとに数字が少し違い、いずれも統計的に有意ではありません。

Anthropicの実験にあった6つの使い方#

研究チームは画面録画を見直し、AIを使った人を6つの型に分けました。

前の3つは学びが少なく、後の3つは学びが保たれました。後の3つに共通するのは、自分で考え続けていることです。理解のために聞くか、エラーを自分で処理しています。ただし各グループは2〜7人で、記述的な分析なので、法則ではなく使い方のヒントとして読んでください。

「先に予想する」「記憶から書き直す」に理由がある訳#

MITのTeaching and Learning Labの指導ガイドは、情報を自分で思い出すことは、読み返すよりも長期の記憶によいと述べ、Roediger and Karpicke（2006年）を引いています。同じページは、予想が外れても説明つきの正解を見れば学びが深まるとし、その苦労を学習者に「望ましい困難」（Bjork 1994）と伝えることを勧めています。アリゾナ大学のガイドは、定義を言わせるだけの問いより、予想や比較をさせる問いのほうが役立つと付け加えています。

これは教室一般についての根拠です。AIを使ったこの計画そのものを検証した研究はありません。 ルールを設計する合理的な理由として使っていますが、計画が効くことの証明ではありません。

3. 例（想定）：同じ課題、2通りの学び方#

これは数字を仮に置いた例であり、実在の人物ではありません。

学習者が、新しいライブラリでデータ取得の部分を書いています。

やり方A：全部任せる

やり方B：先に予想し、そのあと理由を聞く

やり方Bは25引く10で、15分遅くなります。その代わり、11:30には自分で直せます。ここでの時刻は例のための仮の数字で、測定値ではありません。

この例を裏づけているのは例そのものではなく、第2節の根拠です。Anthropicの実験では、任せきりのグループの点数が低くなりました。

4. 4つのルール#

1. 聞く前に予想する。 「結果は〜になると思う」と1行書きます。そのあと実行するか聞くかして、比べます。外れても構いません。そのズレこそ、これから学ぶところです。
2. コードだけでなく説明も頼む。 なぜこう書くのか、どんなときに間違うのか、別の方法はあるかを聞きます。Anthropicの研究では、コードと説明を一緒に頼んだ班に近い使い方です。
3. 記憶から書き直す。 理解できたら、AIのタブと資料を閉じて打ち直します。詰まった所に印をつけ、開き直し、もう一度打ちます。
4. AIオフの回を残す。 毎週、公式ドキュメントとマシンのエラーメッセージだけで進める時間を作ります。手がまだ覚えているかを確かめる時間です。

補足のルールが2つあります。AIからコードを受け取ったら、他人のコードのようにレビューすること。そして、AIはとても自信のある口調で間違うことがあることを忘れないことです。

5. 4週間の計画#

毎週60分を4回（月曜から木曜）と、金曜に30分の自己テスト（テスト15分、見直し15分）を想定します。測れるように、ライブラリか言語を1つだけ選びます。

計算#

• 毎週4回、1回60分、4週間で、4×4×60＝960分の学習です。
• 金曜は4×30＝120分。計画全体は960＋120＝1,080分、つまり18時間です。
• AIオフの分数：第1週と第4週は各180分、第2週と第3週は各120分で、合計600分。金曜の120分（AIなし）を足すと720分。
• AIオフの割合：720÷1,080＝66.7%。AIオンは360分です。

この割合は私の選択で、正しい数字を示す研究はありません。締め切りに追われているなら、少なくとも第1週の回と金曜のテストは残してください。

6. 毎週金曜の自己テスト#

AIなし、資料なしで、15分、10点満点です。

そのあと資料を開いて採点し直し、間違った所をノートに書きます。間違いが、来週の宿題です。

ある学習者の仮の例： 第1週は10点中4点（40%）、第2週は5点（50%）、第3週は7点（70%）、第4週は8点（80%）。第1週から第4週で4点、つまり40パーセントポイント上がりました。数字は作り話で、自己採点には誤差があります。他の人ではなく、自分の傾向を見てください。

自分を比べる方法の1つ：毎週、AIオンで学んだ概念を2つ、AIオフで学んだ概念を2つ選び、金曜にどちらをよく覚えているかを見ます。4つでは極めて少ないので、自分を知る目安にとどめてください。

7. AIに先にやらせてもよい場面#

Anthropicは、以前の自社研究では、すでに習熟した作業でAIが生産性を高めたと述べており、2つの結果は矛盾しないかもしれないと注記しています。

8. バランスのとれた見方#

• 実験は約1時間だけでした。 数か月後に差が縮むのか、そのままなのかは分かりません。
• 少人数、1つのライブラリ、1回のテストです。 著者もこれらの限界を述べており、別の実験なら違う結果になるかもしれません。
• AI企業による実施です。 結果はAIの利用にやや不利ですが、それでも原文を読み、独立した資料と見比べてください。
• 実験で使われたのはチャットです。 プロジェクト全体を書く自動化ツールでは違うかもしれず、著者もそう述べています。
• 人から学ぶ場合との比較はありません。 AIと良い指導者のどちらがよいかは分かりません。
• PNASの数学の研究は高校生が対象です。 大人がプログラミングを学ぶ場合にそのまま当てはまるとは限りません。
• MicrosoftとCMUの調査は自己申告で、相関のみです。
• この計画は多くの人で試されていません。 遅すぎる、厳しすぎると感じたら、金曜のテストを残したまま、AIオフの割合を調整してください。

9. 結論#

問いは「AIで学ぶべきか」ではなく、自分の手が覚えているようにどう使うかです。今ある根拠は薄いものの、同じ方向を指しています。考え続け、理由を聞き、打ち直す人は、学びを保てます。先に予想し、説明を頼み、記憶から書き直し、AIオフの回を残し、金曜のテストで測りましょう。

今日から始めるなら、ライブラリを1つ選び、最初の予想をノートに書き、最初の金曜のテストを予定に入れてください。

基礎がまだなら、新人向け12か月の計画を見てください。面接が近いなら、2週間の計画をどうぞ。この話を2人の会話で聞きたい方は、新人と先輩の対話があります。

参考資料#

引用する前に原文を開いて確認してください。数字は更新されることがあります。

• Shen and Tamkin、"How AI Impacts Skill Formation"、arXiv 2601.20245（2026年1月）
• Anthropic、研究紹介ページ "How AI assistance impacts the formation of coding skills"
• Bastani and colleagues、"Generative AI without guardrails can harm learning"、PNAS 2025
• Wharton、Bastani and colleaguesの研究の要約記事
• METR、"Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity"（2025年7月）
• Lee and colleagues、"The Impact of Generative AI on Critical Thinking"、CHI 2025（著者公開のPDF）
• MIT Teaching + Learning Lab、"Help Students Retain, Organize and Integrate Knowledge"
• Roediger and Karpicke、"Test-enhanced learning"、Psychological Science（2006年）
• アリゾナ大学、"L2L Strategy: Retrieval Practice"
• このブログの関連記事：AI時代の新人：12か月計画、AI時代の面接：2週間の計画、新人と先輩の対話、AIが書いたコードのレビュー、AIを鵜呑みにしてはいけない理由

AIでコードを書く人、AIエージェントに作業を任せる人なら誰でも、初心者の方でも読めます。セキュリティの知識は不要です。用語にはどれも身近なたとえを添えています。計算の部分は印をつけてあるので、不要なら読み飛ばせます。

数字は公開情報から取っており、末尾に一覧があります。「例」と書いたものは作った例で、実在の人物や会社には触れていません。AIがパッケージ名を作り出す理由は、まだ誰にも完全には分かっていません。以下のたとえは覚えやすくするための補助であり、仕組みそのものの説明ではありません。

まず要点#

• AIはコードを書くとき、もっともらしく聞こえるのに実在しないライブラリを提案することがあります。USENIX Security 2025の大規模な研究は、2024年の実験で、その割合を商用モデルで平均少なくとも5.2%、オープンソースモデルで21.7%と測りました。
• 同じ偽の名前が繰り返し提案されるなら、攻撃者はnpmやPyPIのような公開レジストリでその名前を先に登録し、マルウェアを入れておけます。この攻撃をスロップスクワッティング（slopsquatting）と呼びます。
• その研究で、偽の名前が出たことのある500件の質問を10回ずつ再実行したところ、約43%の偽の名前が10回すべてで再び出ました。作り出された名前は完全なランダムではなく、攻撃者が先読みできる程度には偏っています。
• 実際の実験もあります。空のパッケージhuggingface-cliは3万件を超えるダウンロードを集め、react-codeshiftという名前は200を超えるリポジトリに広がりました。どちらも研究者が登録したもので、マルウェアは入っていません。
• リスクは本物ですが、どのくらい大きいかははっきりしません。大きな被害が確認されたスロップスクワッティング攻撃は、私は見つけられませんでした。それより心配なのは、誰も見ていない状態でエージェントがインストールコマンドを実行することです。
• 防ぐのに高価なツールは要りません。ロックファイルでバージョンを固定し、新しいパッケージはインストール前に確認し、インストールスクリプトを止め、エージェントには承認を求めさせ、隔離環境で動かします。

むずかしい言葉をやさしく#

1. まずたとえで：店員とそっくりの店#

とても熱心な店員さんに「この機種に合うスマホケースはありますか？」と聞いたとします。店員さんはすぐ「はい、ゾルボ・プロがあります」と答えます。しかしその名前の商品はありません。嘘をついているわけではなく、それらしく聞こえる名前を作るのが上手なだけです。

そこへ、店員さんが多くのお客さんに同じ名前を勧めていることに気づいた詐欺師が現れます。隣に「ゾルボ・プロ」という看板の店を開き、有害な商品を売ります。次に店員さんが案内したお客さんは、その店にまっすぐ入っていきます。

これがスロップスクワッティングです。店員がAI、商品がライブラリ名、店がnpmのようなレジストリ、npm installが店に足を踏み入れることにあたります。打ち間違いと違い、利用者は何も間違えていません。提案に従っただけです。

この用語は、WikipediaとAndrew Nesbitt氏（広めた人）の説明によると、Python Software Foundationのセキュリティ開発者Seth Larson氏が2025年4月に考えたとされています。Larson氏本人の元の投稿は見つけられなかったので、伝聞であり引用ではないものとして扱ってください。

学び： 危険なのはAIが間違えることではなく、その間違いが予測でき、待ち構えている人がいることです。

2. 実在する2つの実験と、混同しやすい1つの事件#

2.1 空のhuggingface-cliパッケージ（Lasso Security、2023年から2024年）#

Lasso Securityの研究者Bar Lanyado氏は、AIモデルがPyPIのhuggingface-cliというパッケージのインストールコマンドを繰り返し提案することに気づきました。このパッケージは存在せず、正しくはhuggingface_hub[cli]です。氏はその名前で空のパッケージを登録し、誰かがインストールするかを調べました。

報道によると、約3か月で3万件を超えるダウンロードがありました。媒体によって数字が異なり、約1万5,000から3万5,000と幅があるため、数万件程度と読んでください。The Registerは、この偽の名前がAlibabaの研究用リポジトリのインストール手順にも載っていたこと、氏の報告後に修正されたことも伝えています。

注意点があります。ダウンロード数は被害者がいたことの証明ではありません。AIが生成したコード、人が手順をコピーしたもの、自動スキャナーが、それぞれ何件かは分かっていません。

学び： 繰り返し作り出された名前には本物の人がインストールし、他人の文書にまで紛れ込むことがあります。

2.2 react-codeshiftが200以上のリポジトリへ（Aikido Security、2025年から2026年）#

Aikido Securityによると、2025年10月17日に公開リポジトリへ入ったコミットが、LLMが生成した47個の「スキル」（エージェント向けの指示ファイル）を追加しました。そのうち少なくとも2つにnpx react-codeshiftというコマンドが含まれていました。この名前は、実在するjscodeshiftとreact-codemodを混ぜたように見えます。react-codeshiftというパッケージは存在したことがありませんでした。

これらのファイルはコピーやフォークで広がりました。Aikidoによると、2025年12月には200を超えるリポジトリがこのコマンドを参照しており、研究者Charlie Eriksen氏が名前を登録した2026年1月14日には237以上でした。そのときのGitHubのコード検索では、約215件のファイルが一致しました。数え方で結果が変わるため「200以上」と読むのが安全です。登録直後のダウンロードは初日に約74件、その後は1日に1から4件でした。筆者は、このわずかな流れは実際のエージェントがコマンドを試している兆候かもしれないと述べていますが、これは筆者の推測で、検証された結果ではありません。パッケージは安全な場所取りとして保持され、マルウェアは入っていません。

学び： AIが作った間違いはその場にとどまりません。コピーされ、フォークされ、翻訳され、他のエージェントが読んで従う「標準」になっていきます。

2.3 2026年5月のnpmワーム：危険だが、スロップスクワッティングではない#

Cloud Security Alliance（CSA）の2026年5月17日付の調査ノートは、TeamPCPという集団に関連するnpmワームを説明しています。npmの169パッケージとPyPIの2パッケージにまたがる373の悪意あるバージョンです。ノートによると、このワームはAIコーディングツールのファイルにも設定を書き込み、有効に見えるプロベナンスを持つバージョンもありました。これは他者の報告を伝える二次的なノートなので、引用する前に必ず元の資料を開いてください。CSA自身も、「初」とされる主張の一部は引用元の研究者のものだと述べています。

押さえておきたいのは、これが本物のパッケージの乗っ取りであり、AIが作り出した名前の話ではないことです。それでもここに載せる理由は2つです。1つ目は、レジストリが現実の標的であり、インストールコマンドを実行するエージェントが狙いやすい接点になりうることを示すからです。2つ目は、プロベナンスが絶対の保証ではないことを示すからです。第6章の習慣は、どちらの事件にも効きます。

学び： スロップスクワッティングという言葉にこだわらないでください。大事なのは、AIが作った名前でも、本物のパッケージが汚染された場合でも、自分のマシンに何が入るかを管理することです。

3. 仕組みをステップで見る#

4つの輪がつながった鎖とイメージしてみましょう。先にお断りします。モデルがなぜパッケージ名を作り出すのかは、まだ完全には分かっていません。よく言われる見方は、モデルが本物のライブラリらしく見える名前を書こうとし、本物の名前もreact、codemod、cliのような見慣れた語の組み合わせが多い、というものです。これはイメージであり、証明された結論ではありません。

1. あなたが頼む。 あなた（またはエージェント）がCSVを読む機能などを必要とし、AIにインストールコマンド付きのコードを頼みます。
2. AIが名前を提案する。 その名前がレジストリにないことがあります。研究によると、偽の名前のうち実在の名前から1、2文字しか違わないものは約13.4%だけで、主に打ち間違いの問題ではありません。
3. 攻撃者が登録する。 公開レジストリでは、空いている名前をすぐに取れます。偽の名前が繰り返されるなら、攻撃者は人気のモデルに何度も質問してよく出る名前を調べ、それを取れます。
4. インストールが成功する。 最初は「見つからない」エラーで無害です。名前が取られると同じコマンドが成功し、インストールスクリプトがインストールした人のマシンやCIサーバーで動くことがあります。

3.1 自分で計算できる例（例、読み飛ばし可）#

これは作った利用状況を使う例ですが、研究の本物の数字2つを基準にしています。5.2%（商用モデル）と43%（10回すべてで繰り返された偽の名前）です。開発者10人のチームが、1人1営業日あたり5回、AIにインストールコマンドを頼み、20営業日続けたとします。

devs, per_day, days = 10, 5, 20
suggestions = devs * per_day * days          # 1000
fake_rate = 0.052                            # 商用モデルの下限の目安
repeat_rate = 0.43                           # 10回すべてで繰り返された偽の名前
fake = suggestions * fake_rate               # 52
predictable = fake * repeat_rate             # 22.36
check_minutes = fake * 2                     # 1パッケージの確認に2分
print(suggestions, round(fake), round(predictable), check_minutes, check_minutes / devs)
# 1000 52 22 104.0 10.4

読み方：1,000件の提案のうち偽の名前は約52件で、そのうち約22件が攻撃者に予測されうる、繰り返すタイプです。もしそのひとつが取られていて誰も確認しなければ、npm installを1回実行するだけで十分です。一方、新しいパッケージを1つ2分で確認するコストは、チーム全体で月に約104分、1人あたり約10分です。確認は、誤ったインストール1回よりはるかに安くつきます。

注意：43%は、以前に偽の名前が出た500件の質問での測定で、全質問ではありません。5.2%は提案されたパッケージ名ごとの平均で、利用者ごとではありません。あなたのチームの数字は大きく違うかもしれないので、予測ではなく計算の方法として見てください。

4. 日常業務で穴になる場所#

工事現場とイメージしてみましょう。腕のいい職人でも、誰も倉庫を点検しなければ、間違った資材を持ち出すことがあります。

4.1 例：エージェントと過ごす朝#

これは作った例で、実在の人物や製品には触れていません。パッケージ名も作り物です。

• 10:00。 開発者がエージェントに頼みます。「このフォルダのCSVを結合して、日付の列をきれいにして。」
• 10:03。 エージェントはcsv-tidy-helper-xというパッケージを使うコードを書き、インストールを実行します。自動承認モードなので、コマンドはそのまま動きます。
• 10:04。 この名前はこれまで存在しませんでしたが、先週、誰かが登録していました。インストールは成功し、インストールスクリプトが動きます。
• 11:30。 コードは問題なく動き、開発者はPRを出します。ロックファイルは14行増えましたが、誰も読みません。

やるべきこと：エージェントをインストールコマンドで止め、確認させることです。開発者が名前を調べると、作成は先週、ダウンロードは3件、ソースリポジトリなし。断るには十分な兆候です。インストールがサンドボックスの中で動いていれば、被害も限定されます。第6章にこれらの防御の層をまとめています。

例は証拠の代わりにはなりません。証拠は次章の研究です。なお、Stanfordの研究（Perryら、2022）は、AIアシスタントを使った人のほうが安全性の低いコードを書き、しかも自分のコードは安全だと強く信じていたと報告しています。だから、確認されていないインストールコマンドを心配するのには根拠があります。あわせてAIが書いたコードのレビューとAIを鵜呑みにしてはいけない理由もご覧ください。

5. 研究と事件の数字#

読み方： この表は2つの別のことを示しています。AIがパッケージ名を作り出すこと、作られた名前が登録されて人にインストールされうることには、良い証拠があります。それが実際にどれだけの被害を生んでいるかについては、良い証拠がまだありません。

6. 明日から使える習慣#

食材の受け入れ手順のある厨房とイメージしてみましょう。新しい食材にはレシートと受け取りのサインが必要で、誰でも勝手に倉庫へ入れてよいわけではありません。

6.1 8つのステップ#

1. ロックファイルでバージョンを固定し、CIやクリーンなマシンではnpm installの代わりにnpm ciを使います。npmの文書によると、npm ciはロックファイルのとおりにインストールし、package.jsonとずれていればエラーになります。
2. 新しいパッケージはインストール前に確認します。 作成日、ダウンロード数、実在して一致するソースリポジトリ、メンテナー、バージョン履歴。先週作られたのに、ちょうど必要な名前をしているパッケージは、立ち止まるサインです。
3. インストールスクリプトは既定で止めます。 --ignore-scriptsか、.npmrcのignore-scripts=trueを使います。信頼すると決めたパッケージだけ有効にします。
4. 許可リストか社内ミラー（private registry mirror）を使います。承認済みのパッケージだけが入り、知らない名前は見つかりません。
5. プロベナンスを確認します。 パッケージにある場合はnpm audit signaturesを使います。分かるのは出どころであり、きれいだという保証ではないことを忘れないでください。
6. エージェントのインストールコマンドは、必ず人が承認します。 インストールや見知らぬコードの実行に自動承認を有効にしないでください。
7. エージェントはサンドボックスかdevcontainerで動かし、本物のキー、デプロイ用トークン、本番への書き込み権限は中に入れません。
8. すべてのPRでロックファイルの差分を読みます。 新しいパッケージはあるか、名前は何か、どのレジストリか。これはAIが書いたコードのレビューのチェックリストにも入っています。

6.2 覚えておきたい4つのコマンド#

# 1. ロックファイルのとおりに、インストールスクリプトを動かさずにインストール
npm ci --ignore-scripts

# 2. インストール前に確認: 作成日、メンテナー、リポジトリ
npm view some-package time.created time.modified maintainers repository.url
curl -s https://api.npmjs.org/downloads/point/last-week/some-package

# 3. インストール済みのものの署名とプロベナンスを確認
npm audit signatures

# 4. エージェントの変更後: ロックファイルに新しいresolved行はないか
git diff package-lock.json | grep '^+.*"resolved"'

Pythonでは、似たコマンドとしてpip install --require-hashes -r requirements.txtがありますが、各パッケージのハッシュ付きの要件ファイルが必要です。ツールごとに書き方が違うため、お使いのツールの文書を確認してください。

6.3 インストール前の10の質問#

1. このパッケージ名はレジストリに実在しますか。確認はレジストリのページで行いましたか、それとも記憶ですか。
2. いつ作られましたか。数週間未満なら疑います。
3. 週あたりのダウンロード数は、この種のパッケージとして妥当ですか。
4. パッケージ名と一致する公開のソースリポジトリはありますか。
5. メンテナーは誰で、実績はありますか。
6. インストール時にスクリプトを動かしますか。
7. 同じ仕事をする、より有名なパッケージはありませんか。
8. このインストールコマンドは自分のものですか、それとも誰も承認していないエージェントのものですか。
9. このパッケージが悪意あるものなら、このマシンで何に触れられますか。
10. インストール後、ロックファイルは何行増え、それを読みましたか。

7. バランスよく：分かっていることと不明なこと#

かなり確か： モデルはパッケージ名を作り出します。実験での測定値は数パーセントから20%超まで幅があります。偽の名前は繰り返されうるし、作られた名前は登録でき、本物の人がインストールします。

不明なこと：

• 新しいモデルやツールでの作り出しの割合。多くのツールはいまWebを検索したりパッケージ名を確認したりするので、割合が下がっているかもしれません。ツールごとの独立した測定は、私は見ていません。
• 実際の被害。大きな被害が確認されたスロップスクワッティング攻撃は見つけられませんでしたが、見つからないことは起きていないことを意味しません。
• 実験は、研究者が無害なパッケージを登録して行ったものです。本物の攻撃者は公表しません。

大げさに考えないでください。 2026年5月のnpmワームのような大きなサプライチェーン事件は、本物のパッケージの乗っ取りから起きています。スロップスクワッティングだけを防ぐと、リスクの大半を見逃します。第6章の習慣はどちらにも効きます。

軽く見ないでください。 予防は安く（上の例で1人あたり月約10分）、確認なしにパッケージを入れるエージェントは、アクセスキーやソースコードに触れられます。AIアプリのOWASP Top 10は、サプライチェーンのリスクをより広い地図の中に置いています。エージェントがMCP経由でツールを呼ぶなら、MCPとは何かも読んでください。ツールのひとつひとつも、自分のところへ入れているものだからです。

8. 結論#

AIが作った名前は、誰かが登録し、どこかのマシンが自動でインストールするまでは無害です。リスクの大半は「誰も見ていない」ところにあります。インストールコマンドに関所を作りましょう。バージョンを固定し、新しいパッケージを調べ、スクリプトを止め、エージェントに承認を求めさせ、ロックファイルを読みます。

参考資料#

数字は2026年10月時点の公開情報によります。同じ数字でも媒体によって伝え方が違うことがあり、二次的なノートは参考用です。引用する前に、必ず元の資料を開いて確認してください。

• Spracklenら、We Have a Package for You! A Comprehensive Analysis of Package Hallucinations by Code Generating LLMs（USENIX Security 2025）
• Lasso Security、AI Package HallucinationsとThe Register（huggingface-cliの実験）
• Aikido Security、react-codeshiftとスキルファイル内の架空のnpxコマンドに関する記事（2026年）
• 用語の由来（伝聞、元の投稿は未確認）：Wikipedia, SlopsquattingとAndrew Nesbitt, Slopsquatting meets dependency confusion
• Cloud Security Alliance、Mini Shai-Hulud: npm Worm Targets AI Developer Supply Chain（二次的な調査ノート、2026年5月17日）
• npm Docs、Generating provenance statementsとnpm ciコマンド
• Pearceら、Asleep at the Keyboard?（2021年）とPerryら、Do Users Write More Insecure Code with AI Assistants?（Stanford、2022年）

AIを仕事に取り入れるプログラマー、製品に関わる人、チームリーダーのための記事です。むずかしい言葉には短い説明を付けます。

筆者は弁護士ではなく、この記事は法的助言ではありません。 2つの事例は、公開された情報源（法律事務所の要約、報道、オープンな百科事典）から語り直したもので、判決の原文からではありません。「責任の地図」と最後の5つのことは私の意見で、規則ではありません。

先に要点#

• 実際の2つの事例は、**「AIがやったのであって、私ではない」**が誰も助けないことを示しています。
• AIの出力を使う人も、AIを顧客の前に出す側も、確認する役目があります。
• 責任は、ひとりでに持ち主を見つけません。事故の前に名前を付けます。
• チームが今すぐできる5つのこと：責任者1人、リスクの高いところの確認、ログ、人への経路、責めない書き残し。

むずかしい言葉をやさしく#

1. 事例その1：航空会社のチャットボットが間違えた#

法律事務所Manattの要約によると、Moffattという乗客が、エア・カナダのサイトのチャットボットに、忌引き運賃について尋ねました。チャットボットは、通常の航空券を買い、90日以内に差額の払い戻しを申請できると答えました。けれど航空会社の実際の方針は、搭乗後の払い戻しを認めていませんでした。申請すると、航空会社は断りました。

航空会社は、その要約によれば、チャットボットは別の法的な主体で、その言葉に航空会社は責任がないと主張しました。ブリティッシュコロンビア州の民事の解決審判所（Moffatt対エア・カナダ、2024 BCCRT 149）は、この主張を退け、航空会社には注意義務があり、過失による不実表示をしたと判断しました。航空会社は差額を払い戻すことになり、金額は650.88カナダドルと伝えられています。

考える価値があるのは、金額は小さくても、原則は小さくないことです。顧客には、サイトのどのページが「正しく」、どれが「チャットボットのでたらめ」かを知る理由がありません。

2. 事例その2：AIが作り出した判例を弁護士が提出した#

Mata対Avianca（ニューヨークの連邦裁判所、2023年）で、原告の弁護士は、いくつもの判例を引用した書面を提出しました。相手方がそれを見つけられずにいると、ChatGPTが作り出したもので、弁護士は確認していなかったと分かりました。2023年6月22日、裁判官は合計5,000ドルの制裁金を科し、弁護士が「責任を放棄した」と述べました（Wikipedia、Bloomberg Law、Above the Lawによる）。

この事例から私が取るもの：道具は署名せず、使う人が署名する。下書きが機械で書かれたからといって、確認する義務は消えません。

3. 2つの事例、1つの型#

どちらも、最後の段階で確認する責任を持つ名前のある人が欠けていました。

4. 責任の地図（私の意見）#

AIが間違えたとき、たいてい4つの当事者がいて、それぞれに役目があります：

どの地域でも、法の前で「正しい」分担がどうなのかは、私には分かりません。この表は仕事の分け方にすぎず、チームで全員が誰かが担当していると思い込まないためのものです。

5. チームが今すぐできる5つのこと#

1. AI機能ごとに責任者を1人決める。 「チーム」ではなく名前。その人は、機能が何をし、どう測り、どう止めるかを知っている。
2. リスクの高いところに人の確認を置く。 お金、健康、法律、個人情報、元に戻せないこと。リスクの低いところ（タイトルの提案）は緩くてよい。確認と権限の制限については、AIが書いたコードのレビューとAIアプリのOWASP Top 10を参照。
3. 何が起きたかたどれるようにログを残す。 苦情が来たとき、AIが誰に、いつ、何を根拠に何を言ったかを知る必要がある。
4. 人への経路を用意し、顧客に知らせる。 AIに自信がないとき、顧客が「人と話したい」と言ったとき、道がなければならない。機械と話していることをはっきり伝え、機械の言葉が、そうでないのに約束のように聞こえないようにする。
5. 個人を責めずにインシデントを書き残す。 「誰がやったか」でなく「仕組みはどうやってこれを許したか」を問う。GitLab 2017とAmazon S3 2017の話は、仕組みに目を向けてインシデントを語る例。確認が必要な理由はAIをうのみにしない理由で扱っています。

6. よくある落とし穴#

• 「AIがやったのであって、私ではない」。 上の2つの事例は、この主張が弱いことを示しています。
• 形だけの承認。 確認者が1日に何百回も読まずに承認を押す。紙の上の名前は、本当の確認ではありません。
• 連なりの最後にいる個人を責める。 最後のボタンを押した人は、統制のない仕組みの、最後の輪にすぎないことが多い。
• すべて提供者に押し付ける。 契約が、相手の責任を限っているかもしれません。思い込まず、読む。
• ログを残して守らない。 ログには顧客の言ったことが入っており、他の個人情報と同じように慎重に保管する必要があります。
• 責任者を決めたのに、機能を止める権限を与えない。

7. バランスの取れた見方#

• 2件だけで、二次的な情報源を通しています。 要約、報道、オープンな百科事典で読んだもので、判決の原文ではありません。細部が欠けているかもしれません。
• 法は地域で違います。 ブリティッシュコロンビア州の審判所の判断が、自動的に他の場所へ当てはまるわけではありません。
• すべてを確認するのは非現実的です。 だから記事はリスクが高いところを言っています。リスクが低いところは、確認が少なくてもよい。
• 責任の地図は仕事の分け方であって、法の前での責めの分け方ではありません。
• 偏った見方をしているかもしれません。 2件とも、報道が注目した事例だからです。AIが間違えても、誰も訴えないことは多いのです。

8. 結論#

AIツールは速く下書きできますが、署名はせず、制裁金も科されません。責任は、結果を出した人と組織に残ります。すべきことは、事故の前に責任へ名前を付け、間違いの代償が大きいところに確認を置き、責める人を探さずにインシデントから学ぶことです。

今日の小さな一歩：動かしているAI機能を1つ選び、**「明日の朝、顧客に間違ったことを言ったら、誰が最初に気づき、誰が止めると決めるのか」**と問うてください。まだ答えられないなら、それが最初の仕事です。

参考資料#

• Manatt：AI Gone Wild, Airline Has to Honor a Refund Policy（二次的、法律事務所の要約）
• Wikipedia：Mata v. Avianca, Inc.（二次的）
• ブログ内の関連記事：AIが書いたコードのレビュー、AIアプリのOWASP Top 10、AIをうのみにしない理由、間違ってデータを消した日：GitLab 2017、間違いの1コマンド、4時間：Amazon S3 2017

製品に関わる人、チームリーダー、AIを製品に組み込むプログラマーのための記事です。技術用語には短い説明を付けます。

3つの層への分け方と指標は、実務家の手引き（ブログ、ツールの文書）から取りました。これは二次的な情報源です。この記事の閾値と数字はすべて例で、標準ではありません。お店「ホン」の例は、作り直したものです。

先に要点#

• 利用回数は成功ではありません。仕事の結果を測ります。
• 3つの層を同時に測ります：品質、費用、信頼。1つの層だけでは盲点が生まれます。
• 正しい費用は、成功した結果あたりの費用で、レビューの手間を含みます。
• 受け入れ率が高いのは、過信かもしれません。evalsの合格率と並べます。
• 1ページの表を使い、指標が悪化したとき何をするかを先に決めます。

むずかしい言葉をやさしく#

1. なぜ1つの数字で測らないのか#

数えやすいものから始めるのは簡単です：呼び出しの回数、利用者の数。けれどAI機能は、とてもよく使われても悪いことがあります：間違って答える、費用がかさむ、利用者に黙って無視される。

実務家の手引き（要約で読みました）は、2点で一致します：呼び出しを数えるのは浅く、大事なのは完了した仕事であること。そして、指標は層に分けること。1つに集中すると盲点が生まれるからです。よくある例：95%正しいモデルも、利用者が信頼しなければ役に立たない。

だから3つの層に分けます：

この記事はAI機能のための評価を書く（品質の層）と、生産性をコードの行数で測らない（活動の指標が誤解を招く理由）につながります。

2. 品質の層#

品質は、1つの「正確さ」の数字ではありません。エラー分析から取ります：evalsの記事のように、失敗を分類にまとめて数えます。

提案する指標：

• 失敗の分類ごとの合格率。 たとえば「意図の読み違え」「情報のでっち上げ」「口調が硬い」。分類ごとに1つの数字。
• 重大な失敗の件数。 でっち上げた価格は、口調の失敗とは全く違います。実際の結果を伴う失敗は、別に数えます。
• 全体の合格率。ただし、それだけを唯一の数字にしない。

「すべて合格」の数字を出し、それから各分類に掘り下げます。evalsの手引きも、段階評価でなく合格か不合格を勧めています。

追い方： モデル、プロンプト、データを変えるたびにevalsを動かし直します。モデルを変えて動かし直さなければ、品質がどう動いたか分かりません。

3. 費用の層#

3.1. 呼び出しあたり、成功した結果あたりの費用#

呼び出しあたりの費用は、得やすい数字です。けれど機能が、モデルを安く呼びながら、人の修正が多く要るかもしれず、使える結果1つに多くの呼び出しが要るかもしれません。だから比べる価値のある費用は：

成功した結果あたりの費用 =（モデルの費用 + 基盤 + レビューや修正をする人の手間）÷ 成功した結果の数

例（作り直した数字）：お店「ホン」の顧客対応アシスタント、1か月。

モデルの費用だけを見れば、2,000万を10,000回で割って、1回2,000ドン。職員の手間と1,000件の失敗を見落とします。だから「成功した結果あたりの費用」のほうが、多くを明らかにします。

3.2. 遅延#

遅延は、平均だけでなくp95（とp99）で測ります。平均は最も遅い場合を隠しますが、利用者が離れるのはそこです。チャットの機能では、最初の言葉までの時間が、速いという感覚を大きく左右します。

4. 信頼の層#

最もよく省かれる層です。利用者の行動を見ます：

絶対的な水準だけでなく、傾向を見ます。 修正率の急な跳ね上がりは、個人に合わせた結果でなく、品質の低下の印だと述べる手引きもあります。

背景： Stack Overflowの2025年調査（回答者4万9千人超）では、46%がAIの正確さを信頼せず、強く信頼するのは3%だけでした。あなたの製品の利用者も、似た気持ちかもしれません。信頼は得るものであり、測るものです。

5. 落とし穴：高い受け入れ率は過信かもしれない#

この記事で、私が最も重要だと思う点です。利用者が出力の90%を受け入れているのに、evalsでは実際に正しいのは75%だけなら、15ポイントの差は、利用者が過信していることで、良い機能ではありません。

読み方： 受け入れ率を、evalsの合格率と並べます。

これらの率が、普通どのくらいかを言えるデータは、私にはありません。これは指標の読み方で、測定結果ではありません。

6. 1ページの表#

9つの指標、3つの層を、毎週記録します。

組み合わせます： 速度や費用の指標には、必ず品質の指標を添えます。費用が下がり、合格率が落ちるのは、進歩ではありません。

7. 指標が悪化したときのことを先に決める#

行動の規則のない表は、飾りです。例で、閾値は作り直したものです：

具体的な閾値は、機能のリスクによります。お金について答える機能は、タイトルを提案する機能より厳しい閾値が要ります。

8. よくある落とし穴#

• 利用だけを測る。 よく使われても、良いとは限らない。
• いいね、よくないねだけ。 押す人は少なく、両極に偏る。行動（修正、上書き）と組み合わせる。
• 費用にレビューの手間を忘れる。 モデルの費用は安くても、総費用は安くないかも。
• 平均が裾を隠す。 p95と最悪のケースを見る。
• evalsを動かし直さずにモデルを変える。
• 指標を目標にする（グッドハートの法則）：受け入れ率に報いれば、人は品質を上げずに、数字をよく見せる。

9. バランスの取れた見方#

• 二次的な情報源です。 3つの層への分け方は、実務家の手引き（ブログ、追跡ツールの文書）から来ており、独立した研究ではありません。
• 閾値の標準はありません。 ここの数字はすべて例です。機能の種類ごとに、「普通の」受け入れ率や修正率がどのくらいかは分かりません。
• 測ることは手間がかかります。 小さな実験なら、絞った1ページの表（品質、費用、信頼の指標1つ）で足ります。
• 指標は、利用者の声を聞くことの代わりになりません。 毎週、実際のやり取りをいくつか読んでください。
• お店「ホン」の例は作り直したもので、式を示すために私が作った数字です。

10. 結論#

良いAI機能は、最も多く呼ばれる機能ではなく、正しい結果を、妥当な費用で出し、適度に信頼されている機能です。3つの層を同時に測り、成功した結果あたりの費用を計算し、受け入れ率を合格率の隣に置いて読みましょう。

今日の小さな一歩：動かしているAI機能を1つ選び、成功した結果あたりの費用を計算し（修正の手間を足すのを忘れずに）、いつも使う数字と比べてください。

参考資料#

• Antoine Buteau：AI product metrics, economics and support burden（二次的、実務家の手引き）
• PostHog：Product metrics to track for LLM apps（二次的）
• Hamel HusainとShreya Shankar：LLM Evals, Everything You Need to Know
• Stack Overflow Developer Survey 2025、AIの章
• ブログ内の関連記事：AI機能のための評価を書く、生産性をコードの行数で測らない、バイブコーディングで1日でプロトタイプ

これは実話ですが、私自身の話ではありません。AWS自身が公表した事後報告（末尾にリンク、直接読みました）に沿って振り返ります。報告はコマンドを実行した人の名前を挙げていないので、私も名前を付けず、その人が何を考えたかも推測しません。

この記事はGitLab 2017の話と1点で違います：これはバックアップが壊れていた話ではなく、1つの打ち間違いで、あまりに多くを外せるツールの話です。記事の時刻は、報告と同じ太平洋時間（PST）です。

先に要点#

• 2017年2月28日の午前9:37、S3チームの権限を持つメンバーが、課金に関わるサブシステムから少数のサーバーを外すコマンドを実行しました。入力の1つの打ち間違いで、意図より多くのサーバーが外れました。
• 外れたサーバーは、S3の中核の2つのシステム、インデックスと配置を支えていました。両方が完全に再起動される必要がありました。
• US-EAST-1のS3は、約4時間17分後の午後1:54にやっと正常に戻りました。
• 注目点：コマンドは作られたとおりに動いたのです。外しすぎを止めるものがなかっただけ。AWS自身のサービス状態の表示板も、S3に依存していました。
• AWSはツールを、よりゆっくり外し、最小を下回って外さないように変えました。

むずかしい言葉をやさしく#

1. いつもの運用作業#

その朝、S3チームは、US-EAST-1で遅く動く課金処理をデバッグしていました。権限を持つチームメンバーが、既存の手順書に従い、課金に関わるサブシステムから少数のサーバーを外し、効果があるか見ようとしました。

特に変わったことはありません。サブシステムからサーバーを外すのは、運用者の日常の仕事で、手順書もありました。大事な点です：これは、許された操作で、手順に従い、権限のある人が行ったものでした。

2. 午前9:37：入力の打ち間違い#

報告によると、コマンドは9:37に実行され、入力の1つが間違って入力されました。結果：意図より多くのサーバーが外れました。

報告は、どの入力か、どう間違ったか、なぜかを述べていません。私は推測しません。自信を持って言えるのは、ツールがその値を受け取って実行したことで、「このコマンドは何台を外し、それは安全か」を確かめる関門はなかったということです。

外れたサーバーは、課金のシステムでなく、2つの中核システムのものでした：

• インデックス： リージョン内のすべてのオブジェクトのメタデータと位置の情報を持つ。取得、一覧、書き込み、削除の依頼に必要。
• 配置： 書き込みの依頼で、新しいオブジェクトの保存先を割り当てる。インデックスが正しく動くことに依存する。

それだけの容量が外れると、両方が完全に再起動される必要がありました。

3. 再起動：何年もやっていなかったこと#

これは、報告の中で私が最も考える価値があると思う細部です。AWSは、大きなリージョンで、これらのシステムを何年も完全には再起動していなかったと書いています。その間にS3は大きく成長し、安全な再起動に必要なメタデータの整合性を確かめる安全確認が、再起動を予想より長くしました。

言い換えれば：復旧する力は、今の規模では一度も試されていなかったのです。GitLabの教訓と響き合います：復元を試したことのないバックアップは、使えるか分からず、実際の規模で動かしたことのない再起動の手順は、どのくらいかかるか分かりません。

4. 時系列#

すべて太平洋時間、2017年2月28日、US-EAST-1リージョン。

9:37から午後1:54までは約4時間17分です。報告は、各再起動それぞれの所要時間を挙げていません。

5. 誰が影響を受けたか、そして表示板の皮肉な細部#

報告によると、影響を受けたサービスには、S3のコンソール、新しい仮想マシン（EC2）の起動、S3に保存されたスナップショットのデータが要るEBSボリューム、AWS Lambdaがありました。一部のサービスは、中断の間にたまった作業があり、回復に追加の時間が要りました。

皮肉な細部： AWSのサービス状態の表示板の管理コンソールも、S3に依存していました。11:37まで、個別のサービスの状態を更新できなかったので、AWSは、Twitterのアカウントとページ上部の文言で伝えるしかありませんでした。

一般的な教訓（私の推論）：障害を知らせるツールは、壊れているものそのものの上に置かない。

6. 1つの間違ったコマンドが、大きな障害になった理由#

報告から、1つの打ち間違いを4時間の中断に変えた5つの層が見えます。この読み方は私のものです。

共通点：各層は、単独では妥当で、重なったときだけ障害になります。

7. AWSが直したこと#

報告によると：

• よりゆっくり外す。 容量を外すツールは、より低い速さで外すよう変えられました。
• 最小。 サブシステムを必要な最小容量より下げる削除をすべて遮る仕組みが加わりました。
• 他のツールの見直し。 AWSは、他の運用ツールに、同様の安全確認がないか調べています。
• 影響範囲を小さくし、復旧を短く。 サブシステムを独立したセルに分けます。年内の予定だったインデックスのサブシステムの分割は、前倒しですぐに始められました。
• 複数のリージョンにまたがって動く表示板。

全体として、AWSは誰かが打ち間違えるのを禁じることに重点を置かず、打ち間違いが大きな害を生めないようにすることに重点を置きました。

8. GitLabの話との比較#

2つは「1つの間違ったコマンド」という型を共有しますが、教訓の場所は違います：

合わせて：間違ったコマンドを打ちにくくし、その結果を小さくする。

9. 私が学ぶこと：外せるツールへの問い#

この部分は私の提案で、AWSの結論ではありません。 外す、消す、止めることができるツールを書く、または使うなら、問います：

1. 最小はあるか？ ツールは、システムを安全な水準より下げる操作をすべて遮るか。
2. 速度の制限はあるか？ ゆっくり外せば、運用者が間違いに気づく時間ができる。
3. 事前の確認はあるか？ 一覧表示のみのモード：外す前に「これはN台を外す」。
4. 影響範囲はどれだけか？ 1つの間違ったコマンドで、最大どれだけ壊れるか。
5. 実際の規模で復旧を試したか？ システム全体を最後に再起動したのはいつか。
6. 障害を知らせるツールは、独立して動くか？
7. 危険な操作を、2人目が見られるか？

10. AIがツールを動かせるとき#

この話は2017年ですが、型はとても現代的です：外す力を持つツールが、間違った入力を受け取り、何も止めない。 AIエージェントでは、間違った入力は、誘導された指示から来るかもしれず、エージェントは「何かおかしい」とは感じません。

それがAIアプリのOWASP Top 10の**過剰な権限（LLM06）**です：過剰な機能、過剰な権限、過剰な自律。そこでの対策は、AWSの教訓と重なります：機能を限り、最小限の権限、影響の大きい行動は承認を求める。記事MCPとは何かはヒューズについて述べ、S3の最小こそ、1つのヒューズです。

11. バランスの取れた見方#

• 主な情報源は1つです。 私はAWS自身の報告に拠っており、報告はAWSの立場から書かれています。
• 報告は多くの細部を省いています。 名前も、具体的な打ち間違いの値も、各再起動の所要時間もないので、推測しません。
• 比較と「5つの層」の表は、私の読み方です。
• 障害は10年近く前のことです。 システムは大きく変わりましたが、原因（最小がない、大きな影響範囲、試されていない復旧、壊れたものに依存するツール）は、今もとても身近です。
• コマンドを実行した人がどう感じたかは分かりませんので、記事はそれを描きません。

12. 結論#

1つの打ち間違い、4時間、そしてインターネットの一部が遅くなりました。けれど、AWSが直すと選んだのは、「運用者に打ち間違えるなと言う」ことではありません。間違ったコマンドが外しすぎないようツールを、結果が小さくなるようシステムを直したのです。それが、最も学ぶ価値のある考え方です。

今日の小さな一歩：使っている、外す、または消すことができるツールを1つ見つけ、最小とプレビューのモードがあるか確かめてください。なければ、やることに加えます。

参考資料#

• AWS：Summary of the Amazon S3 Service Disruption in the Northern Virginia (US-EAST-1) Region
• ブログ内の関連記事：エンジニアが間違ったデータを消した日：GitLab 2017年の話、AIアプリのOWASP Top 10、MCPとは何か？コンセントで説明する

AIが関わるコードを書く人、レビューする人のための記事で、初心者も対象です。技術用語には短い説明を付けます。

コードの例とその数字は、イメージしやすいように作り直したものです。「カバレッジ100%、ミューテーションスコア4%」は、論文の要旨から取りました（全文は読んでいません）。名前を挙げたツールは例にすぎず、動かしていません。方法は私の提案です。

先に要点#

• AIがコードとテストの両方を書くと、テストは要件でなく、コードを確認するだけになりがちです。
• 緑のテストでは足りません。 高いカバレッジでも足りません：100%を覆っても、ほとんど不具合を捉えないスイートがあります。
• 正しい問いは「テストは緑か」ではなく、**「コードが間違っていたら、テストは赤になるか」**です。
• 7つの方法：仕様から書く、先に赤を見る、自分で壊す、ミューテーションテスト、プロパティベース、境界値の表、実際に動かす。
• 最も安いことから：手でコードを壊して、テストを見る。

むずかしい言葉をやさしく#

1. 問題：テストを書く人が、コードも書いた人#

1人がコードを書いてからテストを書くとき、たいてい同じ理解を両方に持ち込みます。要件を誤解したなら、コードは間違い、テストも一緒に間違うので、緑になります。AIでは、さらに起きやすい：AIはコードができた後にテストを書き、そのコードが見えているので、テストはコードがしていることに合わせて作られがちです。

だからAIが書いたコードのレビューの15項目には、テストについての2つの項目があります：テストは大事なことを確かめているか、そしてAI自身が書いたテストは、コードを壊して赤になるか見ること。

これは単なる感覚ではありません。言語モデルでミューテーションに導かれてテストを生成する論文（MutGen、2025年）は、カバレッジは不具合検出の弱い指標だと論じ、**カバレッジ100%でも、ミューテーションスコアは約4%**というスイートに触れています。私は要旨を読んだので、この数字は、一般的な統計でなく、問題を示す例として扱ってください。

2. 例：50万の境界#

作り直した例。 要件：50万以上の注文は10%引き。

AIが書いたもの：

function discount(total) {
  return total > 500000 ? total * 0.9 : total;
}

test("大きな注文は10%引き", () => {
  expect(discount(600000)).toBe(540000);
});

test("小さな注文は割引なし", () => {
  expect(discount(100000)).toBe(100000);
});

2つのテストとも緑で、カバレッジは100%。でもコードは間違っています：要件は「50万以上」なのに、コードは>を使っているので、ちょうど500,000の注文が割引されません。

手で壊す。 >を>=に変える。つまり、コードを要件に合うよう直すのです。テストを動かし直す：まだ緑。つまり2つのテストは、境界で、間違ったコードと正しいコードを見分けられません。これを「生き残った変異体」と呼びます。

仕様からテストを1つ足す：

test("ちょうど500,000は割引される", () => {
  expect(discount(500000)).toBe(450000);
});

これは、今のコードでは赤で、直した後は緑です。価値のあるテストです：コードが間違っているとき失敗するのですから。

3. テストの価値を保つ7つの方法#

方法1：コードでなく仕様からテストを書く#

コードでなく要件を見て、例を書きます。記事仕様駆動開発は、変わったケースも含め、受け入れられる例を3〜6個、先に書くことを勧めます。それがまさに、必要なテストです。

AIにテストを書かせざるをえないなら、コードだけでなく、仕様と例を渡してください。

方法2：先にテストが失敗するのを見る#

直す前にテストを書き、動かし、正しい理由で失敗するのを見て、それから緑に直します。一度も赤を見ていないテストは、何かを捉えられるか分からないテストです。

Anthropicの実践ガイドは、エージェントへの依頼の例で、まさにこの考えを使っています：「再現する失敗するテストを書き、それから直して」。

方法3：自分でコードを壊す#