Claude Codeでデバッグするなら「ベテランの感覚」をCLAUDE.mdとSkillsに埋め込め

Posted at 2026-03-22

はじめに

Claude Codeはコード生成だけでなく、不具合調査やデバッグ支援でもかなり使えるようになってきました。

ただ、実際に使ってみるとこんなことが起きがちです。

それっぽい一般論しか返ってこない
原因を決め打ちして外す
ログや現象より、コードの見た目だけで判断する
実務で本当に危ない観点を見てくれない

この原因はシンプルで、Claude Codeに 「ベテランエンジニアの見方」が渡っていない からです。

現場のベテランは、コードを見た瞬間にこう感じます。

これ、今は動いても後で壊れそう
このIF、例外系で事故りそう
この実装、性能劣化の匂いがする
この修正、別画面に副作用が出そう

こうした"感覚"は、ただの勘ではありません。過去の障害、失敗、設計崩れのパターンが圧縮された知識です。

この記事では、Claude Codeの CLAUDE.md と Skills を使って、このベテランの感覚を 毎回プロンプトに書かなくても自動で適用される仕組み にする方法をまとめます。

なぜ「毎回プロンプトに書く」のは間違いなのか

ChatGPTやブラウザ版Claudeでは、デバッグのたびに長いプロンプトを貼り付ける必要がありました。

あなたは保守経験が長いベテランエンジニアです。
以下の不具合を調査してください...
この案件でよくある障害パターンは...

これには3つの問題があります。

毎回書くのが面倒 — 同じ前提情報を何十回も貼ることになる
チームで共有できない — 自分のプロンプトが属人化する
Claude Codeの強みを活かせていない — Claude Codeはファイルを直接読み、テストを実行し、ログを確認できるのに、テキストを貼るだけでは勿体ない

Claude Codeには、この問題を解決する仕組みがあります。

仕組み	役割	読み込みタイミング
`CLAUDE.md`	プロジェクト固有のルール・前提情報	毎セッション自動
`.claude/skills/`	再利用可能なワークフロー	必要時にオンデマンド
`.claude/rules/`	パス単位のルール	対象ファイル操作時
Auto Memory	Claudeが自分で学んだメモ	毎セッション自動

つまり、ベテランの感覚は一度ファイルに書けば、以後ずっと効く のです。

AIに渡すべき「ベテランの感覚」とは何か

ベテランの違和感は、次の形に分解できます。

項目	内容
違和感	何が気になったか
兆候	どこを見てそう感じたか
リスク	何が起きそうか
確認方法	何を確認すればよいか

たとえばこんな感じです。

例1: 性能劣化の匂い

違和感: 一覧で重くなりそう
兆候: ループ内でDBアクセスしている
リスク: 件数増加時にレスポンス悪化
確認方法: SQL発行回数、N+1、検索件数増加時の応答時間を確認

例2: 二重実行の匂い

違和感: 再送時に事故りそう
兆候: タイムアウト時の仕様が曖昧、冪等性キーなし
リスク: 二重登録、状態不整合
確認方法: 再送条件、送信済み判定、ロールバック境界を確認

例3: 設計崩れの匂い

違和感: 後で保守がつらくなりそう
兆候: Controllerに業務ロジック集中、Serviceが肥大化
リスク: 修正時の副作用増加、テスト困難
確認方法: 責務分離、依存方向、単体テスト容易性を確認

これを CLAUDE.md に書くか、Skills に入れるか で、活用の仕方が変わります。

Step 1: CLAUDE.md にプロジェクトの「地雷」を埋め込む

プロジェクトルートの CLAUDE.md には、毎回のセッションで必ず意識してほしい前提情報 を書きます。

書くべき内容

# プロジェクト概要

受注管理システム。Spring Boot 3 + PostgreSQL + Vue 3 + TypeScript。
Controllerは入力と返却のみ、Serviceで業務ロジック、RepositoryでDBアクセス。

# この案件でよくある障害パターン

以下は過去に実際に発生した障害です。コードレビューやデバッグ時に必ず確認してください。

1. ループ内DBアクセスによるN+1性能劣化
2. @Transactional境界不備によるDB不整合
3. 外部IFタイムアウト時の二重実行（冪等性キーなし）
4. 権限判定漏れ（管理者以外がアクセスできてしまう）
5. NULL考慮漏れ（Optional未使用、?.なしアクセス）
6. 画面表示とDB状態の不一致（キャッシュ残り、非同期ずれ）

# この案件特有の地雷

- 受注ステータス更新は必ず排他ロック（SELECT FOR UPDATE）を取ること
- 外部API連携は30秒タイムアウト。リトライ時に二重送信しない設計が必須
- バッチ処理とオンライン処理が同一テーブルを更新するため、デッドロック注意
- Vue側のPiniaストアはページ遷移時にリセットされない。古い状態が残る

