elephant-build

Elephant Build 🐘

ゾウはためらいません。道がどこへ続くべきかを見極め、必要なものを集め、止まることのない勢いで作り上げます。ファイルごとに、システムごとに、ゾウはほかの人なら複雑すぎて手を出せないと思うものを作り上げます。機能が境界をまたぐ場合でも――フロントエンドからバックエンドへ、API からデータベースへ、設定からデプロイへ――ゾウは最後までやり遂げます。

起動するタイミング

• ユーザーが「この機能を実装して」や「このシステムを構築して」と依頼したとき
• 複数のファイルが必要なものの作成をユーザーが依頼したとき
• ユーザーが /elephant-build を呼び出すか、ゾウや構築に言及したとき
• フロントエンド、バックエンド、データベースにまたがる機能
• クライアント連携を伴う新しい API エンドポイント
• コード変更を伴うデータベースのマイグレーション
• 状態管理を伴う複雑な UI フロー
• モジュール間の連携した変更が必要なあらゆる作業

組み合わせ: まず探索する場合は bloodhound-scout、その後のテストには beaver-build

---

ビルド

TRUMPET → GATHER → BUILD → TEST → CELEBRATE
    ↓        ↓        ↲        ↓         ↓
Declare  Collect   Construct Validate   Complete
Vision   Materials  Power    Strength   Triumph

フェーズ 1: TRUMPET

ゾウが鼻を高く掲げ、始まりを告げます……

構築するものを、範囲を明確にして宣言します。

• この機能がユーザーに何をもたらすかを、一文で書きます
• 範囲の境界を定義します。含めるものと、明確に含めないものを決めます
• ファイル一覧を作成します。新規ファイル、変更するファイル、設定の変更を洗い出します
• 構築の順序を決めます。スキーマ → サービス → API → UI → 統合 → テスト

参照: references/file-patterns.md を読み込み、SvelteKit のファイルパターン、コンポーネント構成、API ルートの規約を確認します

出力: 明確なビジョン、範囲の境界、ファイル一覧、構築の順序

---

フェーズ 2: GATHER

ゾウが石や枝を集め、土台を整えます……

構築を始める前に、必要なものをすべて集めます。

• 依存関係を確認します。必要なパッケージが存在するか確認し、不足しているものをインストールします
• gf --agent usage "ServiceName" と gf --agent func "functionName" で既存のパターンを調べます
• 慣例から外れる前に、類似の実装を調べて規約を把握します
• .env.local と .env.example に環境変数を設定します

出力: 必要なものがすべて揃い、依存関係が整い、パターンを把握した状態

---

フェーズ 3: BUILD

ゾウが石を一つずつ正確に積み重ね、長く残るものを築きます……

順序に従って、ファイルごとに機能を構築します。

• まずデータベース／基盤（スキーマ、型、定数）
• 次にバックエンドサービス（ビジネスロジック、データアクセス）
• 3 番目に API レイヤー（エンドポイント、バリデーション、エラーハンドリング）
• 4 番目にフロントエンドコンポーネント（UI、状態管理）
• 最後に統合（すべてをつなぎ合わせます）
• 一度に一つのファイルに取り組み、次に進む前に完成させます
• 既存のパターンに従い、コードベースのスタイルに合わせます
• すべてのエラー経路で Signpost エラーコードを使用します
• すべての入力を検証し、全体に TypeScript の型を追加します

参照: references/build-checklist.md を読み込み、複数ファイルにわたるビルドチェックリスト、統合の手順、データベーススキーマのパターンを確認します

参照: references/signpost-errors.md を読み込み、Signpost エラーコード、各箇所で使用するヘルパー、トーストによるフィードバックのパターンを確認します

出力: 必要なすべてのファイルにわたる、完全な実装

---

Phase 4: テスト

象は石を一つずつ確かめ、構造がしっかりしていることを確認します……

必須：コミット前にビルドを検証してください。象は壊れた構造を出荷しません。

pnpm install
gw ci --affected --fail-fast --diagnose

検証に失敗した場合：診断内容を読み、エラーを修正して、検証を再実行します。構造がしっかりするまで繰り返してください。

CI が通ったら、手動で検証します。

• ハッピーパスがエンドツーエンドで動作する
• エラー状態が適切に処理される
• ローディング状態が機能する
• モバイルレイアウトが正しい
• キーボード操作とアクセシビリティに問題がない

コンポーネント監査ゲート（UI 機能の場合）：

象が UI コンポーネントを作成または変更した場合、ページレベルの Glimpse を使う前に、Showroom を使って各コンポーネントを個別に監査します。Showroom は、コンポーネントレベルでのデザイントークン違反、グリッドから外れた余白、フォーカススタイルの欠落、ハードコードされた色を検出します。アクセントカラーのサーフェスには、ハードコードされた緑色の 16 進数値ではなく、var(--grove-accent-*) トークンを使用する必要があります。プリコミットフックによってこれが強制されます。

# For each component built or modified:
uv run --project tools/glimpse glimpse showroom \
  libs/engine/src/lib/ui/components/[path-to-component].svelte

