Claudeでなぜなぜ分析するときのコツ

アプリ開発講座④AIのなぜなぜ分析が浅くなる理由と、2軸の横並びチェック

「なぜを5回」と頼んでも2〜3回で止まる。横並びチェックしたのに同じバグが再発する。その原因と直し方を、実運用版のSKILL.md全文つきでまとめました。

バグを1件直しました。なぜなぜ分析もしました。横並びチェックも頼んで、「他に該当箇所はありませんでした」という報告も受け取りました。それなのに、数週間後に同じ原因のバグが別の画面で出てくる。

わたしも同じことをやりました。しかも、コミット直前のレビューで指摘されるまで気づきませんでした。検索の軸を変えて探し直したら、1本目では0件だった箇所がまだ残っていました。

原因は掘り下げの深さではなく、探し方の軸にありました。

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

・AIの「なぜ」が2〜3段で止まったとき、役割を指定して5段目まで掘り直させられる ・1本の検索で「該当なし」と言われても、別の軸から探し直して残りを拾える ・以上を毎回指示せずに、バグ修正を頼むだけで自動で回せる

こんな人におすすめ

・AIに「なぜを5回」と頼んでも、2〜3回で止まってしまう人 ・横並びチェックを頼んだのに、後から同じ原因のバグが別の場所で出てきた人 ・再発防止策が「ドキュメントに書いておきます」で毎回終わってしまう人

読む前に、順番の確認だけ

・Claude Codeなどのコーディング用AIをまだ使っていない人は、先に①要件定義編へ。Claude Codeを動かすところまで済ませてから、この記事に戻ってきてください
・ターミナル（パソコンに文字でコマンドを打つ画面のことです）をまだ一度も開いたことがない人も、同じく先に①へ。この記事のコマンドは、すべてClaude Codeにそのまま貼れる形で載せてあります
・pytest / mypyをまだ入れていない人（完了条件の「テスト全グリーン」「型チェック」がそのままでは満たせません。6ステップのうち5つは使えます）
・今回はバグを直しきるところまでで、再発防止までは手を広げないと決めている人には、後半が過剰かもしれません
・チーム開発で、コミットメッセージの書式を自分の一存では変えられない人。6ステップのうち、記録の型を決める最後の1つが使えません

②を読んだ方へ：この記事は何が違うか

②で渡した簡易版SKILL.mdは約50行で、「2つの角度から探す」とだけ書いてありました。この記事はその角度の中身（動詞軸と受け手軸）、両方をすり抜ける3種類の書き方、0件が偽物かどうかの確かめ方、3件以上でlint化を必須にする線引きを、コマンドと160行のSKILL.md全文で埋めます。②の簡易版はそのまま差し替えられます。

このシリーズの5記事について

Claude Codeでアプリを作り、育てていくまでを5本に分けて書いています。

① 要件定義編 ── 何を作るかを、Claude Codeに伝わる形で言葉にする
② 計画→実装→テスト・なぜなぜ分析編 ── 仕様書からアプリを組み上げ、不具合を根本から直す
③ 技術的負債を、AI自身にあぶり出させる ── まだ表面化していない問題を、先回りで洗い出させる
④ AIのなぜなぜ分析が浅くなる理由と、2軸の横並びチェック ── 見つけた1件を、二度と再発しない形で直しきる （この記事）
⑤ セキュリティ監査編 ── 人に使ってもらう前に、危ない箇所を洗い出す

番号は公開順です。読む順ではありません。はじめてアプリを作るなら①②、人に使ってもらう前に⑤、アプリが育ってきたら③④、の順が自然です。どの記事から読んでも単体で完結します。

5本とも、コードを書いたことがない方が読める形にしてあります。③④はコマンドの結果を読む場面が出てきますが、打つのはClaude Codeなので、読んで判断できれば足ります。

5本を通して一貫しているのは、AIの出力をそのまま信じないという姿勢です。要件定義書も、実装も、AIが出したバグや脆弱性の指摘も、要所で人間が確かめる。その確かめ方を各記事で具体的に扱っています。

5本を個別に買うと4,020円ですが、マガジンなら1,500円です。3本以上読む予定なら、そちらのほうが安くなります。今後追加する回も、追加料金なしで読めます。

直したはずのバグが、別の場所から顔を出す

冒頭に書いた再発は、運が悪かったわけではありません。横並びチェックのやり方に、構造的な取りこぼしがあるからです。この記事では、その取りこぼしがなぜ起きるのかと、二度と起こさないための手順を扱います。

扱うのは3点セットです。(1) 掘る（なぜなぜ分析で根本原因まで下りる）、(2) 洗い出す（横並びチェックで同型箇所を全件拾う）、(3) 機械化する（再発防止をlintかtestに落とす）。

