AI時代の開発ワークフロー実践ロードマップ ― 78バグから10本の記事を書いて見えたこと

Last updated at 2026-05-31Posted at 2026-05-31

AI時代の開発ワークフロー実践ロードマップ ― 78バグから10本の記事を書いて見えたこと

TL;DR

78件のバグ → 6カテゴリ分類 → 7つの設計原則 → 6コマンドのClaude Code Skillに体系化
SFAD（Spec-First AI Development）: 仕様を先に書き、テストで守り、AIに実装させるワークフロー
10本のシリーズを「課題別」「役割別」「導入順」の3軸で案内するガイドマップ
どの記事から読んでも理解できる構成（依存関係と推奨順序付き）
全コマンドの導入手順とSFAD Skill のインストール方法

この記事でできること

やりたいこと	この記事で得られるもの
シリーズの全体像を把握したい	10本の要約と関係図
自分に合った記事を選びたい	課題別・役割別の案内
SFADを導入したい	ステップバイステップのロードマップ
チームに紹介したい	1ページで伝わる概要

1ヶ月前、私は78個のバグを前に途方に暮れていました。

今日、そのバグたちは6つのコマンドと7つの原則になっています。

この記事は、10本のシリーズの最終回であり、全体の入口でもあります。「どこから読めばいいかわからない」という方のためのガイドマップです。

10本で伝えたかったこと

シリーズ全体のストーリーを3分で読める要約です。

起: 78バグの発見（記事1-2）

ある業務システムをClaude Codeで開発し、リリース後に78件のバグを記録しました。最初は「AIが書いたコードだからしょうがない」と思っていました。

でも分類してみると、構造が見えました。

バグカテゴリ	件数	予防手段
print残留	23件	lintで防げた
仕様齟齬	15件	仕様の書き方で防げた
bare except	12件	lintで防げた
テスト不足	11件	テスト基盤で防げた
型安全	9件	型チェックで防げた
その他	8件	-

78件のうち、lint strictだけで35件（45%）が防止可能でした。「AIが悪い」のではなく、「品質基盤のない状態でAIに開発してもらっていた」ことが原因でした。

承: 原因の構造化（記事3-4）

15件の仕様齟齬を掘り下げたら、全てのケースで「ルール」「具体例」「疑問点」が欠落していました。Example Mappingという手法でこの3つを構造化すると、仕様の抜け漏れを事前に潰せることがわかりました。

23件の設計起因バグを掘り下げたら、Outside-In（外側から内側へ）ではなくInside-Out（内側から外側へ）で実装していたことが根本原因でした。受け入れテストを先に書いて「ゴール」を定義してからユニットテストと実装に入るDouble-Loop TDDのアプローチで、この問題を解消できました。

転: 解決策の体系化（記事5-7）

bare except 12件と型安全9件からは、「AIが書く"動くけど危ないコード"」の見抜き方を整理しました。lint strictと型チェックstrictの設定で、機械的にブロックできる問題でした。

既存コードへの適用方法として、reverseコマンド（既存コードから仕様を逆算する手法）を実践しました。テストも仕様書もないコードに後から品質を注入するアプローチです。

78件の分析結果を7つの設計原則に集約しました。「Day 0に品質基盤を構築する」「Discoveryが先」「テストは仕様の表現」「仕組みで防ぐ」など、AI開発で守るべきガイドラインです。

結: ツールへの昇華（記事8-9）

7つの原則を「知っている」だけでは意味がありません。6つのClaude Codeコマンド（init, cycle, spec, test, impl, reverse）として実装し、コマンド1つで手順が実行される仕組みにしました。

さらに「自分のワークフローをSkillとしてパッケージ化する方法」を7ステップで公開しました。コードレビュー、ドキュメント生成、デプロイメントチェックリストなど、あらゆる開発手法をSkill化できます。

月曜日からできること

「理論はわかったけど、何から始めればいいのか」という方のために、3つの実践レベルを整理しました。

レベル1: 今日できること（30分）

lint strictを入れます。これだけで78件中35件（45%）を予防できます。

Python の場合:

# ruff をインストールして実行
pip install ruff
ruff check . --select T201,E722,BLE001,ANN401

ルール	検出対象
`T201`	print文を検出する
`E722`	bare exceptを検出する
`BLE001`	blind exception（Exception全般を捕捉）を検出する
`ANN401`	Any型の使用を検出する

TypeScript の場合:

tsconfig.json に以下を追加します。

{
  "compilerOptions": {
    "strict": true
  }
}

ESLintの設定に以下を追加します。

