AI駆動開発の実運用ノート

配布資料の目次　›　設定カタログ

配布資料 2303 — サブエージェント（2種）とスキル（4種）

サブエージェントは「並列で速くなる」道具だと思われがちですが、実際に効いたのは別のところでした。

レビュー観点を、そのプロジェクトで実際に事故った順に固定できることです。 汎用のレビュー観点より、自分の失敗履歴から作った観点リストのほうが検出率が高くなります。

スキルのほうは定型手順の置き場になります。ただし知識を書くと腐ります。ここでも実際に2件腐りました。

サブエージェント（.claude/agents/）

サブエージェント駆動開発（5タスク以上で適用: Plan → Explore → coder 並列 → test-generator → code-reviewer）のうち、プロジェクト固有に定義された2種。

code-reviewer

  • 役割: 現在の差分をプロジェクト規約に照らして実証的にレビューする読み取り専用エージェント（コードは変更しない）
  • 使用タイミング: 実装直後の検証フェーズ（駆動開発の第5段） / 頻度: 実装タスクごと
  • ツール: Read, Grep, Glob, Bash（書込系なし）
  • プロンプトの要点: レビュー観点7つを、優先順で固定します。
    1. バグの有無（全状態・全経路）
    2. 金銭の絶対制約（否定済み設計の再導入検知・文言 grep）
    3. 許可している権限の越境行為（テナント境界を含む）
    4. テーマ・デザイントークン（CSS だけでなく inline style・props・SVG まで）
    5. DB 規約
    6. UI 文言
    7. スコープ規律（1PR = 1レイヤー）
  • 出力の形式: ファイル:行番号 + 重大度（blocker / warning / nit）+ 根拠 + 修正提案に固定。推測禁止・最後にマージ可否の総評1行
  • 移植のヒント: レビュー観点を「そのプロジェクトで実際に事故った順」に並べてください。汎用のレビュー観点より、自分のプロジェクトの失敗履歴から作った観点リストのほうが検出率が高くなります。読み取り専用にすると「レビューのついでに勝手に直す」事故が構造的に起きなくなります

test-generator

  • 役割: 新規/変更バックエンドロジックへの Jest ユニットテスト生成・追加
  • 使用タイミング: 実装後の検証フェーズ（第4段） / 頻度: ロジック変更タスクごと
  • ツール: Read, Grep, Glob, Edit, Write, Bash
  • プロンプトの要点: DB・設定はモック化 / it 名は日本語 / 金銭ロジックは成分別 assertion（合計値だけの assert 禁止・成分ごとに個別検証・支払者区分と決済手段の全組合せ）/ ガード系は拒否・許可の両ケース / 依存追加時は既存 spec のモック追加漏れも修正（DI 回帰防止）/ テスト実行の緑表示を鵜呑みにせず対象 spec の実行を確認
  • 移植のヒント: 「合計が合っていれば OK」のテストは、成分同士の誤差相殺を見逃します。金額・数量など複合値は、成分別 assertion をエージェントの契約に書き込んでください

スキル（.claude/skills/）

定型作業の手順書です。発話のパターン（trigger）で自動的に発動します。

apply-wireframe — ワイヤーフレームデザイン適用

  • 目的: HTML ワイヤーフレームのデザインを対応する Next.js ページへ転写する
  • 発動条件: 「デザインを適用」「デザインが適用されていない」等 / 頻度: 画面実装・デザイン適用タスク時
  • 手順の要点: 画面 ID から HTML 特定 → CSS import 順確認 → data-actor 設定 → HTML→JSX 転写規則（class→className 等）→ カラーコード直書き禁止 → 目視一致チェックリスト
  • 移植のヒント: 「デザインの正本はどこか」を skill に固定すると、AI が雰囲気で配色や余白を発明しなくなります

docker-rebuild — Docker 再ビルド

  • 目的: コード変更をコンテナに反映し全コンテナを healthy にする
  • 発動条件: 「変更が反映されない」「コンテナが unhealthy」等 / 頻度: 開発中随時（特に frontend 反映時）
  • 手順の要点: 変更内容→再ビルド対象サービスの対応表 / ヘルスチェックは 127.0.0.1（Alpine で localhost 不可）/ unhealthy 時のトラブルシューティング順序とよくあるエラー4パターン
  • 移植のヒント: 「再起動すれば直る」と AI に雑にやらせず、変更種別と必要な反映手順の対応表を持たせてください（restart では frontend コードが反映されない、といった罠を封じられます）

