Claude Code Skills: 自分専用の AI ワークフローを作る · 第 5 回 / 全 6 回

レッスン5: ケーススタディ: コードレビュー用スキルを作る

学習目標:

複数ステップのワークフローをどう構成するかを学ぶ

チェックリストパターンがどう適用されるかを理解する

サポートファイルを使いこなせるようになる

実運用に耐える複雑なスキルを1つ作り上げる

前提: << レッスン4 | 次: レッスン6 >>

コードレビューがケーススタディに向いている理由

コードレビューは、構造化されたワークフローの教科書的な例です。¹

手順が決まっている: 規約をチェックし、問題を探し、修正を提案する
基準が測定できる: どのチェック項目も、通るか通らないかのどちらかになる
絶え間なく繰り返す: どの PR にも必要になる
スキルに向いている: チームのレビュー基準をスキルに書き込めば、どのレビューも同じ水準を保てる

このケーススタディで示すのは、次のことです。

複雑なワークフローを明確な手順に分解する方法
チェックリストを軸に指示を構成する方法
複数の出力次元を一度に扱う方法

ステップ1: レビューのスコープを決める

何かを書き始める前に、このスキルが何のチェックを担うのかを決めます。

今回のコードレビュースキルは、次の3つの次元をカバーします。

規約: 命名、フォーマット、コメント
潜在的な問題: エラーハンドリング、エッジケース、セキュリティリスク
保守性: コードの重複、関数の長さ、ロジックの複雑さ

あえてチェックしないこと:

ビジネスロジックが実際に正しいかどうか（これには要件そのものの知識が必要）
アルゴリズムの効率（これには性能テストが必要）
UI/UXデザイン（コードレビューのスコープ外）

ステップ2: ディレクトリ構造を作る

今回は、レビュールールを整理するためにサポートファイルを使います。²

BASH

mkdir -p ~/.claude/skills/code-review
mkdir -p ~/.claude/skills/code-review/checklists

touch ~/.claude/skills/code-review/SKILL.md
touch ~/.claude/skills/code-review/checklists/naming.md
touch ~/.claude/skills/code-review/checklists/error-handling.md

ファイルを分ける理由:

SKILL.md は短く保ち、コアなフローだけを置く
詳細なチェックルールは別ファイルに置き、必要に応じて読み込む²
チームはメインファイルに触れずに、各チェックリストを独立して保守できる

ステップ3: メインの SKILL.md を書く

MARKDOWN

---
name: code-review
description: コード変更を命名規約、エラーハンドリング、潜在的なバグ、保守性の観点でレビューする。PR レビューや一般的なコード品質チェックに使う
---

# コードレビューアシスタント

チームの規約と確立されたプラクティスに照らして、コード変更を体系的にレビューする。

## 入力フォーマット

次のいずれの形式も受け付ける。

- Git diff の出力
- 完全なソースファイル
- コードの断片（関数やクラス）
- PR のリンク（まずツールで PR の内容を読むこと）

## レビューの流れ

次の順序でレビューを進める。

### 1. 規約チェック

`checklists/naming.md` を参照し、各項目を順に確認する。

- **変数名**: 意味が明確で、チームの規約（camelCase、snake_case など）と一貫している
- **関数名**: 動詞で始まり、意図がはっきり伝わる
- **クラス名**: 名詞で、単一責任の原則に沿っている
- **定数名**: すべて大文字、アンダースコア区切り

**基準:** どの名前も、コードに不慣れな人にその用途が伝わること

### 2. エラーハンドリングチェック

`checklists/error-handling.md` を参照し、次を確認する。

- **例外の捕捉**: try/catch があり、適切な例外の型を捕捉しているか
- **エラーの戻り値**: 関数がエラーを正しく処理し、伝播させているか
- **エッジケース**: 空の入力、null、undefined、空配列が扱われているか
- **リソースの後始末**: ファイル、コネクション、ロックが適切に解放されているか

**基準:** 失敗しうるものにはエラーハンドリングが必要

### 3. 潜在的な問題チェック

- **null/undefined へのアクセス**: 存在しないプロパティやメソッドに到達しうるか
- **型安全性**: 暗黙の型変換のリスクはないか
- **並行性**: 競合状態やデッドロックのリスクはないか
- **セキュリティホール**: SQL インジェクション、XSS、CSRF、秘密情報の漏洩

**基準:** 実行時エラーやセキュリティリスクを生みうるコードは指摘する

### 4. 保守性チェック

