Claude Code Skills 改善サイクル実践ガイド｜NG/OKパターン蓄積・役割分離・出力設計で量産フェーズを回す

---
name: api-test-generator
description: Generates API integration test files. Use when creating tests for REST API endpoints. Handles authentication, request/response validation, and error scenarios.
allowed-tools: Read, Glob, Grep, Bash, Write
---

## NG/OK パターン（繰り返すミスの防止）

### 文字列比較
NG: `expr: response.body.status == "active"`
OK: `expr: response.body.status == 'active'`
理由: ダブルクォートはYAMLのキー構文と競合する。文字列値はシングルクォートで囲む。

### null チェック
NG: `expr: response.body.id != null`
OK: `expr: response.body.id != ""`
理由: null比較は型エラーになる。空文字列比較を使う。

### 認証ヘッダーの位置
NG: bind セクションの後に Authorization ヘッダーを記述
OK: bind セクションの前に Authorization ヘッダーを記述
理由: bind変数はヘッダー解決より後に処理されるため、変数が展開されない。

### エラーアサーション
NG: 複数条件を1つの test ブロックに詰め込む
    `test: response.status == 400 && response.body.error != "" && response.body.code == "INVALID_INPUT"`
OK: 条件を個別の verify ステップに分割
    ```
    - test: response.status == 400
    - test: response.body.error != ""
    - test: response.body.code == "INVALID_INPUT"
    ```
理由: 複合条件はどの条件で失敗したか判別が難しく、自己修正が困難になる。

## コアフロー

...（以下省略）

# .claude/skills/runn-syntax/SKILL.md
---
name: runn-syntax
description: runn YAML syntax reference and validation. Use when generating or fixing runn test files. Checks for common syntax errors specific to runn's expression language.
user-invocable: false
allowed-tools: Read
---

## runn expr-lang チートシート

### 関数
- 文字列前方一致: `hasPrefix(str, "prefix")`  ← NOT startsWith()
- 文字列後方一致: `hasSuffix(str, "suffix")`  ← NOT endsWith()
- 文字列含有: `contains(str, "substr")`

### 変数参照
- レスポンスボディ: `response.body.fieldName`
- ヘッダー: `response.headers["Content-Type"]`
- bind変数: `vars.myVar`

### ステップ参照（前ステップの結果を使う）
- 前ステップID: `steps.stepName.response.body.id`

...（詳細仕様）

---
name: design-api-tests
description: Analyzes API endpoint code and designs test cases (does NOT generate files). Use when planning what to test for a given API. Reviews source code, extracts validation logic, and outputs a test plan for user approval.
agent: Explore
context: fork
allowed-tools: Read, Glob, Grep
---

## タスク

以下の手順でテスト設計を行う（ファイルは一切生成しない）。

### Step 1: 情報収集
`$ARGUMENTS` で指定されたAPIエンドポイントに関連するコードを読む：
- ルーターファイル（URL定義）
- コントローラー（バリデーション・ビジネスロジック）
- テスト対象モデル（フィールド定義・制約）
- 既存テスト（命名パターン・カバレッジの確認）

### Step 2: テストケース洗い出し（ホワイトボックス視点）
コードから以下の観点でテストケースを抽出：
- 正常系（必須フィールドあり・オプションフィールドあり/なし）
- バリデーションエラー（各フィールドの境界値・型違い・必須欠如）
- 認証・認可（未認証・権限なし・他ユーザーのリソース）
- エッジケース（空配列・最大文字数・特殊文字）

### Step 3: 承認を求める
Markdownテーブルで生成予定のテストケース一覧を提示し、ユーザーの確認を求める。
確認が取れたら /generate-api-tests を呼び出す。

---
name: generate-api-tests
description: Generates runn API test YAML files from a pre-approved test plan. Use only after /design-api-tests has been approved by the user. Takes the test plan as input and produces test files.
user-invocable: false
allowed-tools: Read, Write, Bash
---

## タスク

引数として渡されたテスト計画に基づきAPIテストを生成する。

### 生成単位
**APIエンドポイント1つ = 1回の生成**。複数エンドポイントは個別に処理する。
理由: 一度に多くのコンテキストを持つと精度が下がり、エラー修正が難しくなる。

### 生成フロー
1. テスト計画を読み込む
2. /runn-syntax を参照してYAML記法を確認
3. テストファイルを生成
4. `runn run tests/api/target-endpoint.yaml --verbose` で実行
5. 失敗した場合：エラーメッセージを解析し、1件ずつ修正して再実行（最大3回）
6. 3回失敗した場合：エラー内容と試みた修正をサマリーとして報告

### 品質チェックリスト（生成後、ユーザーへ渡す前に必ず確認）
- [ ] すべてのテストケースが実行可能か（`runn run` が通るか）
- [ ] ファイル名が命名規則に従っているか（`test-{endpoint}-{scenario}.yaml`）
- [ ] アサーションが個別ステップに分割されているか（複合条件になっていないか）
- [ ] 認証ヘッダーが bind セクションより前に記述されているか

# NG: 複合条件（どの条件で失敗したか分かりにくい）
- test: response.status == 400 && response.body.error != "" && response.body.code == "INVALID_INPUT"

# OK: 個別ステップに分割（ステップ名で失敗箇所が即座に判明）
- test:
    title: ステータスコードが400であること
    expr: response.status == 400
- test:
    title: エラーメッセージが空でないこと
    expr: response.body.error != ""
- test:
    title: エラーコードがINVALID_INPUTであること
    expr: response.body.code == "INVALID_INPUT"