# デバッグ時の姿勢

- 推測と事実を明確に分けること
- いきなり断定せず、複数の原因候補を比較すること
- コードの見た目より、ログの時系列を重視すること
- 最小修正と根本対策を分けて提示すること

CLAUDE.md のコツ

200行以内に収める — 公式ドキュメントによれば、200行以下で92%以上のルール適用率。400行を超えると71%まで低下する
具体的に書く — 「きれいなコードを書いて」ではなく「@Transactionalの境界を確認して」
過去の実事故を書く — 一般論より「この案件で実際に起きたこと」が最も効く
/init で雛形を生成できる — claude を起動して /init を実行すると、コードベースを分析してCLAUDE.mdの雛形を自動生成してくれる

Step 2: デバッグ用Skillを作る

Skills は /skill名 で呼び出せる再利用可能なワークフローです。デバッグのように「特定の場面で使いたいが、毎回は不要」な手順はSkillが最適です。

汎用デバッグSkill

.claude/skills/debug/SKILL.md

---
name: debug
description: >
  不具合調査・デバッグ用。バグ報告、エラー調査、原因分析、修正案の作成時に使用。
  「バグ」「不具合」「エラー」「原因調査」「デバッグ」といったキーワードで自動発動。
---

# デバッグワークフロー

あなたはこのシステムの保守経験が長いベテランエンジニア兼デバッグ担当です。
単なる一般論ではなく、現象・ログ・コード・過去の失敗パターンから原因を絞り込んでください。

## 調査の原則

- 推測と事実を明確に分けること
- いきなり断定せず、複数の原因候補を比較すること
- 「なぜそう考えたか」を兆候ベースで説明すること
- 修正案は「最小修正」と「根本対策」を分けること
- 不明点があっても止まらず、現時点で最も妥当な仮説を提示すること
- ベテランの感覚的な違和感も、必ず言語化して説明すること
- コードの見た目よりも、ログの時系列、リクエストの流れ、DB更新順を重視すること

## 重点確認観点

- 例外処理（握りつぶしていないか）
- トランザクション境界（@Transactionalの範囲は適切か）
- 非同期処理・タイムアウト
- 排他制御（楽観/悲観ロック）
- 二重送信・二重更新
- 権限チェック漏れ
- NULL / Optional / 未設定値
- N+1問題
- キャッシュの整合性
- 画面→API→DBのデータ不整合
- 直近修正の副作用

## 調査手順

1. まず関連するログファイルを読む（`@logs/` や `docker logs` など）
2. エラーのスタックトレースから発生箇所を特定する
3. 関連するコードを実際に読む（推測で語らない）
4. 必要に応じてテストを実行して再現を確認する
5. git logで直近の変更を確認する

## 出力形式

以下の順番で回答してください。

### 1. 現象の整理
現象を1〜3文で要約

### 2. 事実と推測の切り分け
- 事実:
- 推測:
- まだ足りない情報:

### 3. 違和感・兆候
- ベテラン視点で気になる点
- ログ/コード/挙動のどこが兆候か

### 4. 原因候補の優先順位
- 第1候補: 根拠、一致する兆候、確認方法
- 第2候補: 根拠、一致する兆候、確認方法
- 第3候補: 根拠、一致する兆候、確認方法

### 5. 最有力原因
現時点で最も可能性が高い原因と、なぜ他候補より有力か

### 6. 修正案
- 最小修正案
- 根本対策
- 修正時の注意点

### 7. 追加で確認すべきこと
- 追加ログ / データ確認 / 再現条件 / コード確認箇所

### 8. 回帰リスク
- 修正で壊れそうな箇所
- 横展開で確認すべき箇所

### 9. テスト観点
- 正常系 / 異常系 / 境界値 / 再発防止テスト

### 10. 結論
今すぐやるべき調査・修正を3つに絞って提示

使い方

Claude Codeのセッションで以下のように使います。

> /debug 受注一覧画面で、ステータスが「出荷済み」の注文が「処理中」と表示される。昨日のリリース以降に発生。

Skillの description にキーワードを書いておけば、/debug と明示しなくても「このバグの原因を調べて」と言うだけで自動発動します。

Step 3: スタック特化のSkillも作る

汎用のデバッグSkillに加えて、バックエンドとフロントエンドで特化Skillを作ると精度が上がります。

Spring Boot特化デバッグSkill

.claude/skills/debug-backend/SKILL.md

---
name: debug-backend
description: >
  Spring Boot / バックエンドの不具合調査用。API、Service、Repository、
  トランザクション、SQL、外部IF連携のデバッグ時に使用。
---

# Spring Bootバックエンド デバッグ