欠陥部品のリコールに近い作業だと思ってください。1台で不具合が出たら、同じ部品を使った車を全部点検する。そして次のロットから設計を変える。(3)が抜けると、点検した先から同じ部品がまた使われます。

以降の実例とコマンドは、わたしが実際に運用しているPython製のプロジェクトから採っています。言語やアプリの種類が違っても、考え方はそのまま使えます。

実際に起きたこと：1軸で検索して「該当なし」、実は4箇所残っていた

わたしがPythonで書いた、株価チャートの分析ツールでの話です。

日時の扱いに関するバグを直しました。原因のパターンをastimezone(JST)というメソッド呼び出しだと特定しました。日時を日本時間に変換する処理です。それでコード全体を検索した結果が「他に該当なし」。そう判断して、コミットの手前まで進みました。

ところが、コミット直前のレビューで指摘が入ります。同じ関数の中に同型の箇所がある、と。ここでひやりとしました。

そこで検索の仕方を変えて、今度は「日時の値そのもの」を軸に探し直しました。すると、4箇所の同型パターンが残っていることが分かりました。

なぜ最初の検索で見つからなかったのか。答えは単純です。

同じ種類の問題でも、コード上の書かれ方は複数に分裂するからです。

この例では、日時を扱う操作がastimezoneだけではありませんでした。strftimeやisoformatにも分かれていたのです。同じ問題を表す操作の名前が3種類あったことになります。そのうちの1つで検索した時点で、残り2種類は最初から視界に入っていません。

このほかに、関数呼び出しの形をしていない「文字列への直接埋め込み」も1種類ありました。こちらは後半で別立てに扱います。

ここから得られた教訓がこれです。

実際この件では、検索の軸を変えた瞬間に4箇所が出てきました。「該当なし」は、探していなかっただけだったわけです。あのときレビューがなければ、そのままコミットしていました。

対処法は、検索を2軸に分けることです。中身を先に書いておきます。

• 動詞軸：どんな操作をしているか（API名・演算子・メソッド名）

• 受け手軸：何に対して操作しているか（変数名・属性名・型）

この2本を、別々のコマンドで流します。動詞軸で漏れたものは受け手軸で拾えますし、その逆も成り立ちます。わたしが最初にやったastimezone(JST)という検索は、動詞と受け手を1本に混ぜたものでした。だから他の動詞も、他の受け手も、両方すり抜けたわけです。

分けたあと具体的にどう書くか。grepで拾えない経路をどう探すか。見つかった件数でどう対応を変えるか。ここから先は有料エリアで扱います。

「なぜ」が浅くなるのは、各段に役割がないから

もうひとつ、よくある悩みがあります。「なぜを5回と頼んでも、2〜3回で止まる」というものです。

AIに任せた場合も、自分でやった場合も同じように起きます。原因ははっきりしています。

各段が「同じ抽象度の言い換え」になってしまうからです。

たとえば、こんな掘り下げを見たことはありませんか。

なぜ1: エラーが出た
なぜ2: 処理が失敗したから
なぜ3: 想定外の値が入ったから

これは掘り下げではありません。同じことを3回言い直しているだけです。抽象度が上がっても下がってもいないので、何回繰り返しても根本原因にはたどり着きません。

これを防ぐには、各段にあらかじめ「何を答える段か」という役割を割り当てておく必要があります。Why1は観測事実、Why2は直接原因、Why3はコード上の設計判断。このように、段ごとに答えるべき問いを固定してしまいます。

役割を決めておけば、AIに頼んだときも段の意味が明確になります。言い換えでお茶を濁せなくなるからです。

再発防止策が「ドキュメントに書く」で終わると、必ず戻ってくる

3つめの問題です。再発防止策として「コーディング規約に追記しました」で終わらせるパターン。

わたしのプロジェクトで、再発防止を人間のレビュー任せにしたバグ修正を6件さかのぼって追跡しました。結果は、そのほぼ全件が再発していました。新しく書かれた別の箇所で、同じテーマとして復活していたのです。

人間のレビューに担保を任せると、既存の箇所は直っても、新しく書かれる箇所で同じテーマが復活します。特にAIにコードを書かせている場合は要注意です。AIは前のセッションの反省を覚えていないので、ドキュメントに書いただけのルールはほぼ機能しません。

だから再発防止策は、**lint化（最優先）＞ test化 ＞ docsに書くだけ（最終手段）**という優先順で選びます。既製のlintルールで足りなければ、自分のプロジェクト用のチェックを書くところまで含みます。