- **関数の長さ**: 50 行を超えるものは分割を提案する
- **重複**: 3 回以上現れるロジックは抽出を提案する
- **ネストの深さ**: 3 段階を超えたらリファクタリングを提案する
- **コメントの質**: 複雑なロジックが説明されているか

**基準:** 別の開発者がこのコードを楽に読んで変更できること

## 出力フォーマット

レビュー結果は次の構成で報告する。

### ✅ 合格
- [チェック項目] - 基準を満たしている

### ⚠️ 要検討
- **場所**: `file:line`
- **問題**: 具体的に何が間違っているか
- **影響**: これが何につながりうるか
- **提案**: どう改善するか

### 🔴 要修正
- **場所**: `file:line`
- **問題**: 具体的に何が間違っているか
- **リスク**: なぜこのままリリースできないか
- **提案**: 具体的な修正方法

### 📊 総合評価
- コード品質: 良好 / 許容範囲 / 要改善
- 主な問題: [最も重要な2〜3件]
- 推奨する優先度: [まず何を直すか]

## 注記

- **文脈の不足**: 断片が不完全な場合は、周辺のコードがもっと必要かもしれないと伝える
- **フレームワーク特有の慣用表現**: 問題に見えても、フレームワーク特有のパターンのことがある — 「要確認」とマークする
- **テストコード**: テストでは適宜、基準を緩める（たとえば関数の長さ）
- **何も見つからなかった場合**: すべてのチェックを通過したら「✅ レビュー合格、明らかな問題は見つかりませんでした」と出力する

ステップ4: サポートファイルを書く

checklists/naming.md:

MARKDOWN

# 命名規約チェックリスト

## 変数名

**良い例:**
- `userCount`: ユーザー数だと明確にわかる
- `isAuthenticated`: 真偽値は is/has/can で始める
- `maxRetryAttempts`: 意味と単位の両方を示している

**悪い例:**
- `x`、`temp`、`data`: 汎用的すぎる
- `flag`、`status`: どんな状態を保持するのか言っていない
- `getUserInfo2`: 数字の接尾辞はたいてい重複があるサイン

## 関数名

**良い例:**
- `calculateTotalPrice()`: 動詞＋名詞で、動作とその対象の両方を示す
- `validateUserInput()`: 何をするか、何に対してするかを言っている
- `fetchUserProfile()`: `fetch` は非同期であることを示す

**悪い例:**
- `process()`: 汎用的すぎる、何を処理するのか
- `doStuff()`: 意図をまったく表していない
- `handleData()`: `handle` も `data` も広すぎる

## クラス名

**良い例:**
- `UserRepository`: 責任（ユーザーデータの読み書き）を示す名詞
- `PaymentProcessor`: 支払いを扱うものだと明確
- `EmailValidator`: メール検証の責任を示している

**悪い例:**
- `Manager`、`Helper`、`Utility`: 接尾辞が汎用的すぎて意味をなさない
- `DataClass`: どのデータなのか言っていない

checklists/error-handling.md:

MARKDOWN

# エラーハンドリングチェックリスト

## 必ずチェックすべきシナリオ

### 1. 外部依存の呼び出し
- API リクエスト（ネットワーク障害、タイムアウト、4xx/5xx レスポンス）
- データベースクエリ（接続失敗、クエリのタイムアウト、制約違反）
- ファイル操作（ファイルの欠落、権限不足、ディスク満杯）

### 2. ユーザー入力
- 空の入力、null、undefined
- 不正な形式の入力
- 範囲外の値

### 3. データ変換
- JSON のパース（不正な形式の入力）
- 型変換（文字列から数値への変換失敗）
- 日付のパース（無効な日付フォーマット）

## エラーハンドリングのパターン

**捕捉して処理する:**
```javascript
try {
  const data = await fetchUser(id);
  return processData(data);
} catch (error) {
  logger.error('Failed to fetch user', { id, error });
  return null; // またはカスタムエラーをスローする
}
```

**呼び出す前にチェックする:**
```javascript
if (!user) {
  throw new Error('User not found');
}
const profile = user.getProfile(); // 安全 — user は確実に null ではない
```

## よくある間違い

**問題:** 空の catch ブロック
```javascript
try {
  riskyOperation();
} catch (e) {
  // ここでは何も起きない — エラーが握りつぶされる
}
```

**修正:** 少なくともログを残す
```javascript
try {
  riskyOperation();
} catch (e) {
  logger.error('Operation failed', e);
  throw e; // またはエラーステータスを返す
}
```