{
  "rules": {
    "no-console": "error"
  }
}

Go の場合:

# golangci-lint をインストールして実行
golangci-lint run

.golangci.yml に forbidigo（fmt.Println禁止）と govet（型チェック）を有効にします。

30分の投資で、最も頻度が高いバグカテゴリを機械的にブロックできます。今日中にできます。

レベル2: 今週できること（4時間）

CI + pre-commit + テスト基盤を整えます。これで追加11件（合計59%）を予防できます。

GitHub Actions のテンプレート（Python）:

name: CI
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install ruff mypy pytest
      - run: ruff check .
      - run: mypy . --strict
      - run: pytest

GitHub Actions のテンプレート（TypeScript）:

name: CI
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm ci
      - run: npx eslint .
      - run: npx tsc --noEmit
      - run: npm test

GitHub Actions のテンプレート（Go）:

name: CI
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: "1.22"
      - run: go vet ./...
      - run: golangci-lint run
      - run: go test -race ./...

CIに lint + 型チェック + テストを組み込むことで、PRをマージする前に問題を検出できます。pre-commitフックを入れれば、コミット時点で検出できます。

レベル3: 今月できること（継続的）

ここからは手法の導入です。一度にやらず、1つずつ試してください。

Example Mapping を試す

最初はQuestion Listだけで十分です。次の機能を作る前に「この機能について、まだ決まっていないことは何か？」をリストアップするだけです。

機能: ユーザー登録
Questions:
- パスワードの最低文字数は？
- メールアドレスの重複チェックは必要か？
- 登録後の確認メールは送るか？
- ソーシャルログインは対応するか？

これだけでも仕様齟齬は大幅に減ります。Question Listに慣れたら、Rules と Examples を追加してフルのExample Mappingに進みます。

1機能だけ Double-Loop TDD で実装してみる

全ての機能をDouble-Loop TDDで作る必要はありません。まず1機能だけ試します。

受け入れテストを先に書く（外側のループ）
ユニットテストを書く（内側のループ）
実装してテストをGreenにする
リファクタリングする

1回やると「なるほど、こういう流れか」と体感できます。体感すると、次から自然に使えるようになります。

既存コードの仕様を1つ reverse で抽出してみる

テストがない既存コードを1ファイルだけ選んで、「このコードは何をしているか」を言語化してみます。Given-When-Then形式で書き出すと、「あれ、この条件のときどうなるんだろう」という疑問が見つかります。その疑問がバグの種です。

よくある質問

Q: AIを使わない開発にも適用できますか？

A: はい。BDDもTDDも、AI以前から存在する手法です。Example MappingはMatt Wynneが2015年に提唱しました。Double-Loop TDDはFreeman & Pryceが2009年にGOOS本で体系化しました。これらはAIがなくても有効です。AIを使うと、テストコードの生成や実装の速度が上がるため、TDDのサイクルがより速く回るようになります。AIが加速装置として機能する、ということです。

Q: チームに導入するにはどうすれば？

A: 記事7で書いたチーム導入のアプローチを参考にしてください。ポイントは「全員一斉に導入しない」ことです。まず1人が1機能で試す。うまくいったら2人目が試す。成功体験が積み重なったらチームに展開する。トップダウンで「明日からこの手法を使え」と言っても定着しません。

Q: SFADのSkillファイルはどこで手に入りますか？

A: 記事8-9でSkillの設計思想と作り方を公開しています。ファイルの構造、Phase設計の考え方、ゲートの配置方法を全て説明しています。「完成品をダウンロードする」より「自分のプロジェクトに合わせて作る」方が効果的です。なぜなら、プロジェクトごとにワークフローは異なるからです。

Q: Python以外でも使えますか？

A: はい。SFADは10スタック（Python, TypeScript, Go, Rust, Ruby, Java, Kotlin, Swift, PHP, C#）に対応しています。各記事でTypeScript/Goのコード例を示しています。BDD/TDDの考え方は言語に依存しません。ツールチェーン（テストランナー、linter、型チェッカー）が言語ごとに異なるだけです。

Q: 1人でも使えますか？

A: 個人開発でこそ効果があります。チーム開発ではレビューアーが問題を指摘してくれますが、個人開発にはレビューアーがいません。Skillが「自動レビューアー」の役割を果たします。ゲートで止まるたびに、自分で仕様を見直す機会が生まれます。私がSFADを作ったのも、1人で開発しているときにバグが多発したからです。

全10記事へのリンク集

読む目的に合わせて、4つのルートを用意しました。

入門ルート（初めての方）

