私のClaude Code活用方法紹介

社外秘X 私のClaude Code活用方法紹介 〜コードレビューについての改善手法〜 KDDIアジャイル開発センター株式会社 溝渕 康行

自己紹介 溝渕 康行 KDDIアジャイル開発センター株式会社 ソフトウェアエンジニア 高知県出身 好きなもの ・日本酒などお酒 ・犬（特にコーギー） 経験 ・Angular+Javaを使った金融商材販売のパッケージ開発 ・RPAによるビジネスプロセスの改善と自動化 ・BtoBのデータ管理サービスと認証機能開発 2025年7月からAIエージェント作成プロジェクトに参加。 KDDI Agile Development Center Corporation 2

社外秘X コードレビュー指示の精度が結果を決める 曖昧な指示では Claude Code の能力を引き出せない — よくある指示を3段階で分析 Lv.1 最もよくない 「このPRをレビューして」 Lv.2 Lv.3 改善の余地あり 「セキュリティとパフォーマンス の問題がないか確認して」 あと一歩 ✅ 「OWASP Top 10 に基づいて severity 付きで報告して」 .claude/agents/ ⚠ 何が足りないか ⚠ 何が足りないか ⚠ 何が足りないか • 観点の指定がない • 観点はあるが判定基準なし • 方法論と出力形式はある • 判定基準がない • 何を HIGH とするか不明 • プロジェクト固有の文脈なし • 出力形式がない • プロジェクト文脈がない • severity 判定基準が曖昧 ▼ ▼ ▼ 何を見ればいいか わからない 何がどの程度 重要か不明 プロジェクト固有の 判断ができない ❌ 結果 ❌ 結果 ❌ 結果 レビューの深さも方向もAI任せ。 表面的な指摘のみ → 重要な問題を見逃す チェックリスト的指摘に終始。 プロジェクト固有のリスクを 見逃す 汎用的レビューは可能だが、 アーキテクチャ固有の問題を 検出できない 構造化されたアプローチ 各エージェントに専門観点 + severity 判定基準を明記 → Lv.2, 3 の「基準なし」を解決 Task tool 並列実行で複数観点を 同時にカバー → Lv.1 の「観点なし」を解決 Skills フロー全体を定義ファイルに 集約・標準化 → 再現性のある高品質レビュー KDDI Agile Development Center Corporation 3

社外秘X 良いプロンプトでも、単一視点では見落としが生まれる セキュリティ観点の優れたプロンプトで実際にレビューした場合を考える ✅ セキュリティ観点の良いプロンプト OWASP Top 10 に基づいてレビュー。 ## 観点 - 認証・認可の実装パターン検証 - 入力バリデーション・サニタイズ - セッション管理・トークン処理 - 機密情報の漏洩リスク ## severity 判定基準 HIGH: 攻撃可能な脆弱性 MEDIUM: 防御層の不足 LOW: ベストプラクティスとの差異 ## 出力: 統一JSON形式 🔍 このプロンプトで検出できること ❌ しかし、他の観点では見落としが発生する レビュー対象のコード例: app/api/users/route.ts → export async function GET(req) { const users = await db.user.findMany(); for (const user of users) { user.orders = await db.order.findMany({ where: { userId: user.id } }); user.profile = await getProfile(user.id); user.logs = await getAuditLogs(user.id); } return Response.json(users); } ⚡ パフォーマンス 🔧 コード品質 🏗 アーキテクチャ N+1 クエリ SRP 違反 + テスト困難 密結合 + ページング未実装 ユーザー数 × 3回の追加クエリが 発生。100ユーザーで 301回の DBアクセス → レスポンス 10倍遅延 1つのハンドラにデータ取得・ 加工・監査ログ取得が混在。 個別テスト不可能、変更時の 影響範囲が不明 全ユーザーを一括返却する設計。 データ増加で破綻。プロファイル 取得が特定実装に密結合 → 切り替え不可 ✓ セッショントークンの有効期限が未設定 ✓ SQLインジェクション可能な動的クエリ ✓ CSRF トークン検証の欠如 ✓ APIキーのハードコード 👍 セキュリティ観点では十分に良いレビュー HIGH（ホットパス上） ← セキュリティレビューでは検出されない MEDIUM ← セキュリティレビューでは検出されない HIGH（スケール不可） ← セキュリティレビューでは検出されない 💡 1つの視点が完璧でも、カバーできない領域がある → 複数の専門家による多角的レビューが必要 KDDI Agile Development Center Corporation 4