ステップ5: 問題だらけのケースでテストする

問題をいくつも仕込んだスニペットを用意します。

JAVASCRIPT

function process(data) {
  var result = [];
  for (var i = 0; i < data.length; i++) {
    var item = data[i];
    if (item.type == "A") {
      var x = item.value * 2;
      result.push(x);
    } else if (item.type == "B") {
      var y = item.value / 2;
      result.push(y);
    } else {
      result.push(item.value);
    }
  }
  return result;
}

スキルを呼び出します。

出力には次のような指摘が含まれるはずです。

⚠️ 命名: process、data、x、y はいずれも汎用的すぎる
⚠️ const/let ではなく var を使っている
⚠️ === ではなく == を使っている
⚠️ data が null でないか、配列であるかを一切チェックしていない
⚠️ item.value が存在するかを一切チェックしていない
提案: この関数はより小さな純粋関数に分割できる

ステップ6: イテレーションする

最初の実行で表面化しやすいこと:

見逃し（本当は問題なのに拾えなかったもの）→ チェックルールを追加する
出力が長すぎる → 重要なものだけを報告するよう出力フォーマットを引き締める
誤検知（正常なコードを問題としてフラグ）→ 「要確認」カテゴリを追加する

改善を続ける:

レビューのたびに、すり抜けた問題を書き留める
チェックリストを更新する
もう一度テストする
1か月もすれば、スキルは本当に精度が上がる。³

まとめ

コードレビューはスキルに自然にはまる: 手順が固定、基準が測定可能、繰り返しが多い
フローをチェックリストとして構成する: 規約、エラーハンドリング、潜在的な問題、保守性
サポートファイルがスキルを保守しやすく保つ: メインファイルは短いまま、詳細なルールは別に置く
出力に等級をつけることが重要: 合格、要検討、要修正 — レビュアーが何から手を付けるべきか分かるように
イテレーションを続ける: レビューのたびに見逃したチェックを追加すれば、1か月で精度が上がる

次のレッスンでは高度なパターンに進みます。個人スキルとプロジェクトスキル、バージョン管理、そしてチームでの協働です。

レッスン6 >>

Anthropic エンジニアリングブログ: Equipping agents for the real world with Agent Skills — https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills ↩
Anthropic プラットフォームドキュメント: Agent Skills overview — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview ↩ ↩²
Claude Code skills: .NET ワークフローと再利用可能なプロンプト — https://codewithmukesh.com/blog/skills-claude-code/ ↩

練習

よく知っている領域を1つ選び — フロントエンドのコード、API 設計、SQL クエリ、ドキュメント — その領域向けのレビュースキルを作ってください。

レベル1: 自分だけのレビュースキルを作る

要件:

レビューの次元を最低3つ
各次元に具体的なチェック項目を3〜5個
明確な出力フォーマット（合格、要検討、要修正）
実際のケースで最低2件テストする

完了基準 · ローカルでチェック

各次元が明確に定義され、チェックする価値があるどのチェック項目も、行動に移せるほど具体的（「コード品質をチェックする」ではない）出力フォーマットで深刻度が一目でわかる実際のコードやドキュメントでテストし、結果を記録した

1つのコードを取り上げ、2通りでレビューします。

レベル2: 人間のレビューとスキルのレビューを比べる

自分の手で
コードレビュースキルで

それぞれが何を見つけたかを比べ、次を書き留めてください。

スキルが拾って、あなたが見逃した問題
あなたが拾って、スキルが見逃した問題
スキルの指摘のうち誤検知だったもの（問題としてフラグされたが実際は問題ない）

完了基準 · ローカルでチェック

同じコードを両方のレビュー方法に通した見つかったものを並べて比較し、記録したスキルの強みと弱みがどこにあるかを分析したスキルへの具体的な変更を提案した

レッスン5: ケーススタディ: コードレビュー用スキルを作る

コードレビューがケーススタディに向いている理由

ステップ1: レビューのスコープを決める

ステップ2: ディレクトリ構造を作る

ステップ3: メインの SKILL.md を書く

ステップ4: サポートファイルを書く

ステップ5: 問題だらけのケースでテストする

ステップ6: イテレーションする

まとめ

Footnotes

練習

よく知っている領域を1つ選び — フロントエンドのコード、API 設計、SQL クエリ、ドキュメント — その領域向けのレビュースキルを作ってください。

1つのコードを取り上げ、2通りでレビューします。