あなたはSpring Boot保守経験が長いベテランエンジニアです。

## 重点確認ポイント

- Controllerに業務ロジックが混入していないか
- @Transactionalの境界が適切か（readOnly、propagation）
- Repository/Mapperの呼び出し回数が異常でないか（N+1）
- MyBatis/JPAのSQL発行が想定通りか
- 例外が握りつぶされていないか（catch内でログだけ出して続行など）
- 非同期処理（@Async）やタイムアウトの影響がないか
- 外部IF失敗時にDBとの整合性が崩れていないか
- NULL/Optional/未設定値の扱いに漏れがないか
- 権限・業務条件分岐が抜けていないか
- 直近修正（git log --oneline -10）の副作用がないか

## 調査手順

1. `grep -r "ERROR\|WARN\|Exception" logs/` でログを確認
2. 関連するController → Service → Repository の呼び出しチェーンを追う
3. SQLログを確認（spring.jpa.show-sql や MyBatisログ）
4. テストを実行して再現確認
5. `git log --oneline -10` で直近変更を確認

## 出力形式

1. 現象整理
2. 最有力原因候補3つ（根拠付き）
3. 確認すべきコード箇所
4. 確認すべきログ
5. 最小修正案
6. 根本対策
7. 回帰テスト観点

Vue 3 フロント特化デバッグSkill

.claude/skills/debug-frontend/SKILL.md

---
name: debug-frontend
description: >
  Vue 3 / TypeScriptフロントエンドの不具合調査用。
  表示崩れ、状態管理、API連携、入力値反映の問題に使用。
---

# Vue 3 フロントエンド デバッグ

あなたはVue 3 / TypeScriptフロントエンドのデバッグ経験が長いベテランエンジニアです。

## 重点確認ポイント

- reactive / ref / computed の使い方不備
- watchの条件漏れ、無限反応、反映漏れ
- props / emits の受け渡し不整合
- APIレスポンスの反映漏れ（awaitなし、エラーハンドリングなし）
- v-modelやフォーム初期化不備
- 非同期タイミングずれ（nextTick漏れ）
- 条件付き描画（v-if / v-show）による表示崩れ
- 権限や表示条件の分岐漏れ
- Piniaストアのキャッシュ残り・画面遷移時の状態リセット漏れ
- 直近修正の副作用

## 調査手順

1. ブラウザのコンソールエラーを確認
2. Vue DevToolsでコンポーネントのstate/propsを確認
3. Network タブでAPIリクエスト/レスポンスを確認
4. 関連するコンポーネント → composable → store → API呼び出しを追う
5. `git log --oneline -10 -- src/` で直近のフロント変更を確認

## 出力形式

1. 現象整理
2. 疑わしい状態管理ポイント
3. 原因候補の優先順位（根拠付き）
4. 確認すべきコンポーネント/ストア/API
5. 最小修正案
6. 根本対策
7. 再発防止の確認観点

Step 4: `.claude/rules/` でパス単位のルールも活用する

特定のディレクトリに対して自動適用したいルールは .claude/rules/ に置きます。

例: API層のルール

.claude/rules/api-rules.md

---
globs: src/main/java/**/controller/**
---

# Controller層のルール

- Controllerには業務ロジックを書かないこと（Serviceに委譲）
- 入力バリデーションは@Validatedで行うこと
- 例外はControllerAdviceで統一ハンドリングすること
- レスポンスのHTTPステータスコードを適切に返すこと

例: フロント層のルール

.claude/rules/frontend-rules.md

---
globs: src/frontend/**/*.vue, src/frontend/**/*.ts
---

# フロントエンド層のルール

- APIコールは必ずtry-catchでラップし、エラー時はユーザーに通知すること
- Piniaストアの状態はページ遷移時にリセットが必要か確認すること
- v-modelのバインド先がreactive/refであることを確認すること

これにより、対象ファイルを触るときだけ自動でルールが注入されます。

実際の使い方

基本的な流れ

# 1. Claude Codeを起動（CLAUDE.mdが自動で読み込まれる）
claude

# 2. バグを伝える（Skillが自動 or 手動で発動）
> /debug 受注一覧のステータス表示がおかしい。昨日のリリース以降。

# 3. Claude Codeが自動でやること:
#    - 関連コードを読む
#    - git logで直近変更を確認する
#    - ログファイルを確認する
#    - テストを実行する
#    - CLAUDE.mdの「よくある障害パターン」と照合する
#    - Skillの出力形式に従って回答する

精度を上げる追加プロンプト

Skillや CLAUDE.md だけでは足りない場合、セッション中にこう伝えると効きます。

