🎯 この記事で得られる成果
- ⏰ 読了時間: 約 10 分
- 🎯 対象読者: Claude Code/Cursor/GitHub Copilot 使用者
- 📊 実証データ: GitHub PR 実例あり（53 分で実装完了）
- 💡 実装難易度: ★★☆☆☆（初中級者でも実践可能）
具体的な改善効果
-
AI との往復回数が平均 85%削減（私の実測値）
- コード修正時間が 75%短縮
- CI/CD エラー率が 90%低下
実際に私がこの個人プロジェクトで実践し、通常 20 往復以上かかる実装を 3 往復で完了させた手法を公開します。
📖 前回記事もあわせてどうぞ：Claude Code で 2 週間 →3 日に短縮！AI 駆動開発で Web サイトを爆速リプレイス
😩 あなたもこんな経験ありませんか？
「AI を使えば開発が楽になる」そう思って導入したのに、実際は…
- 💬 「この機能追加して」→「わかりました」→「動かない…」の無限ループ
- 🔄 修正依頼を 10 回以上繰り返してようやく動く状態に
- ⏰ 結局手で書いた方が早かったかも？と後悔
私も同じ悩みを抱えていました。Claude Code、Cursor、GitHub Copilot…どのツールを使っても結果は同じ。
しかし、ある 5 つの方法を実践することで、劇的に改善できることを発見しました。
📉 実際の改善結果（Before/After）
改善前の開発フロー
平均往復回数: 20 回 😫
改善後の開発フロー
平均往復回数: 3-5 回 🎉
よくある失敗パターン 5 選
-
エンドレス往復地獄
何度もやり取りを重ねても、期待通りの実装にたどり着けない
-
動かないコード問題
指示通りに実装してもらったはずなのに、エラーで動作しない
-
的外れな修正
期待した機能と全く異なる箇所が修正され、本来の目的が達成されない
-
ブラックボックス化
AI が書いたコードが複雑すぎて、後から理解・修正できない
-
push まではできたけど、github actions でエラーが出てしまう
修正対応で時間が溶ける
💡 実は AI は動作確認の動画も作れる
多くの人が見落としている点ですが、Playwright 等のE2Eテストツールを組み合わせることで、Claude Code を介して動作確認動画を生成できます：
この動画により、AI が何を実装したかが視覚的に理解でき、ブラックボックス化を防げます。
これらの問題で、AI を使うほうが時間がかかるという本末転倒な状況に陥っていませんか？
📊 実測データ：従来手法 vs 改善手法
| 項目 |
従来手法 |
改善手法 |
改善率 |
| AI との往復回数 |
20 回 |
3 回 |
85%削減 |
| 実装時間 |
6 時間 |
1.5 時間 |
75%短縮 |
| CI/CD エラー率 |
ほぼ毎回 |
稀に |
90%低下 |
| コード品質 |
不安定 |
テスト付き |
大幅向上 |
根本原因：「よしなに」では伝わらない
人間同士でも難しいコミュニケーション
AI は確かに指示を理解し実行できますが、人間と同じように具体的な指示が必要です。
想像してみてください：
- 部下に「これよろしく」と丸投げする上司
- 「適当にやっといて」という曖昧な依頼
これらは人間同士でも問題になりますよね？AI でも同じことが起こっています。
でも「よしなに」したい気持ちもわかる
とはいえ、AI には「察して欲しい」「いい感じにやって欲しい」というのが本音。
実はこれを実現する方法があります。
解決策 1：仕様書ベースの開発プロセス
ステップ 1: 簡易仕様書の作成
まずは GitHub の Issue やドキュメントに、以下の要素を含む簡易仕様書を書きます：
## 機能概要
ユーザー登録機能の実装
## 要件
- result 画面の表示変更
## 概要
現在、回答をしたときに点数は出てきますが、どの問題が間違ったかを表示していません。
result 画面にどの問題が間違ったかを表示して、拡張として答えと解説を表示してください
## 下記を検討してください
- どのファイルを追加・修正するか記述してください
- cookie の保持方法に修正があれば、構造データを出してください
- テストを作成し、result 画面に答えと解説が表示されるかを確認してください
- 不要なファイルはコミットに含めないでください
- commit / push 時に lefthook で問題が出た場合は修正してください
- gh コマンドで PR を作成し、リザルト画面の動画を添付する
- 下記は実際に playwright で起動し、問題を解き実行して保存してください
screenshots 配下に格納
2 問間違った時の動画 webm 動画で添付
3 問間違った時の動画 webm 動画で添付
- push した後にアクションの結果を gh pr checks で確認し、不備があれば修正する。
- アクションが正常に終了した後に完了としてください
ステップ 2: AI に理解度チェックを依頼
仕様書を読み込ませて、以下を確認：
この仕様書を読んで、以下を教えてください：
1. あなたの理解している実装内容
2. 不明な点や確認が必要な箇所
3. 実装の順序と各ステップでのチェックポイント
4. 想定される技術的課題
実例：私のプロジェクトでの活用
この方法により、AI が「よしなに」理解してくれる土台を構築できます。
📊 実際の成果
上記の PR では：
- 仕様書作成：30 分
- AI 理解確認：10 分
- 実装完了：1 時間
-
合計：約 1.5 時間で完成（従来は 6 時間）
🎯 実測データ（GitHub のタイムスタンプより）:
- PR 作成: 2025 年 8 月 10 日 18:28 (JST)
- PR マージ: 2025 年 8 月 10 日 19:21 (JST)
-
実際の所要時間: 53 分 16 秒 ✨
わずか 1 時間未満で、テスト付きの機能実装から動画撮影、PR 作成、GitHub Actions 通過まで完了しました。
解決策 2：テスト駆動で AI に「視覚」を与える
なぜテストが重要なのか？
AI はコードを書けますが、動作確認は指示しないと行いません。
ここで重要になるのが、AI に「視覚情報」を持たせることです。
実装すべきテスト戦略
1. 単体テスト・結合テスト
describe("ユーザー登録API", () => {
test("正常な登録データで成功する", async () => {
const response = await request(app).post("/api/register").send({
email: "[email protected]",
password: "password123",
});
expect(response.status).toBe(201);
expect(response.body).toHaveProperty("token");
});
test("重複メールでエラーになる", async () => {
await createUser("[email protected]", "password123");
const response = await request(app).post("/api/register").send({
email: "[email protected]",
password: "password456",
});
expect(response.status).toBe(409);
expect(response.body.error).toBe("メールアドレスが既に使用されています");
});
});
2. E2E テスト
test("ユーザー登録フロー", async ({ page }) => {
await page.goto("/register");
await page.fill('input[name="email"]', "[email protected]");
await page.fill('input[name="password"]', "securepass123");
await page.click('button[type="submit"]');
await expect(page).toHaveURL("/dashboard");
await expect(page.locator(".welcome-message")).toBeVisible();
});
自律的な改善サイクルの構築
AI に以下の指示を出します：
1. テストを実行して結果を確認
2. 失敗したテストがあれば原因を分析し修正
3. 全てのテストが通ったらコミット
4. 新しい機能追加時は必ずテストも追加
このサイクルを、私が「OK」と言うまで繰り返してください。
解決策 3：仕様書に全てを任せる勇気
大きなタスクこそ、詳細な仕様書で一発解決
**仕様が確定している小〜中規模タスクでは、段階的アプローチを省略できる場合があります。**しっかりした仕様書があれば、AI は明確に定義されたタスクを効率的に実装できます※1。
実際の仕様書例（私が使用したもの）
## 下記を検討してください
- どのファイルを追加・修正するか記述してください
- cookie の保持方法に修正があれば、構造データを出してください
- テストを作成し、result 画面に答えと解説が表示されるかを確認してください
- 不要なファイルはコミットに含めないでください
- commit / push 時に lefthook で問題が出た場合は修正してください
- gh コマンドで PR を作成し、リザルト画面の動画を添付する
- 下記は実際に playwright で起動し、問題を解き実行して保存してください
screenshots 配下に格納
2 問間違った時の動画 webm 動画で添付
3 問間違った時の動画 webm 動画で添付
- push した後にアクションの結果を gh pr checks で確認し、不備があれば修正する
- アクションが正常に終了した後に完了としてください
なぜこれで動くのか？
- AI は複数タスクを並列処理できる
- テストによる自動検証で品質担保
- CI/CD まで含めた完全自動化
実際、上記の仕様書だけで 53 分で PR 完成まで到達しました。段階的にやる必要はありません。
解決策 4：プロジェクト文脈の共有
CLAUDE.md の活用
プロジェクトルートに以下の情報を記載：
# プロジェクト情報
## 概要
React で構築されたタスク管理アプリケーション
## 技術スタック
- Frontend: React 18 + TypeScript + Vite
- Backend: Node.js + Express + Prisma
- Database: PostgreSQL
- Testing: Jest + React Testing Library + Playwright
## 開発コマンド
- 開発サーバー: `yarn dev`
- テスト実行: `yarn test`
- E2E テスト: `yarn test:e2e`
- ビルド: `yarn build`
- 型チェック: `yarn type-check`
## コーディング規約
- 関数はアロー関数で統一
- コンポーネントは PascalCase
- ファイル名は kebab-case
- CSS は Tailwind CSS 使用
## 重要なルール
- 新機能追加時は必ずテストも作成
- TypeScript の厳密モードを維持
- コミット前に必ず lint + type-check を実行
解決策 5：Lefthook で CI/CD エラーを事前防止
GitHub Actions で失敗する前に、ローカルで確実にチェック
「push したら CI で失敗して修正対応で時間が溶ける」という問題を解決するために、Lefthook を活用します。
Lefthook とは？
Git hooks を簡単に管理できるツールで、コミット前やプッシュ前に自動的にテストやリントを実行できます。
どことなく、GithubWorkflow と似てますよね？
インストール方法
npm install --save-dev lefthook
yarn add -D lefthook
pnpm add -D lefthook
インストール後、以下のコマンドで初期化：
セットアップ例
pre-commit:
commands:
lint:
run: yarn lint --fix
type-check:
run: yarn type-check
test:
run: yarn test --watchAll=false
pre-push:
commands:
build:
run: yarn build
e2e:
run: yarn test:e2e --headless
AI への指示例
以下の順序で実装してください：
1. lefthook.yml を設定し、CI と同じチェックをローカルで実行
2. コミット前に自動的にlint、型チェック、テストを実行
3. エラーが出た場合は自動修正を試行
4. 全てのチェックが通ってからコミット・プッシュ
5. それでも CI で失敗した場合のみ、追加修正を実施
このプロセスを自動化してください。
効果
- ✅ CI 失敗率が大幅に減少
- ✅ 修正のための往復時間を削減
- ✅ 品質の高いコードを確実にプッシュ
まとめ：AI との協働を成功させる 5 つのポイント
1. 仕様書ファースト
簡易要件を AI に渡し、詳細設計を書かせて相互理解を構築
2. テスト駆動開発
AI に「視覚」を与え、自律的に品質をチェックしてもらう
3. 仕様書駆動アプローチ
詳細な仕様書があれば、AI は複雑なタスクも一気に実装可能
4. 文脈の共有
プロジェクトの背景・技術選択・制約を AI と共有
5. CI/CD 連携
Lefthook で事前チェックし、CI 失敗を防止
📊 最終成果：この記事の手法を実践した結果
これらを実践することで：
| 効果 |
数値 |
実例 |
| ✅ 往復回数の削減 |
85%減 |
20 回 → 3 回 |
| ✅ 開発時間の短縮 |
75%減 |
6 時間 → 1.5 時間 |
| ✅ CI エラー率 |
90%減 |
ほぼ毎回 → 稀に |
| ✅ コード品質 |
大幅向上 |
テストカバレッジ 90%以上 |
結果として、AI は本当の意味での「開発パートナー」になります。
従来の「AI に振り回される開発」から脱却し、「AI と一緒に効率的に開発する」スタイルを確立しましょう。この方法論は、どの AI ツールを使っても応用できる普遍的なテクニックです。
📣 この記事を読んだあなたの次のアクション
👉 今すぐ試せる 3 つのステップ
-
今取り組んでいるタスクを簡単な仕様書にする（10 分）
-
AI に理解度チェックをさせる（5 分）
-
AI に視覚情報を与える！テストを書かせて自動検証させる（15 分）
最も効果的なのは、AI に実装とテストを同時に書かせることです。
具体的な指示例：
以下の機能を実装してください：
1. ユーザー登録API（/api/register）
2. 必ず単体テストを作成し、実行して成功を確認
3. テストには正常系と異常系の両方を含める
4. テスト結果を見せてください
AI が生成するテストの例：
describe("ユーザー登録機能", () => {
it("正常なデータで登録成功", async () => {
const result = await registerUser({
email: "[email protected]",
password: "secure123",
});
expect(result.success).toBe(true);
});
it("無効なメールアドレスでエラー", async () => {
const result = await registerUser({
email: "invalid-email",
password: "secure123",
});
expect(result.error).toBe("メールアドレスが無効です");
});
});
ポイント：
- テストが通るまで AI に修正を繰り返させる
- 全てグリーンになってから次の機能へ
- これだけで品質が劇的に向上
👬 この記事をシェアしてみませんか？
もしこの記事が役に立ったら、ぜひチームメンバーや同僚にシェアしてください。みんなで AI との往復を減らし、開発効率を上げましょう！
💬 フィードバック募集中
この手法を試した結果や、もっと良い方法があれば、コメントで教えてください。みなさんの経験を共有して、より良い AI 活用方法を一緒に作っていきましょう！
🏷️ 関連タグ
#Claude_Code #AI駆動開発 #プロンプトエンジニアリング #開発生産性 #2025年最新
📚 参考リンク
著者について
🚀 AI 駆動開発を日々実践中のエンジニア
- 💼 業務：インフラ〜フロントエンドまで AI 駆動で開発
- 🏢 経験：GCP/AWS、オンプレインフラ構築、フルスタック開発
開発歴: ${new Date().getFullYear() - 2005}年〜
- 🎯 目標：AI 駆動開発のスペシャリストを目指して日々学習中
- ♟️ 趣味：囲碁（浦添囲碁会館で土曜大会参加）
📧 お仕事のご相談
AI 駆動開発のご相談、開発案件のお問い合わせはお気軽にどうぞ！
以下のような案件を承っております：
- 🌐 Web サイト・アプリケーション開発
- 🔄 既存システムの AI 活用リファクタリング
- ☁️ インフラ構築・最適化
- 💡 技術顧問・コンサルティング
連絡先:
フォローしていただけると嬉しいです！最新の AI 開発テクニックを共有していきます
注釈
※1 段階的アプローチについて：大規模開発や仕様の不確定要素が多い案件では、段階的なアプローチが依然として有効です。本記事で紹介した「一発実装」は、要件が明確で、仕様が確定している小〜中規模のタスクにおいて特に効果を発揮します。プロジェクトの規模や複雑さに応じて、適切なアプローチを選択することが重要です。
※ この記事の数値は、私の個人プロジェクトでの実測値です。効果はプロジェクトや環境によって異なる場合があります。
