このlessonをすべて読み終えたら、以下の3つを自信を持って実践できます。

• ▸✅ SPEC → Plan → Tasks → Implement のフロー
• ▸✅ Agent モードの安全な使用 (dry-run · 承認ゲート)
• ▸✅ Git コミット単位 + AI が生成したコードの PR 説明方法

学習目標をチェックリストとして置き、すべてに答えられるようになったらlessonを閉じてください。

一言で: シンプルな作業 = 素早くvibe / 複雑な作業 = まずSPEC。

SPECが先の場合:

• ▸🟢 大規模機能 (1週間以上の作業)
• ▸🟢 複数人協業 (PRレビュアーが必要)
• ▸🟢 セキュリティ · 決済 · 認証
• ▸🟢 バックエンド API 契約
• ▸🟢 データスキーマの変更

Vibeが先の場合:

• ▸🟢 UI コンポーネント (ボイラープレート)
• ▸🟢 小さなバグ修正
• ▸🟢 リファクタリング · 名前の変更
• ▸🟢 テストの作成
• ▸🟢 ドキュメント · コメント

Spec-Kit ワークフロー (GitHub, 2025):

/specify  → spec.md  (要件)
/plan     → plan.md  (実装戦略)
/tasks    → tasks.md (チェックリスト)
/implement→ 実際のコード作成

Anthropic Skills + Claude Code と組み合わせることで自動化できます。

エージェント = LLM が ツール呼び出し · 結果確認 · 次の行動決定 を 自律的に 繰り返すもの。

基本ループ:

1. 目標を受け取る
2. 計画 (サブタスクに分解)
3. ツール呼び出し (編集 · 実行 · テスト)
4. 結果の評価
5. 次の行動を決定 → 2へ (または終了)

エージェントが得意な作業:

• ▸🟢 反復作業: 100ファイルの一括変更
• ▸🟢 探索: コードベース理解 · デバッグ仮説の検証
• ▸🟢 地道な作業: マイグレーション · テスト作成 · ドキュメント更新
• ▸🟢 夜間 · 週末作業: ユーザーが寝ている間に自動でPRを生成

制約:

• ▸🔴 完全自律 X — 5〜10分ごとにユーザーの承認を推奨
• ▸🔴 コストの高い呼び出し (Opus 1M コンテキスト = $90/M)
• ▸🔴 危険な操作 (rm -rf · DB DROP) を直接実行するリスク
• ▸🔴 ハルシネーション — 架空の関数呼び出し · ドキュメント生成

安全策:

• ▸権限モード: ask (全操作を承認) → acceptEdits (編集のみ) → plan (変更なし)
• ▸サンドボックス: Docker · worktree 分離
• ▸チェックポイント: 毎コミット後にレビュー
• ▸ロールバック準備: git reset で復元可能

> 💡 2025年のトレンド: GitHub Actions + Claude Code の組み合わせ → 夜間にPRを自動生成・テスト するパターンが広まっています。

TDD サイクル: Red (失敗テスト) → Green (通過コード) → Refactor (整理)

AI の役割:

AI が得意なテスト:

• ▸🟢 ユニットテスト (input/output がシンプル)
• ▸🟢 エッジケース (null · 空配列 · 非常に大きな数)
• ▸🟢 ボイラープレート (jest · vitest · pytest セットアップ)

AI が苦手なテスト:

• ▸🔴 複雑な結合テスト (DB · 外部 API · 認証フロー)
• ▸🔴 ビジネス要件 (ドメイン知識が必要)
• ▸🔴 パフォーマンステスト (実際の環境が必要)
• ▸🔴 フレーキーなテストの診断 (タイミング · 環境依存)

Cursor · Claude Code の活用:

「この関数 (/src/auth.ts) の vitest テストを作成:
- 成功ケース (有効なメール · パスワード)
- 失敗 (空入力 · 短いパスワード · 無効なメール)
- エッジ (メール100文字 · パスワード1000文字 · SQLインジェクション試行)
- モック: db, bcrypt」

> 💡 Iron Law: AI が作成したテストも 自分で読んで理解。テスト通過だけを見て信頼しないこと。

原則:
1. 小さなコミット — 1コミット = 1つの変更意図。AI レビューが効果的になる
2. 明確なメッセージ — Conventional Commits (feat · fix · refactor)
3. PR 自動化 — Copilot Review · CodeRabbit などによる自動一次レビュー
4. 自動テスト — CI が通過しなければマージ不可

AI Git ツール:

AI 時代の PR テンプレート:

## 変更
- 何を · どこで · なぜ

## AI 協業
- 使用ツール: Cursor Composer / Claude Code
- AI 生成割合: ~60% (ボイラープレート), 40% 手動
- 検証: 統合テスト通過 · 手動 dogfood

