AIエージェントの失敗 2,227 件のうち 36% は、CLAUDE.md の 1 行で消えるものだった

著者は自分のコーディングエージェントのセッションログ1,920本から、ツール呼び出し43,771回のうち失敗2,227回（5.1%）を集めた。目的は失敗の多いツールを特定して直すことだった。しかしツール別の分類は決め手にならず、代わりに出てきたのは直感に反する数字だった。1〜3手のセッションでは1手あたり23.10%が失敗し、100手以上では2.25%まで下がる。上位2型は、cdしてからgitを実行して止められるケースと、存在しないファイルを読もうとしたケースで、全体の50.2%を占めていた。

ここで面白いのは、著者が「短いセッションほど危ない」という数字をそのまま記事にしなかった点だ。ツールの型、失敗の型、プロジェクトの偏りと切り口を変えて4回書き直し、最後に安全ガードを1種類だけ除外したところで12倍の傾きは消えた。短いセッションが危ないのではなく、短いセッションに特定の作法違反が集中していただけだった。数字は正しく、読み方が間違っていた。社内の業務データを眺めるときも、「多い」「少ない」の比較は母集団の偏りを先に疑うべきだ。さらに、一度失敗すれば覚えるはずだという期待も、同じ型が同じセッション内で何度も繰り返される記録とは噛み合わない。

残ったのは、失敗の3分の1以上を占める1種類の作法違反だ。著者によれば、それはバッチ実行時に必ず起きており、CLAUDE.mdに1行書けば消えるものだった。中小企業でAIに作業を任せているなら、まずログから「毎回教え直している作法」を数え、1行のルールとして固定するのが最も安い改善になる。ただし、is_errorには実行前の安全ガードによる停止も含まれる。失敗の定義を先に決めないと、数字はたやすく別の意味を持つ。