🎯 壁打ちをスキップすると、AI はハルシネーションで埋める
ステアリング駆動開発の入口は 壁打ち です。ここを飛ばすと、AI は「なぜその作業が必要か」を推測で埋め始めます。結果、見た目は正しいが目的を外したコードが量産されます。
壁打ちは「5 観点で認識を揃え、規模を判定し、オーナーが承認する」3 つの工程に分解できます。本記事ではシリーズ第 2 回として、このファーストステップを .claude/skills/brainstorming/ の運用例で解説します。
🧠 壁打ちには「業務理解 × 開発手法」両輪のスキルが必要
壁打ちの 5 観点は、表面的には質問項目に見えますが、質の高い壁打ちを成立させるには 業務理解と開発手法の両輪 が必要です。ここを正直に共有しておきます。
壁打ちで動員されるスキル
| 領域 | 具体例 | なぜ必要か |
|---|---|---|
| 業務理解 | 業務フロー、関係者の責務、KPI、現場の運用ルール | 背景・目的・スコープを「現場の言葉」で語るため |
| ドメインモデリング | DDD / Bounded Context / ユビキタス言語 / 集約 | 業務を AI が扱える構造に翻訳するため |
| アーキテクチャ素養 | オブジェクト指向 / SOLID / 階層分離 | 既存資産観点で「流用可能性」を判断するため |
| 代替案の引き出し | 設計パターン・他社事例・OSS 動向 | 代替案観点で「比較する選択肢」を出すため |
正直に言うと、AI 駆動開発のハードルは高い
これまで 「仕様書通りにコーディングする」 ことが主な業務だったエンジニアにとって、AI 駆動開発はハードルが急に上がります。なぜなら、AI 駆動開発で求められるのは 「要件定義を一人で進められる責務」 に近いからです。
「何を作るか」を曖昧にしたまま実装に入ると、AI は推測でコードを量産し、品質判断不能な状態になります。 要件定義 = 開発そのもの という原則の意味は、ここに表れます。
具体的に必要となる力：
- 業務担当者と 「業務の言葉」で会話して、ユビキタス言語を引き出せる
- 既存システムを 読み、流用判断ができる
- 設計原則・パターンを チェックリストとして持っている
- 採用しなかった代替案を 「なぜ選ばなかったか」で語れる
これらは一朝一夕には身につきません。 これまでの開発スタイルでは出番が少なかった筋肉 を新たに鍛える必要があります。
でも、ここで「自分には無理」と判断する必要はない
ハードルは高い。けれど、 道筋はあります 。本ナレッジベースを段階的な学習パスとして使ってください。
| ステップ | やること | 参照記事 |
|---|---|---|
| 1. 地図を持つ | 開発手法の全体像を頭に入れる | 開発手法ガイド：概要 |
| 2. ドメイン言語を養う | DDD・集約・Bounded Context の感覚を掴む | DDD 編 |
| 3. レビュー観点を装備 | SOLID をチェックリスト化 | SOLID 編 |
| 4. 検証習慣を作る | TDD で AI 出力を即座に判定 | TDD 編 |
| 5. 小規模で壁打ちを試す | S 規模で壁打ちの型を覚える | 本記事 + 概要編 |
| 6. M / L 規模に挑戦 | 業務担当者と一緒に進める | ステアリング作成編 |
いきなり本番の L 規模を一人で抱えない — これが安全な始め方です。まずは S 規模で壁打ちのフォーマットに慣れ、徐々に複雑度を上げていくと、業務理解と開発手法の両輪を実戦で鍛えられます。
💡 チームで導入する場合: 「業務知識が厚いメンバー」と「開発手法が厚いメンバー」のペアで壁打ちを進めると、片側だけのチームより圧倒的に質が上がります。一人で両輪を完璧にする必要はありません。 チームのスキルセットを補完し合う設計 が、AI 駆動開発を本番投入する現実解です。
🗣️ 壁打ちは 5 観点で進める
CTS-EC では壁打ちを 5 観点で定型化しています。1 つでも欠けたら Step 1（規模判定）に進みません。
| # | 観点 | 代表的な問い |
|---|---|---|
| 1 | 背景（Why now?） | なぜ「今」必要か？やらないと何が起きるか？ |
| 2 | 目的（What success?） | 何を達成したら成功か？定量/定性の指標は？ |
| 3 | スコープ（What’s in/out?） | In Scope / Out of Scope を明示する |
| 4 | 既存資産（What exists?） | 参照可能な既存実装・仕様・過去ステアリングは？ |
| 5 | 代替案（What else?） | 別アプローチ、トレードオフ、判断を覆す条件 |
🔍 既存資産は「ツール検索必須」
「既存資産」観点では 必ず Grep / Glob / Read を実行 します。記憶ベースで「特になし」と回答するのは禁止です。
Grep "OAuth" dotnet/src/ # 既存実装
Glob "**/Auth*.cs" # 類似ファイル
Read docs/glossary.md # 関連用語
ls .steering/archive/ # 過去ステアリング結果は brainstorm.md の §4 に表で残します。
| 種別 | 参照先 | 流用可能性 |
|---|---|---|
| 既存実装 | dotnet/src/.../AuthService.cs | パターン踏襲 |
| 仕様書 | docs/specs/auth-design.md | 関連 |
| 過去ステアリング | archive/20260301-oauth-v1/ | テスト構造を流用 |
この表があることで、/steering-complete 時に ADR 昇華の判断材料にもなります。
📊 S / M / L 規模判定
壁打ち完了後、AI が規模を 推奨 します。オーナーが最終判断します。
| 規模 | 条件 | ステアリング | ファイル数 |
|---|---|---|---|
| S | バグ修正、軽微な変更、設定変更 | 不要 | 0 |
| M | 単機能追加、リファクタ、単一ドメイン変更 | 必須 | 4 |
| L | 複数機能、アーキテクチャ変更、複数ドメイン連携、新規用語導入 | 必須 | 8 |
「全タスクに L 規模を適用する」のは過剰 です。バグ修正に 8 ファイルの仕様書は書きません。逆に新ドメイン追加を M 規模で済ませると、architecture.md / glossary.md の欠落で後から設計崩壊が起きます。
🚨 L 規模のシグナル（チェックリスト）
以下のいずれかに該当すれば L 規模を推奨します。
- 複数の Bounded Context にまたがる
- 新しいエンティティ・集約を導入する
- 既存アーキテクチャの変更を伴う
- 新しい用語（ユビキタス言語）を導入する
- 3 つ以上のフェーズに分かれる
- 複数の外部サービス連携がある
CTS-EC では「共通ブランドマスタ導入」「3 段階カテゴリマッピング」「Saga パターン標準化」などが L 規模でした。いずれも新用語 + 複数コンテキスト + 新規アーキテクチャの 3 条件を満たしています。
✍️ brainstorm.md のフォーマット
壁打ちの結果は .steering/[YYYYMMDD]-[タイトル]/brainstorm.md に保存します。ステアリング固有の作業メモで、揮発可です。
# 壁打ち: Yahoo OAuth 実装
**日付**: 2026-04-20
**ステータス**: 検討中 → 承認済み
## 1. 背景
- ショッピング ID 認証の EOL が 2026-06 → OAuth 移行必須
## 2. 目的
- 全店舗の OAuth 移行完了
- **成功指標**: 未移行店舗 0 / トークン失効エラー率 < 0.1%
## 3. スコープ
### In Scope
- Yahoo OAuth トークン取得・保存・リフレッシュ
### Out of Scope
- 楽天・Amazon の認証（別ステアリングで対応）
## 4. 既存資産
| 種別 | 参照先 | 流用可能性 |
| --- | --- | --- |
| 既存実装 | `dotnet/src/.../CognitoAuth.cs` | 近似パターン |
## 5. 代替案
| 案 | メリット | デメリット | 採否 |
| --- | --- | --- | --- |
| A: 自前実装 | 制御しやすい | 保守負担大 | ❌ |
| B: IdentityServer 委譲 | 実績あり | 学習コスト | ✅ 採用 |
## オーナー承認
- [x] 承認日: 2026-04-20
- [x] 規模判定: L
## 再利用可能な判断（ADR 昇華候補）
- [ ] OAuth ライブラリ選定ポリシー（ADR 昇華候補）
- [ ] トークン保管場所の命名規則（ADR 昇華候補）🏛️ ADR 昇華の基準
brainstorm.md の「ADR 昇華候補」セクションから、プロジェクト全体に永続化すべき判断のみ を docs/adr/adr-NNN.md に手動で昇華します（/steering-complete 実行時）。
| 昇華する | 昇華しない |
|---|---|
| 設計原則・命名規則の決定 | タスク固有の実装詳細 |
| アーキテクチャパターンの選定 | 一時的な判断 |
| 採用しなかった代替案の記録 | 単純な作業手順 |
| プロジェクト全体に影響する制約 | レビュー指摘の対応履歴 |
2 段構成にすることで「壁打ちの作業メモ」と「再利用可能な決定」を分離管理できます。ADR に一時的な判断が混ざると、後から読み返したときに重要度が判別できなくなるため、昇華判断を意識的に行うことが重要です。
🧭 オーナー承認の文面テンプレート
壁打ち + 規模判定が揃ったら、次の文面でオーナーに投げます。
★ 壁打ち・規模判定レビュー ★
1. 壁打ちドキュメント: .steering/20260420-yahoo-oauth/brainstorm.md
2. 推奨規模: L
3. 理由: 新規 Bounded Context「認証連携」を導入、
Yahoo API 依存追加、トークン管理の新規用語あり
ご確認ください：
- 承認（規模も含めて）
- 規模変更（L→M など）
- 壁打ち修正（追加議論が必要）承認が取れた時点で Step 3（ステアリング作成）に進めます。承認前に実装・Git コミットに進むのは禁止です。
⚠️ 壁打ちフェーズでやってはいけないこと
- 5 観点のうち 1 つでもスキップしてステアリング作成に進む
- 「既存資産」観点でツール検索なしに「特になし」と回答する
- brainstorm.md を作成せずに直接 ADR を書く
- ユーザー対話なしに、記憶ベースで問いを埋める
- オーナー承認前に規模を AI 側で確定する
📚 シリーズ記事
| # | タイトル | 内容 |
|---|---|---|
| 1 | 概要 | ステアリング駆動開発の全体像 |
| 2 | 壁打ち・規模判定編（本記事） | 壁打ちの進め方、ADR の書き方、規模判定の基準 |
| 3 | ステアリング作成編 | M/L 規模のドキュメント作成、TDD タスク分解 |
| 4 | 実装・完了編 | TodoWrite 連携、進捗管理、アーカイブ運用 |
| 5 | コンテキスト設計編 | AI に渡すコンテキストの最適化、skills 設計 |
| 6 | 品質ゲート編 | doc-reviewer、テスト品質チェック、受入テスト |
| 7 | Claude Code ベストプラクティス | CLAUDE.md 設計、hooks、commands、rules、skills |
| 8 | Agent Teams 編 | agents 定義、チーム構成、マルチエージェント協調 |
| 9 | Remote Control 編 | スマホ・Web から CLI セッションを操る席拘束からの解放 |
🔗 関連記事
- ステアリング駆動開発とは：概要 — シリーズ全体の導入
- Claude Code 7層ハーネスエンジニアリング — 品質ゲート層の詳細
📖 関連用語
- ADR — brainstorm.md から昇華する設計判断記録
- ビジネスケイパビリティ — 壁打ちでスコープを業務側の言葉で語る前提概念
- MVP — In Scope / Out of Scope を絞るスコープ設計の考え方
- ハルシネーション — 壁打ちで抑制する典型的な失敗モード