## テスト
- vitest pass: 12/12
- 手動: dev サーバーで入力・例外を確認

よくある落とし穴:

• ▸❌ AI が生成したコードをすべて一つのコミットに — レビュー不可能
• ▸❌ AI が他の場所も勝手に変更 — レビュー時に驚く
• ▸❌ コンパイルエラーだけ見てマージ — ビジネスロジック未検証
• ▸✅ Plan モードで開始 → 小さな単位で変更 → 即座にコミット

SPEC を書くと なぜ トークンが節約できるのか

旧来のやり方: 毎回の会話で「この機能を作って → AI が質問 → 回答 → AI が実装」を繰り返す。同じコンテキストを N回 繰り返す。

SPEC-Driven: 最初に spec.md を一度だけ作成 → その後のすべての会話は その spec を参照。コンテキストは1回 + 短い後続リクエスト。

実践フロー

ステップ1: AI と一緒に spec.md を作成

私: 決済システムを作りたい。まずspecを作ろう。
   - 決済ゲートウェイ: Toss
   - 商品: 単回購入 + 定期サブスクリプション
   - 返金・精算ロジックが必要
   AI に仕様を作成してもらいたい。

AI: (spec.md を作成)
  # 決済システム仕様

  ## 要件
  1. 決済ゲートウェイ統合 (Toss)
  2. 商品種別: SINGLE / SUBSCRIPTION
  3. 返金処理 (7日以内)
  4. 精算 (毎月1日)

  ## API エンドポイント
  - POST /api/payments/init
  - POST /api/payments/confirm
  - POST /api/payments/refund
  ...

この spec.md が プロジェクトルート に保存される。

ステップ2: 実装 — 説明を繰り返さずに

私: spec.md の POST /api/payments/init を実装して。

AI: (spec を読んで正確に実装)

毎回「Toss ゲートウェイ · サブスクリプション · 返金ポリシー」を繰り返さない。spec 一度 + 短いリクエスト だけ。

ステップ3: コードレビュー — spec 基準で

私: 実装は spec.md と一致しているか？差異があれば教えて。

AI: (spec とコードを比較)
  ✅ /init エンドポイント — spec と一致
  ⚠️ /refund — spec は7日だがコードは14日になっている
  ❌ /confirm — spec の webhook 検証ステップが欠落

Spec-Kit (GitHub, 2025)

GitHub が作った SPEC-Driven 標準ツール。4段階自動化:

/specify  → spec.md を自動生成 (要件)
/plan     → plan.md を自動生成 (実装戦略)
/tasks    → tasks.md を自動生成 (チェックリスト)
/implement → 実際のコード作成

Claude Code · Cursor と組み合わせると 仕様 → コード まで 一つのフロー。

SPEC vs Vibe — 改めて整理

まとめ

• ▸大きな作業 → まず SPEC、その後実装 = トークン節約 + 一貫性
• ▸小さな作業 → そのまま Vibe でもOK
• ▸Spec-Kit で 仕様 → コード を自動化

核心を一言で

エージェント = AI が 自律的にファイルを変更・コマンドを実行 する。誤った使い方をすると 自分のコード · DB · 本番環境 まで壊れる可能性がある。安全使用の5原則。

⚠️ 絶対にしてはいけないこと

1. --dangerously-skip-permissions の使用禁止

Claude Code のオプションの中に 全権限を自動承認 するモードがあります。速いのは確かですが、AI が rm -rf のような危険なコマンドも質問なしに実行してしまいます。本番コードやDBが破損する恐れがあります。

✅ 常に デフォルトモード (Ask または Plan) で開始。

2. 権限モードの段階 — 段階的に許可

推奨フロー: Plan で開始 → 確認 → Ask で段階的に → 必要に応じて AcceptEdits

3. Git commit を頻繁に — ロールバックポイント

# 作業開始前
git add -A && git commit -m "checkpoint: エージェント作業開始前"

# エージェント作業後
git diff   # 変更を確認
git add -p # 部分的なステージング (意図しない変更を除外)
git commit -m "feat(auth): JWT refresh を追加"

# 失敗した場合
git reset --hard HEAD~1   # 直前のコミットに戻る

意味のある単位 ごとにコミット。壊れた部分だけを 部分的にロールバック できる。

4. 別の worktree で隔離

git worktree add ../myapp-experiment my-feature
cd ../myapp-experiment
claude    # 隔離されたフォルダで作業

元のコードへの ダメージ0%。失敗したら git worktree remove ../myapp-experiment で終わり。

5. Docker コンテナ — 完全な隔離

docker run --rm -it -v $(pwd):/app -w /app node:20 bash
# 中で claude を実行
# コンテナ内でのみコマンドが実行される → ホストは安全