AIと開発するときの課題感を理解してから、具体的な手法に入るルートです。

記事1: AIと開発して78個のバグを踏んだので全部分類した（Qiita、無料）
記事2: テスト不足18件から学んだこと ― Double-Loop TDDの考え方（Qiita、無料）
記事3: AIに伝わる仕様書の書き方 ― Example Mappingで要件を構造化する（Qiita、無料）
記事5: エラーを「握りつぶす」コードの見抜き方 ― Python・TypeScript・Go・Rustで学ぶエラーハンドリング設計（Qiita、無料）
記事10: この記事（Qiita、無料）

実践ルート（すぐに使いたい方）

手法と原則を理解して、自分のプロジェクトに適用するルートです。

記事3: AIに伝わる仕様書の書き方 ― Example Mapping（Qiita、無料）
記事4: 設計起因バグ23件の根本原因 ― Outside-In実装とは何か（Qiita、無料）
記事7: 78バグから導いた7つの設計原則（note、有料）
記事8: 78バグを6コマンドに変えた話 ― SFADの設計思想（note、有料）

レガシーコード対応ルート

テストも仕様書もない既存コードを改善したい方向けのルートです。

記事6: 既存コードをAIで解析する ― SFADのreverseコマンド実行記録（note、無料）
記事5: エラーを「握りつぶす」コードの見抜き方 ― Python・TypeScript・Go・Rustで学ぶエラーハンドリング設計（Qiita、無料）
記事7: 78バグから導いた7つの設計原則（note、有料）

Skill作成ルート

Claude Code Skillを自分で作りたい方向けのルートです。

記事8: 78バグを6コマンドに変えた話 ― SFADの設計思想（note、有料）
記事9: Claude Code Skillの作り方完全ガイド（note、有料）

全記事一覧

記事	タイトル	掲載先	価格
記事1	AIと開発して78個のバグを踏んだので全部分類した	Qiita	無料
記事2	テスト不足18件から学んだこと ― Double-Loop TDDの考え方	Qiita	無料
記事3	AIに伝わる仕様書の書き方 ― Example Mappingで要件を構造化する	Qiita	無料
記事4	設計起因バグ23件の根本原因 ― Outside-In実装とは何か	Qiita	無料
記事5	エラーを「握りつぶす」コードの見抜き方 ― Python・TypeScript・Go・Rustで学ぶエラーハンドリング設計	Qiita	無料
記事6	既存コードをAIで解析する ― SFADのreverseコマンド実行記録	note	無料
記事7	78バグから導いた7つの設計原則	note	有料
記事8	78バグを6コマンドに変えた話 ― SFADの設計思想	note	有料
記事9	Claude Code Skillの作り方完全ガイド	note	有料
記事10	AI時代の開発ワークフロー実践ロードマップ	Qiita	無料

私が次にやること

SFADの改善

SFADは完成品ではありません。使うたびに「このPhaseはもっと細かく分けた方がいい」「このゲートは不要だった」という気づきがあります。ユーザーからのフィードバックを反映して、継続的に改善していきます。

他の開発手法のSkill化

SFADで「開発手法をSkill化する」という方法論が確立できたので、他のワークフローにも適用していきます。コードレビュー、デプロイメントチェックリスト、インシデント対応フロー。「毎回同じ手順でやるべきだけど、毎回微妙に違うことをしてしまう」作業を、Skillとして標準化していきます。

コミュニティ形成

1人で開発していると、自分の常識が世界の常識になります。「このSkillの設計どう思いますか」「こういうワークフローをSkill化したいんだけど」という相談ができる場所を作りたいと思っています。

締め

78個のバグは、最初は「恥ずかしい記録」でした。

分類したら「構造的な問題」が見えました。構造がわかったら「原則」にまとめられました。原則を「コマンド」にしたら、再現可能な仕組みになりました。

失敗 → データ → 原則 → ツール。

この流れは、どんな失敗にも適用できると思っています。

78個の失敗は、再現可能な仕組みになりました。あなたの現場にも、仕組みで解決できる問題があるはずです。

最初の一歩は、lint strictの設定ファイルを1つ追加することです。30分でできます。

この記事はSFAD（Spec-First AI Development）シリーズの最終回です。最後まで読んでいただきありがとうございました。

このシリーズの有料記事（7つの設計原則 / 6コマンド設計思想 / Skill作成ガイド）はnoteで公開しています。
→ https://note.com/because_and_so

SFADシリーズ全10本の一覧はこちら。
→ https://note.com/because_and_so/m/me824ba1a6796

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up