---
name: generate-and-fix
description: Generates code/test files and automatically fixes errors until tests pass. Use when you need a complete generate-test-fix cycle with automatic error correction.
allowed-tools: Write, Edit, Bash
---

## 自己修正ループ

生成後、以下の手順で自動修正を試みる：

1. 生成したファイルを実行・検証
2. エラーが出た場合：
   a. エラーメッセージを1行ずつ解析
   b. 該当箇所を特定（エラー出力に含まれるファイル名・行番号を参照）
   c. 最小限の変更で修正（関係ない箇所は触らない）
   d. 再実行
3. 修正を最大 **3回** 試みる
4. 3回で解決しない場合：
   - 試みた修正の一覧
   - 最後のエラーメッセージ全文
   - 想定される根本原因（1〜3候補）
   をサマリーとしてユーザーに報告し、処理を停止する

## 修正してはいけないもの
- テストの期待値（仕様側の問題の可能性がある）
- 認証情報・設定ファイル（スコープ外）
- 3つ以上のファイルにまたがる変更が必要な場合（設計上の問題）

.claude/
└── skills/
    ├── api-test-generator/
    │   ├── SKILL.md              # プロセスフロー（500行以内）
    │   ├── ng-ok-patterns.md     # NG/OKパターン詳細（10項目超の場合）
    │   ├── test-template.yaml    # 出力テンプレート
    │   ├── checklist.md          # 品質チェックリスト
    │   └── scripts/
    │       └── validate-yaml.sh  # 実行スクリプト
    ├── runn-syntax/
    │   └── SKILL.md              # DSL専門スキル（他スキルから参照）
    └── design-api-tests/
        └── SKILL.md              # 役割分離：調査専門スキル

## SKILL.md 内での参照例

### テンプレートの使用
出力形式は `.claude/skills/スキル名/test-template.yaml` を参照すること。
テンプレートのフォーマットから外れないよう注意する。

### NG/OKパターンの参照
詳細なNG/OKパターンは `.claude/skills/スキル名/ng-ok-patterns.md` を参照すること。
特にSection 3（アサーション記法）は毎回確認すること。

### DSL仕様の確認
記法に迷った場合は /runn-syntax を呼び出して確認すること。

## 完了前チェックリスト（Claudeが自律実行）

### 形式チェック（ツールで確認）
- [ ] `runn syntax tests/api/*.yaml` が全ファイルでパスするか
- [ ] ファイル名が `test-{endpoint}-{scenario}.yaml` 形式か
- [ ] すべてのテストに `title` フィールドがあるか

### 内容チェック（コードを読んで確認）
- [ ] テストケース設計で承認されたすべてのケースが含まれているか
- [ ] 正常系・バリデーションエラー・認証エラーの3系統が揃っているか
- [ ] アサーションが個別ステップに分割されているか（複合条件 && が残っていないか）

### ユーザーへの確認依頼
- [ ] 仕様不明な項目がある場合は、生成前にリストアップしてユーザーに確認
- [ ] テスト実行に必要な環境変数（API_KEY等）が不明な場合は確認

## ⚠ 重要：完了前チェックリスト

**ユーザーへ結果を渡す前に、必ず以下のチェックリストをすべて実行すること。**
**チェック結果を「✅ 通過 / ❌ 失敗: 理由」の形式で報告すること。**

- [ ] lint チェック: `npm run lint` でエラーがないか
- [ ] 型チェック: `npm run type-check` でエラーがないか
- [ ] テスト実行: `npm test` でfailureがないか

# /retro コマンド

セッション終了時に以下の振り返りを行い、改善PRを作成する：

## 振り返りの観点
1. **NG/OKパターン**: 今回のセッションでClaudeが繰り返したミスをリストアップ
2. **コンテキスト効率**: 200K tokenに近づいた場面と原因
3. **手動介入箇所**: ユーザーが手動で修正した箇所とその理由
4. **未使用ルール**: SKILL.mdに書いたが今回一度も適用されなかったルール

## アクション
- NG/OKパターン → 対象SKILL.mdの先頭セクションに追加
- コンテキスト肥大化 → 参照ファイルへの切り出し or サブエージェント委譲の検討
- 手動介入箇所 → SKILL.mdへのルール追加 or 役割分離の検討
- 未使用ルール → SKILL.mdから削除（シンプルに保つ）

振り返り結果をMarkdownで出力し、該当するSKILL.mdへの変更をPRとして作成する。

# CLAUDE.md または プロンプト
以下の各エンドポイントに対して /generate-api-tests を並列で実行する：
- POST /api/users（ユーザー作成）
- PUT /api/users/{id}（ユーザー更新）
- DELETE /api/users/{id}（ユーザー削除）
- GET /api/users/{id}/permissions（権限取得）

各エンドポイントの処理は独立しているため、context: fork を使って並列実行すること。

#!/bin/bash
# 生成したテストファイルの統計チェック
TESTS_DIR="tests/api"

echo "=== 生成ファイル統計 ==="
echo "総ファイル数: $(find $TESTS_DIR -name "*.yaml" | wc -l)"
TOTAL=$(find $TESTS_DIR -name "*.yaml" -exec wc -l {} + | tail -1 | awk '{print $1}')
COUNT=$(find $TESTS_DIR -name "*.yaml" | wc -l)
echo "平均行数: $(( TOTAL / COUNT ))"

echo ""
echo "=== 複合条件チェック（NG パターン検出）==="
grep -rn "&&\|test:.*==" $TESTS_DIR --include="*.yaml" | head -10

echo ""
echo "=== 認証ヘッダー位置チェック ==="
# bindの後にAuthorizationがある場合を検出
python3 scripts/check-auth-order.py $TESTS_DIR