1 なぜ3つの柱が必要なのか
AI バイブコーディングで発生する「4つの地獄」を事前に防ぐ
😵
読めない地獄
原因: 責務が混在し、関数名から処理内容が推測不能
対策: 柱① 設計 — 業務責務ベースの構成 + 命名規則
🔍
探せない地獄
原因: 変更の影響範囲が追えない、依存関係が暗黙的
対策: 柱①+② — 設計 + 明示的な依存・型ヒント
❓
正解がない地獄
原因: 仕様の基準がない、口頭変更が未反映
対策: 柱①+③ — 設計 + 仕様管理ルール
📅
最新がわからない地獄
原因: ブランチ・環境が乱立、基準が曖昧
対策: 柱③ 運用ルール — ブランチ戦略 + コミット規約
2 3つの柱
局所最適で進むと必ず破綻する。最初に3層をセットで固める
🏗️
柱① 設計
Architecture
- 業務責務ベースのディレクトリ構成
- オーケストレーション / ロジック / 副作用の分離
- 処理フローを先に整理してから実装
- 外部通信にエラーハンドリング + リトライ
📝
柱② 実装ルール
Implementation Rules
- 動詞+目的語の明確な命名
**kwargs / *_fn 引き回し禁止- マジックナンバーは config/constants へ
- 型ヒント / JSDoc 必須
⚙️
柱③ 運用ルール
Operation Rules
- main / staging / dev ブランチ戦略
- Conventional Commits (feat / fix / refactor)
- 1コミット1意図、混在禁止
- 仕様変更は docs/specs/ に記録
3 コマンド一覧と実行タイミング
開発フローに沿った4つのカスタムコマンド
/init-project
開始時に1回
対話ヒアリング
→ CLAUDE.md
→ ディレクトリ構成
→ 定数・仕様テンプレート
→ フロー図
/add-feature
機能追加のたびに
設計ファースト
7フェーズ強制
責務→フロー→仕様
→IF→実装→テスト
→コミット
/design-review
定期 or PR前
9項目スキャン
CRITICAL /
WARNING / INFO
で分類レポート
/smart-commit
コミットのたびに
変更自動分析
Conventional Commits
混在検出 + 分割提案
4 /add-feature の7フェーズ
コードを書く前に設計を強制。各フェーズでユーザー承認を挟む
5 /design-review の9チェック項目
3つの柱それぞれに対応する検査項目
柱① 設計
1. ディレクトリ構成
utils/ にドメイン処理が混入していないか
柱① 設計
2. 責務分離
1関数が複数責務を担っていないか
柱① 設計
3. フロー設計
docs/flows/ にフロー図が存在するか
柱② 実装
4. 命名規則
handle_* / process_* 等の曖昧な命名
柱② 実装
5. 引数・依存
**kwargs / *_fn の暗黙的依存注入
柱② 実装
6. データの扱い
マジックナンバー / マジックストリング
柱② 実装
7. コード品質
型ヒント欠落 / console.log残留
柱③ 運用
8. 仕様管理
docs/specs/ に仕様書が存在するか
柱③ 運用
9. コミット品質
Conventional Commits / 意図の混在
6 /smart-commit のフロー
変更内容を自動分析し、混在を検出して安全にコミット
STEP 1
変更分析
git diff / status
▶
STEP 2
分類
feat / fix / refactor...
▶
STEP 3
混在検出
feat+refactor?
▶
STEP 4
メッセージ生成
Conventional Commits
▶
STEP 5
コミット
stage + commit
feat:
fix:
refactor:
docs:
test:
chore:
⚠️ 混在検出の例
feat + refactor が混在しています
① feat: FIMスコア計算ロジック追加
src/services/analysis/fim_calculator.py (新規)
② refactor: データパイプラインのリネーム
src/services/data_pipeline/loader.py (変更)
→ 分割コミットを提案: まず ② → 次に ①
7 project-architect スキル
バックグラウンドで常駐し、4つのトリガーで自動ガイド
🤖 project-architect（自動適用）
📁
新ファイル作成時
配置先ディレクトリの妥当性を判定。utils/ にドメイン処理を置こうとしたら警告
🏷️
新しい関数・クラス定義時
命名規則チェック。handle_* → 具体的な動詞+目的語を提案
🔄
ディレクトリ構成変更時
業務責務ベースの構成に準拠しているか確認
🌐
外部通信の実装時
エラーハンドリング・リトライ・タイムアウト設定の有無を確認
8 生成されるファイル構成
/init-project 実行後に自動生成されるプロジェクト構造
~/.claude/
├── commands/
│ ├── init-project.md
│ ├── add-feature.md
│ ├── design-review.md
│ └── smart-commit.md
└── skills/
└── project-architect/
└── SKILL.md
C:\Users\kawag\work\<project>/
├── CLAUDE.md
├── src/
│ ├── services/
│ │ ├── <domain_1>/
│ │ ├── <domain_2>/
│ │ └── <domain_3>/
│ ├── utils/
│ └── config/
│ └── constants.*
├── tests/
├── docs/
│ ├── specs/
│ └── flows/
└── .gitignore