危険な作業 (DB マイグレーション · システムコマンド) は 必ず コンテナ内で。

危険なコマンドの ブラックリスト

エージェントが実行する 前に もう一度確認:

• ▸rm -rf (特に * または / を含む)
• ▸git reset --hard (コミットが失われる)
• ▸git push --force (リモートを上書き)
• ▸DROP TABLE · TRUNCATE (DB データの削除)
• ▸npm publish (誤った公開)
• ▸curl ... | sh (外部スクリプトの実行)
• ▸sudo が付いたすべてのコマンド

事故が起きたとき — 素早く復旧

1. 即座に停止 — Ctrl+C
2. 変更を確認 — git status · git diff
3. ロールバック — git reset --hard HEAD または git stash
4. DB の場合 — 最終バックアップを確認
5. 事後分析 — ~/.claude/projects/ のトランスクリプトを確認

まとめ

• ▸絶対に 全権限自動許可 はしない
• ▸Plan → Ask → AcceptEdits の段階的なステップ
• ▸頻繁な git commit + worktree 隔離 + Docker がセーフティネット
• ▸危険なコマンドは もう一度 確認

なぜコンベンションに従うのか

fix: bug fixed

こういうメッセージが100個あると 後で見つけられない。標準のコンベンションに従えば:

• ▸git log --grep "^feat(auth)" — auth 領域の新機能だけを抽出
• ▸semantic-release — 自動バージョニング + CHANGELOG
• ▸CI 検証 — commitlint で不正なメッセージの PR をブロック

形式

<type>(<scope>): <description>

[optional body]

[optional footer]

• ▸type — feat · fix · refactor · docs · test · chore · perf · style
• ▸scope — 領域 (auth · api · ui など)
• ▸description — 命令形、50文字以内

実践例5選

1. feat — 新機能

feat(auth): add JWT refresh token rotation

- Access token の TTL を短縮 (60min → 15min)
- Refresh token のローテーションを導入 (再利用時に全無効化)
- httpOnly + Secure + SameSite=Lax cookie
- RFC 8252 の推奨事項を反映

Closes #142

2. fix — バグ修正

fix(api): handle null user in /api/me

未ログイン状態で /api/me を呼び出すと500エラーが発生。
セッション検証結果が null の場合に明示的に401を返すよう変更。

Before: TypeError: Cannot read 'id' of null → 500
After:  { error: 'NOT_AUTHENTICATED' } → 401

Fixes #198

3. refactor — リファクタリング (動作変更なし)

refactor(db): migrate from Prisma to Drizzle

- ビルド時間 8s → 2s (Prisma generate を削除)
- バンドルサイズ 250KB → 50KB
- TypeScript の型推論の精度向上

Migration guide: docs/db-migration.md

4. test — テストの追加・修正

test(auth): add edge cases for login endpoint

- 空のパスワード
- SQL インジェクション試行 (`' OR '1'='1`)
- 1000文字以上の入力
- 無効なメール形式 (RFC 5322)

Coverage: 78% → 91%

5. chore — ビルド · 依存関係 · ツール

chore(deps): bump next from 14.1 to 14.2

Security: CVE-2024-XXXX のパッチを含む
Breaking: middleware matcher の正規表現が変更

Migration:
- middleware.ts:12 の matcher パターンを更新
- /api/auth/* → /api/auth/(.*) に変更

チームコンベンション の例

追加 type (チームによって異なる):

• ▸perf — パフォーマンス改善
• ▸style — フォーマット · セミコロン (CSS ではない)
• ▸ci — GitHub Actions · ワークフロー
• ▸build — webpack · vite の設定
• ▸revert — 以前のコミットを元に戻す

commitlint による自動強制

npm install --save-dev @commitlint/cli @commitlint/config-conventional
echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

GitHub Actions:

- uses: wagoid/commitlint-github-action@v6

→ PR のすべてのコミットメッセージを自動検査。不正な形式だと マージをブロック。

まとめ

• ▸type + scope + description の標準形式
• ▸50文字以内の一行 + 詳細は body に
• ▸semantic-release · CHANGELOG の自動化で報われる
• ▸commitlint で チーム全体に強制

このlessonの概念を知れば、AIに具体的に指示できるようになります。漠然とした「直して」ではなく、語彙を持ったリクエスト — それがトークン節約の出発点です。

• ▸「この SPEC を基に Plan → Tasks → Implement のフローを作って」
• ▸「AI エージェントモードを安全に使うための dry-run + 承認ゲートのパターンを教えて」

なぜこれでトークンが減るのか

概念を知らないと、AI の返答を受け取っても 「それって何ですか？」 と再度質問しなければなりません。その「再質問」がトークンを消費します。概念を一度理解しておけば、会話が一度で終わります。