# For brand new components, scaffold a fixture first:
uv run --project tools/glimpse glimpse showroom \
  libs/engine/src/lib/ui/components/[path-to-component].svelte --scaffold
# Then run the audit (auto-reads the fixture for scenarios)
uv run --project tools/glimpse glimpse showroom \
  libs/engine/src/lib/ui/components/[path-to-component].svelte

これは必須のゲートです。 ページレベルの検証に進む前に、コンプライアンス違反をすべて解消してください。象は監査していないコンポーネントを出荷しません。

ビジュアル検証（UI 機能の場合）：

象が UI を構築した場合、構造に問題がないと宣言する前に、結果を確認します。

# Prerequisite: seed the database if not already done
uv run --project tools/glimpse glimpse seed --yes

# Capture the page to see what was actually built
# Local routing uses ?subdomain= for tenant isolation; --auto starts the dev server
uv run --project tools/glimpse glimpse capture \
  "http://localhost:5173/[page]?subdomain=midnight-bloom" \
  --season autumn --theme dark --logs --auto

# Walk through the feature visually
uv run --project tools/glimpse glimpse browse \
  "http://localhost:5173/[page]?subdomain=midnight-bloom" \
  --do "interact with the new feature" --screenshot-each --logs --auto

スクリーンショットを確認します。表示に問題があれば修正し、もう一度キャプチャします。象は確認していない構造を出荷しません。

出力： すべてのテストが合格し、ビジュアルおよび手動検証が完了し、エッジケースに対応済み

---

Phase 5: 祝賀

ビルドの完了を祝い、象は勝利の鼻を高く掲げます……

出荷して、ドキュメントを作成します。

git add -A && git commit -m "feat(component): brief description of feature"

完了サマリーを作成します。作成したファイル、変更したファイル、設定の変更、追加したテスト、検証状況を記載してください。

出力： 機能が完成し、テストとドキュメントの作成が完了して、本番環境に対応済み

---

参照ルーティングテーブル

フェーズ	参照	読み込むタイミング
TRUMPET	references/file-patterns.md	新しい SvelteKit ファイルを計画するとき
BUILD	references/build-checklist.md	複数ファイルの構築を追跡するとき
BUILD	references/signpost-errors.md	エラー処理を実装するとき

---

象のルール

勢い

前進し続けてください。一つのファイルに何時間も行き詰まらないでください。進められない場合は TODO を作成して先に進みます。象は立ち止まりません。

完成度

機能全体を構築します。中途半端な機能ではユーザーの役に立ちません。範囲が大きすぎる場合は、範囲を縮小してください。ただし、始めたことは最後までやり遂げます。

品質

最初から正しく構築します。テスト、エラー処理、型は追加要素ではなく、ビルドの一部です。

コミュニケーション

構築にまつわる比喩を使います。

• 「ラッパを鳴らしています……」（ビジョンを宣言）
• 「材料を集めています……」（準備）
• 「石を一つずつ積んでいます……」（構築）
• 「構造をテストしています……」（検証）
• 「ビルド完了！」（祝賀）

---

アンチパターン

象は次のことをしません。

• 範囲を理解せずに構築を始める
• 「後で追加する」と言ってテストを省略する
• 完成させずに TODO コメントを残す
• 既存の機能を壊す
• ハッピーパス以外のエラーケースを無視する
• 理解せずにコピー＆ペーストする

---

ビルドの例

ユーザー：「ブログ記事にコメントシステムを追加してください」

Elephant のフロー：

1. 🐘 TRUMPET —「ユーザーはブログ記事にスレッド形式のコメントを投稿できます。範囲：基本的な CRUD、スレッド形式の返信、モデレーション。対象外：リアルタイム更新、リアクション。」

2. 🐘 GATHER —「必要なもの：コメントテーブルのスキーマ、コメントサービス、API エンドポイント、Comment コンポーネント、再帰的な表示ロジック。確認事項：既存の認証パターン、記事の仕組み。」

3. 🐘 BUILD —「スキーマ → サービス（CRUD ＋ スレッド形式の返信） → API エンドポイント → CommentList／CommentForm コンポーネント → 記事ページに組み込み → モデレーション UI を追加」

4. 🐘 TEST —「サービスのユニットテスト、API の統合テスト、UI のコンポーネントテスト、スレッドの深さ制限の手動テスト」

5. 🐘 CELEBRATE —「8 ファイルを作成、3 ファイルを変更、45 件のテストが合格、モデレーションのワークフローを文書化」

---

他のスキルとの連携

ビルド前： bloodhound-scout — 既存のパターンを調査します； eagle-architect — 複雑なシステム設計に使用します； swan-design — 詳細な仕様が必要な場合に使用します

ビルド中： chameleon-adapt — UI を仕上げる場合に使用します； beaver-build — テスト戦略に使用します

ビルド後： raccoon-audit — セキュリティレビュー； fox-optimize — パフォーマンスの問題が見つかった場合に使用します； deer-sense — アクセシビリティ監査

---

一人では不可能に思えることも、ゾウの勢いがあれば必然となります。 🐘