implement-screen — 画面実装（一気通貫）

  • 目的: 設計ドキュメント + ワイヤーフレームから Backend API → Frontend → テスト → デザイン適用まで一括実装
  • 発動条件: 「画面を実装」「機能を実装」等 / 頻度: 新規画面・機能の実装時
  • 手順の要点: 実装前チェック4点（画面/URL 設計・要件・ワイヤーフレーム・スキーマ）→ DTO → Service（論理削除・ULID・監査フィールド）→ Controller（Guard）→ ユニットテスト → ページ → apply-wireframe → 完了チェック（tsc→単体→Docker→e2e）
  • 移植のヒント: 一気通貫の skill は便利ですが、知識の複製点になります。知識は rules を正本にして、skill は手順の順序だけを持たせてください

new-prisma-entity — Prisma エンティティ追加

  • 目的: 規約（ULID PK・論理削除・監査フィールド）準拠でモデル追加〜マイグレーション
  • 発動条件: 「テーブルを追加」「エンティティを追加」等 / 頻度: スキーマ拡張時
  • 手順の要点: モデルテンプレート（監査5フィールド・index・スネークケース map）→ migrate → generate → コンテナ反映 → サービス層クエリパターン（全クエリで論理削除除外）
  • 移植のヒント: 事故後にルールを強化したら、関連 skill への反映を同一コミットで行ってください（doc-ownership 方式の適用対象に skill も含めます）

教材上の位置づけ

  • サブエージェント: 第3部（サブエージェント駆動開発）
  • スキル: 第1部（設定基礎）+ 第4部（規律の仕組み化）。「既知の腐敗」2件は 二重管理の腐り方 を教える生きた教材として意図的に扱う

定義の書き方

サブエージェント（.claude/agents/*.md）

frontmatter でツールを絞り、本文に観点と出力形式を書きます。それだけです。

---
name: code-reviewer
description: 現在の差分をプロジェクト規約に照らして実証的にレビューする。実装直後に使う
tools: Read, Grep, Glob, Bash
---

あなたは現在の差分のレビュアーです。**コードは変更しません。**

## レビュー観点（この順で見る）

1. **正しさのバグ** — 全状態・全経路を数え上げ、通らない経路がないか
2. **金銭の絶対制約** — `rules/refund-architecture.md` の禁止リストに触れていないか
3. **越境** — テナント・権限の境界を跨ぐ読み書きがないか
4. **テーマ/トークン** — CSS だけでなく inline style・color/fill props・SVG まで見る
5. **DB 規約** — 論理削除の除外漏れ・ULID・監査フィールド
6. **UI 文言** — 内部用語や社内番号が画面に出ていないか
7. **スコープ規律** — 1PR = 1レイヤーになっているか

## 出力

`ファイル:行番号` + 重大度（blocker / warning / nit）+ 根拠 + 修正提案。
**推測を書かない。** 根拠は実際のコードの引用で示す。
最後にマージ可否の総評を1行。

tools に書込系を入れないのが要点になります。 読み取り専用にすると「レビューのついでに勝手に直す」事故が構造的に起きなくなります。

観点の順序は、そのプロジェクトで実際に事故った順にします。 ここでは金銭が2番目にありますが、それは金銭の事故が一番痛かったからです。

スキル（.claude/skills/<name>/SKILL.md）

スキルは手順書です。知識を書かないのがいちばん大事なところになります。

---
name: docker-rebuild
description: コード変更をコンテナに反映して全コンテナを healthy にする。
  「変更が反映されない」「コンテナが unhealthy」と言われたときに使う
---

# Docker 再ビルド

## 変更内容から再ビルド対象を決める

| 変更した場所 | 必要な操作 |
|---|---|
| frontend のコード | `build --no-cache web` → `up -d web`（**restart では反映されない**） |
| backend のコード | `build api` → `up -d api` |
| 環境変数のみ | `up -d`（再ビルド不要） |
| Prisma スキーマ | migrate → generate → `build api` |

## ヘルスチェック

`curl 127.0.0.1:3000/health` を使う。**Alpine では `localhost` が引けない。**

## unhealthy のとき

1. `logs --tail=50 <service>` で最後のエラーを読む
2. よくある4パターン: ポート衝突 / env 未設定 / migrate 未適用 / ヘルスパス誤り
3. 直らなければ `down -v` はせずに、まず1コンテナだけ再作成する

## 知識はここに書かない

スキーマ規約・Cookie 設定・認証の仕様は `.claude/rules/` が正本です。
このスキルからは参照だけしてください。

最後の節を必ず入れてください。

同じ知識を rules とスキルの両方に書くと、片方だけ更新されて腐ります。 ここでも実際に2件腐りました。Cookie の例が旧仕様のまま残り、事故後に義務化したバックアップ手順が反映されていませんでした。

正本は rules 側と決めて、スキルは手順の順序だけを持たせます。 そして doc-ownership の対象にスキルも入れておくと、次からは同一コミットで直ります。

この資料を出典にしている回