社外秘X 単一AIでのコードレビュー、その限界 AIで単一・複数の視点でレビューしようとするとどんな不便がある？ ⚠ ⏱ ⇄ 見逃しリスク 時間のボトルネック False Negative Sequential Bottleneck 深度と広さのトレードオ フ セキュリティに集中すると パフォーマンス問題を見逃す 複数の観点を順番に確認 品質→セキュリティ→性能→設計 … 品質に集中すると 設計上の欠陥を見逃す レビュー時間が肥大化 広く見る → 各観点が浅くなる 深く見る → 範囲が狭くなる 限られた時間内では 両立は不可能 コンテキストの影響で見逃し発生 → 本番障害のリスク増大 Breadth vs Depth → フィードバックの遅延 → 常にどこかが手薄 これらの課題を解決するには？ → 多角的な「専門家チーム」によるレビューへ KDDI Agile Development Center Corporation 5

並列実行による多角的な「専門家チーム」によるレビューで解決 社外秘X 複数の専門分野に特化したエージェントで、並列的にレビューすることで、短い時間で死角のないコードレビューを実現 システム アーキテクト リファクタリング 専門家 ⚡ パフォーマンス エンジニア ✓ 品質 エンジニア Source Code 汎用 セキュリティ エンジニア KDDI Agile Development Center Corporation 6

社外秘X 並行レビューで品質・速度・コストの同時最適化 並列で多角的に評価をすることで、深い網羅性と実行時間の短縮を実現したフィードバックが得られる Coverage Cost Speed 品質 (Quality) 順次実行 (Sequential) PRに対して並列レビュー 4つ順次にやると時間がかかる セキュリティ (Security) 設計 (Design) 100% 並列実行 (Parallel) 25% 75% 70~80% 1度でレビュー完了 （追加コスト不要） 20~30% AIからの指摘に対して や、AIの観点不足へ の深掘り 時間短縮 パフォーマンス (Performance) 並列で行えば25%の時間で出来る 追加の情報や観点 → サブエージェン トでさらに深掘りレビュー 多角的な視点でのカバー 75% 時間短縮 一部の指摘に対して絞ることで トークンコスト削減 KDDI Agile Development Center Corporation 7