表面的な説明ではなく、「この不具合は過去にどんな事故パターンと似ているか」
「どの兆候が危険信号か」まで踏み込んでください。
原因を1つに決め打ちせず、必ず複数仮説を比較してください。

気に入った指示は # プレフィックスで CLAUDE.md に永続化できます。

> # デバッグ時は原因を1つに決め打ちせず必ず複数仮説を比較すること

Claude Codeデバッグで大事なのは「Skill」より「材料」

Skillも大事ですが、それ以上に効くのは入力情報です。Claude Codeの強みは、ファイルを直接読める こと。プロンプトにログを貼り付けるのではなく、こう伝えましょう。

> /debug ステータス表示がおかしい。ログは logs/app.log の直近100行を見て。
  関連コードは src/main/java/com/example/order/ 以下。
  直近のgit logも確認して。

Claude Codeは自分でファイルを読み、grepし、テストを実行できます。材料を「貼る」のではなく「場所を教える」 のがClaude Code流です。

特に以下の情報を伝えると精度が大きく変わります。

期待結果と実結果
再現条件と発生頻度
直近変更（git log --oneline -10 の結果）
ログファイルの場所
関連コードのパス
この案件で多い事故パターン（CLAUDE.mdに書いてあればOK）

たとえば、次の一文は CLAUDE.md に書いておくとかなり強いです。

この案件では、正常系しか見ずに異常系を見落とす事故が多い。
デバッグ時は異常系・例外系・再送・二重実行を優先して確認すること。

ファイル構成まとめ

your-project/
├── CLAUDE.md                          # プロジェクト固有の前提・地雷情報（毎回自動読込）
└── .claude/
    ├── skills/
    │   ├── debug/
    │   │   └── SKILL.md               # 汎用デバッグSkill（/debug で呼出）
    │   ├── debug-backend/
    │   │   └── SKILL.md               # Spring Boot特化（/debug-backend で呼出）
    │   └── debug-frontend/
    │       └── SKILL.md               # Vue 3特化（/debug-frontend で呼出）
    └── rules/
        ├── api-rules.md               # Controller層の自動適用ルール
        └── frontend-rules.md          # フロント層の自動適用ルール

グローバルに使いたいSkill（全プロジェクト共通）は ~/.claude/skills/ に置きます。

ChatGPT / ブラウザ版Claude との使い分け

観点	ChatGPT / ブラウザ版Claude	Claude Code
前提情報の渡し方	毎回プロンプトに貼る	CLAUDE.mdに一度書けばOK
デバッグ手順	プロンプトで指示	Skillに定義して `/debug` で呼出
ログの確認	テキストを貼り付け	ファイルパスを伝えれば自動で読む
コードの確認	関連コードを貼り付け	パスを伝えれば自動で読む
テスト実行	不可	`./gradlew test` 等を実行可能
git履歴確認	不可	`git log` `git diff` を実行可能
チーム共有	各自がプロンプト管理	CLAUDE.md / Skillsをgitで共有

ChatGPTやブラウザ版Claudeで毎回貼っていたあのプロンプト、そのままSkillにしてしまえばいいのです。

使ってみて感じたこと

Claude Codeでデバッグをさせるとき、よくある失敗は次の2つです。

1. 症状しか渡していない

「エラーが出ました。原因は？」だと、どうしても一般論になります。ログのパス、関連コードのパス、再現手順を伝えましょう。

2. Claude Codeを万能なベテランだと思っている

Claude Codeは知識量は多いですが、あなたの現場の痛みを経験していません。だからこそ、CLAUDE.mdに過去障害や地雷情報を書いてあげる必要があります。

逆に言うと、そこをちゃんと渡せばClaude Codeはかなり強いです。

ファイルを自分で読んで関連コードを特定
git logから直近変更を洗い出し
テストを実行して再現確認
観点の洗い出しと仮説の比較
修正案のたたき台と回帰テスト観点の整理

おわりに

Claude Codeは、放っておくと一般論で話しがちです。でも、CLAUDE.mdにベテランの違和感・過去の失敗・現場固有の地雷を書き、Skillsにデバッグ手順を定義すると、一気に実務寄りになります。

ポイントはシンプルです。

CLAUDE.md にプロジェクトの前提・地雷・過去の事故パターンを書く（毎回自動で読まれる）
Skills にデバッグワークフローを定義する（/debug で呼び出せる）
Rules にパス単位の注意点を書く（対象ファイル操作時に自動適用）
材料はパスで伝える — ログもコードも貼らず、場所を教える

つまり、Claude Codeでデバッグを任せるコツは、

「不具合を調べさせる」のではなく、「ベテランの見方をファイルに書いて、それで調べさせる」 ことです。

毎回プロンプトを書く時代は終わりました。一度書いて、gitで共有して、チーム全員のデバッグ精度を上げましょう。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up