そのうえで「docsに倒していいか」を判断するためのゲートを、あらかじめ用意しておく必要があります。

全体像：6ステップ

ここまでの3つの問題に、それぞれ対処を割り当てます。すると、手順はこの6ステップになります。

1. 症状を1行で書く
      ↓
2. Why5で掘る（各段に役割を割り当てる）
      ↓
3. 原因のパターンを「探せる形」に抽象化する
      ↓
4. 横並びチェック（動詞軸 × 受け手軸の2軸で検索）
      ↓
5. 再発防止策を決める（lint化 > test化 > docs）
      ↓
6. コミットに Why5 と横並び結果を記録する

この6ステップを毎回手で回すのは現実的ではありません。だから最後にSKILL.mdとして登録して、自動発動させます。

SKILL.mdというのは、Claude Codeが自分から読み込んでくれる手順書のファイルです。「これに当てはまる依頼だ」と判断したときに発動します。決められたフォルダに置くだけで登録できます。毎回プロンプトに手順を貼る作業が要らなくなります。これがいちばんの利点です。

持ち帰り：浅いなぜなぜ分析の見分け方3つ

ひとつ渡しておきます。手元にあるWhy5が浅いかどうかを、その場で判定するための3つの目印です。

1. 段が進んでも、主語が変わらない。 Why1からWhy5まで、ずっとコードの話で終わっている。掘れているWhy5は、コードから人・プロセスへ主語が移ります。

2. Why5が「不注意」「確認不足」で終わっている。 これは原因ではなく、原因の探索を打ち切る言葉です。ここで止まっていたら、まだ1段も掘れていません。

3. 再発防止策が「気をつける」になっている。 原因が人の意識に置かれている証拠です。機械化できる形になっていません。

3つのうち1つでも当てはまったら、その分析はやり直しです。まずは自分の直近のコミットで試してみてください。わたしは3つとも当てはまるコミットが、ぽろぽろ見つかりました。

SKILL.mdの冒頭だけ、先に見せます

有料エリアの中心は、この6ステップをまるごと自動発動させるSKILL.mdです。

中身が見えないものにお金は出しにくいと思います。冒頭のdescriptionと「完了条件」だけ、実物のまま出しておきます。

---
name: why5-and-horizontal-check
description: バグ修正・技術的負債の対応時に、症状を消すだけで終わらせず、
  Why5で根本原因を掘り下げ、動詞軸と受け手軸の2軸検索で同型箇所を全件洗い出し、
  再発防止策をlint/testまで機械化する。バグ修正・不具合対応・エラー調査・
  技術的負債への対応を頼まれたときに使う。
---

## 完了条件

次のすべてを満たすまで、完了と報告しない。

- Why5（または本質に到達した段数）が記録されている
- 横並びチェックを動詞軸・受け手軸・補助軸で実施し、各軸の検索コマンドと
  件数が記録されている（0件の軸も記載する）
- 再発防止策が決まっている（「修正のみ・再発防止なし」は禁止。
  検出0件の場合と、後述の省略ケースに該当する場合はゼロ確認の記録で足りる）
- Why5と横並び結果を、コミットメッセージ本文の定型ブロックに記録した
- lint / 型チェック / テストをすべて実行し、全グリーンである

抜粋の中に出てくる「補助軸」は、2軸では拾えない書き方を別立てで探すための3本目です。「後述の省略ケース」とあわせて、有料エリアで扱います。

効くのは「完了条件」の書き方です。手順だけ書いたスキルは、AIが途中で切り上げて「対応しました」と言ってきます。**先に「これを満たすまで完了と言うな」を並べておくと、途中で止まりにくくなります。**この考え方だけでも、手元のスキルに移植できます。

この抜粋は全体の1割強で、残りは有料エリアにあります。

ここから先で手に入るもの

・Why5の5段階の型（各段の役割を固定した対応表・実例つき）と、5段で止めるか続けるかの判断基準2つ
・そのまま投げるAIへの差し戻し文（浅い掘り下げを3段目からやり直させる指示。コピペ可）
・2軸のgrepコマンド4本（macOSやripgrepでも動く形／偽の0件を出さないための注意つき）と、grepで拾えない経路3種、検索手段の使い分け表
・3件ルールと件数の数え方、コミット前チェックリスト5項目、docsに倒す前に答える3つの質問
・lintチェッカーの最小雛形（Pythonのastで書いた約65行。CI設定とpre-commit設定つき）と、既存コードが真っ赤になったときの段階導入手順
・コミットメッセージのテンプレート全文と、実運用版SKILL.md全文（約160行）、置き場所
・CLAUDE.mdの書き方・つまずき4件