社外秘X 複数エージェントによるレビューの実行手段 Step 1 .claude/agents/*.md 各エージェントの専門性を定義 → Step 2: subagent_type で Agent を呼び出す ⚡ 複数を1メッセージで → 並列実行 → Step 3 .claude/skills/*.md Task tool 呼び出しをここに書く ユーザーは「多角的にレビューして」といった指示を Claude Codeにすることで、専門 性を持った各エージェントによるレビューの並列実行を行うことができるようになる。 KDDI Agile Development Center Corporation 8

社外秘X Step 1: エージェント定義を用意する プロジェクトルートの .claude/agents/ に、専門エージェントごとの .md ファイルを新規作成する 配置場所（プロジェクトルートからのパス） 各 .md ファイルの構造 ① フロントマター（YAML）— ツール権限 my-project/ エージェントが使用できるツールを制限・許可する ├── src/ --allowed_tools: [Read, Grep, Glob, Bash] --- ├── package.json ├── CLAUDE.md └── .claude/ ├── settings.json ├── agents/ ← ここに作成 ② 本文（Markdown）— 行動指針と専門知識 エージェントの専門性・観点・出力フォーマットを自由記述 │ ├── security-engineer.md │ ├── quality-engineer.md │ ├── performance-engineer.md - OWASP Top 10 に基づく脆弱性チェック │ └── system-architect.md - 認証・認可の実装パターン検証 └── skills/ 💡 既存ファイルの修正ではなく、.md ファイルを新規作成する ファイル名 = Task tool の subagent_type 名と対応 # セキュリティエンジニア ## レビュー観点 ## 出力: 統一JSON形式 作成するエージェント定義と担当観点 security-engineer.md → セキュリティ quality-engineer.md → コード品質・テスト performance-engineer.md → パフォーマンス system-architect.md → アーキテクチャ・仕様整合 KDDI Agile Development Center Corporation 9

社外秘X Step 2: Task tool で並列にレビューを実行できる Step1のsub agentを用意した段階で、各エージェントの呼び出しや、１メッセージで の並列起動が可能。 Task tool の動作イメージ Task セキュリティ 結果を統合 ↓ 最終レポートを出力 security-engineer リーダー Task パフォーマンス performance-engineer ⚡ 1メッセージで4つを並列起動 Task 品質 quality-engineer Task アーキテクチャ system-architect 📌 準備不要 Task tool は Claude Code の組み込み機能。 インストールや設定ファイルの作成は不要。 📝 記述場所 = Skill ファイル Step 3 の .claude/skills/*.md を用意して呼び出すようにする。 KDDI Agile Development Center Corporation 🔗 subagent_type = Agent ファイル名 Step 1 の .claude/agents/security-engineer.md → subagent_type: "security-engineer" 10

社外秘X Step 3: Skills で自然言語からレビューを起動 「多角的にレビューして」の一言で、専門家チーム全体が動き出す仕組み Skill 定義ファイルの内容例 自然言語で起動する流れ 💬 ユーザー入力 .claude/skills/multi-perspective-review.md 「このPRを多角的にレビューして」 ▼ --name: multi-review description: "PRを多角的にレビュー" Claude Code が description をもとに Skill を自動マッチング --- ▼ # 多角的コードレビュー ## Phase 0: 準備 1. git diff main...HEAD で差分取得 2. CLAUDE.md からアーキテクチャを把握 Skill 定義のボディがプロンプトとして展開 ## Phase 1: 並列レビュー（4つのTask subagent） - quality-engineer: コード品質・SOLID・テスト - security-engineer: セキュリティ・認証・OWASP - performance-engineer: 複雑度・キャッシュ - system-architect: アーキテクチャ・仕様ギャップ 出力: 統一JSON形式（severity, file, suggestion... ） ▼ Phase 0 準備 → Phase 1 並列レビュー Phase 2 → 条件付き深掘り → Phase 3 統合レポート ## Phase 2: 深掘り（条件付き） - HIGH severity → root-cause-analystで根本原因分析 - リファクタリング推奨 → refactoring-expert ## Phase 3: 統合レポート 重複排除・矛盾解決・最終レポート出力 💡 Skills のメリット • description で自然言語マッチング（コマンド不要） • ボディ全体がプロンプトとして展開される • Phase 0〜3 の全フローを1ファイルに集約 • チームの誰でも同じ品質のレビューを実行可能 KDDI Agile Development Center Corporation 11

社外秘X Agent Team とは 複数のエージェントが「チーム」として協調動作する Claude Code の機能 これまで（Task tool 単体） Agent Team（チーム型協調） Team: "code-review" リーダー → → → Agent B → Agent C ⇄ Agent A ⇄ Agent B ⇄ Agent C 👑 リーダー → レポート Agent A レポート ⇅ メンバー同士も 通信可能 チームとして継続稼働・相互通信・動的タスク管理 各エージェントは独立実行・通信不可 結果を返したら終了（Fire-and-forget） 📋 共有タスクリスト — 全メンバーがタスクを参照・更新・追加 Agent Team の構成要素 TeamCreate Task + team_name SendMessage TaskCreate / Update チームを作成する メンバーを起動する メッセージを送る タスクを管理する チーム名を指定して作成。 共有タスクリストが自動生成される。 team_name を指定してメンバーを チームに参加させる。 DM・ブロードキャスト・ シャットダウン要求が可能。 共有タスクリストにタスクを 追加・完了・割り当て。 TeamCreate( team_name="code-review" ) Task( team_name="code-review", name="sec-reviewer", subagent_type="security-engineer" ) SendMessage( type="message", recipient="sec-reviewer", content="HIGH の詳細を確認して" ) TaskCreate( subject="セキュリティレビュー", description="OWASP 観点で..." ) KDDI Agile Development Center Corporation 12

社外秘X Task tool 単体 vs Agent Team 用途に応じて最適なオーケストレーション方式を選択する 比較観点 Task tool 単体（現在の構成） Agent Team Fire-and-forget 各サブエージェントが独立して実行・結果返却 チーム型協調 メンバーが継続的に動作し、相互通信可能 不可 — 各自が独立して判断 SendMessage で双方向通信 例: 指摘の相互検証が可能 タスク管理 プロンプトで一括指示 完了判定はリーダーが一括で行う 共有タスクリストで動的管理 タスク追加・完了を逐次追跡 深掘り リーダーが結果確認後 再度 Task tool を呼ぶ（2段階） メンバー自身がフォローアップ タスクを動的に追加できる コスト（トークン消費） 低い — 通信オーバーヘッドなし 高い — チーム管理 + メッセージ 交換分のトークンが追加で必要 セットアップの複雑さ シンプル Skill 定義にプロンプトを書くだけ やや複雑 TeamCreate / SendMessage / TeamDelete の管理が必要 実行モデル エージェント間通信 ✅ Task tool 単体が向くケース ✅ Agent Team が向くケース • 各エージェントが独立して判断できるレビュー • コストを抑えたい日常の PR レビュー • シンプルに導入・運用したい場合 • エージェント間で指摘の相互検証が必要なレビュー • 大規模 PR で動的なフォローアップが頻繁に発生 • セキュリティ×パフォーマンスなど観点をまたぐ分析 KDDI Agile Development Center Corporation 13

社外秘X Agent Team で再現する場合 TeamCreate + SendMessage によるチーム型オーケストレーション Step 1: 同じ Step 2: チーム作成 + メンバー起動 .claude/agents/ に エージェント定義を作成 Step 3: Skills でラップ TeamCreate でチームを作成 Task + team_name でメンバー参加 → 変更なし — カスタムエージェント 定義は共通で使える → 共有タスクリスト + エージェント 間通信（SendMessage）が使える Skill 定義の中身が TeamCreate ベースに変わる ユーザーから見た起動方法は同じ （自然言語で起動可能） Agent Team の実行フロー ① TeamCreate チーム + 共有タスクリスト を作成 ② Task(team_name=...) でメンバー起動 → sec per f qua l arc h → ③ 協調動作 共有タスクリストで進捗管理 SendMessage で相互に情報共有 → ④ 統合 + TeamDelete リーダーが結果統合 チームをクリーンアップ Agent Team ならではの機能 💬 エージェント間通信 📋 共有タスクリスト 🔄 動的なフォローアップ 👤 チームリーダーの統制 SendMessage で相互に情報共有が可能。 例: security の指摘を performance が検証 TaskCreate / TaskUpdate でタスクを動的に 追加・完了管理。Phase 2 も動的に発行 HIGH 発見時にリーダーが追加タスクを作成し 別メンバーに割り当てる、といった柔軟な運用 リーダーが全体を見てメンバーに指示を送信。 状況に応じた判断・調整が可能 KDDI Agile Development Center Corporation 14

社外秘X Skills 定義はどう変わるか Skill ファイルの中身が Task tool 単体から TeamCreate ベースに変化する Task tool 版（現在の構成） Agent Team 版 .claude/skills/multi-perspective-review.md .claude/skills/multi-perspective-review.md --description: "PRを多角的にレビュー" --- --description: "PRを多角的にレビュー" --- ## Phase 0: 準備 1. git diff で差分取得 2. CLAUDE.md を把握 ## Phase 0: 準備 1. git diff で差分取得 2. CLAUDE.md を把握 ## Phase 1: 並列レビュー 以下を Task tool で **同時に** 起動: - subagent: security-engineer - subagent: performance-engineer - subagent: quality-engineer - subagent: system-architect ## Phase 1: チーム作成 + メンバー起動 1. TeamCreate("code-review")でチーム作成 2. 以下を Task(team_name=...) で起動: - name="sec", type=security-engineer - name="perf", type=performance-engineer - name="qual", type=quality-engineer - name="arch", type=system-architect - name="integrator", type=report-integrator 3. TaskCreate で各レビュータスクを登録 → ## Phase 2: 深掘り（条件付き） HIGH → 再度 Task tool で深掘り ## Phase 3: 統合レポート 全結果を統合・重複排除・レポート出力 ## Phase 2: 協調レビュー + 深掘り - メンバーがタスクリストから取得・実行 - HIGH発見 → SendMessage でリーダーに報告 → リーダーが TaskCreate で深掘り追加 ※サブエージェントで複数の指摘がある場 合など、Serverityを定義しており、HIGHの 場合は再度深掘りレビューさせている。 ## Phase 3: 統合 + クリーンアップ 1. integrator が全結果を統合・レポート出力 2. shutdown_request でメンバー終了 3. TeamDelete でクリーンアップ 📁 ファイルは同じ 🔄 Phase 1 が変化 💬 Phase 2 が動的に 👤 Phase 3 に統合役 .claude/skills/ の同じ Skill ファイルを編集する Task tool 単発 → TeamCreate + team_name 起動 リーダー再呼び出し → SendMessage + TaskCreate で協調 リーダー直接統合 → report-integrator に委任も可能 KDDI Agile Development Center Corporation 15

Be a Change Leader. アジャイルに力を与え 共に成長し続ける社会を創る

社外秘X 偽陰性（見逃し）を最小化する堅牢なレビュー基盤 The Core Value (Reliability) The Mechanism (Standardization) False Negative（見逃し）防止 ✓ 標準化された出力 (Standardized JSON) ● 本番障害につながる重大なバグを最優先で検出 {} ● 人間の専門家チームと同等の多角的な視点 ☑ Multi-perspective（多角的視点） ● 全エージェントが統一フォーマットで出力 ● 解析や自動化ワークフローへの統合が容易 ☑ High Speed（高速並列処理） KDDI Agile Development Center Corporation ☑ Low Noise（ノイズ低減） 17