solo-scaffold

/scaffold

PRD とスタックテンプレートから、プロジェクト一式をスキャフォールドします。ディレクトリ構造、設定ファイル、CLAUDE.md、Git リポジトリを作成し、GitHub にプッシュします。SoloGraph で既存プロジェクトを調査してパターンの一貫性を保ち、Context7 で最新のライブラリバージョンを確認します。

手順

1. 引数を解析して、$ARGUMENTS から <project-name> と <stack-name> を抽出します。

   • 指定されていない、または不完全な場合は、AskUserQuestion を使って不足している値を確認します。
   • templates/stacks/*.yaml（信頼できる情報源）から利用可能なスタックを表示します。 MCP project_info が利用可能な場合は、アクティブなプロジェクトから検出されたスタックも表示します。 各 YAML の description フィールドにある 1 行の説明とともに、スタック名を一覧表示します。
   • プロジェクト名は kebab-case にします。

2. ~/.solo-factory/defaults.yaml から組織のデフォルト設定を読み込みます。

   • org_domain（例：com.mycompany）、apple_dev_team、github_org、projects_dir を読み込みます。
   • ファイルが存在しない場合は、AskUserQuestion で次の項目を確認します。
     • 「バンドル ID に使用する逆ドメイン形式のプレフィックスは何ですか？」（例：com.mycompany）
     • 「Apple Developer Team ID は何ですか？」（省略可。iOS を使用しない場合は空欄のままにします）
   • 今後の実行に備えて、回答を使って ~/.solo-factory/defaults.yaml を作成します。
   • 生成するすべてのファイル内の <org_domain>、<apple_dev_team>、<github_org> プレースホルダーを置き換えます。

3. スタック、PRD、原則を読み込みます。

   • プラグインのテンプレートから stacks/<stack>.yaml を検索して、スタック YAML を探します（kb_search または Glob を使用）。
   • スタック YAML が見つからない場合は、そのスタックに関する組み込み知識（パッケージ、構成、デプロイ）を使用します。
   • PRD が存在するか確認します。docs/prd.md を確認するか、現在のディレクトリで prd.md を検索します。
     • 存在しない場合は、基本的な PRD テンプレートを生成します。
   • 開発原則として dev-principles.md と dev-principles-my.md（個人向けの拡張）を探し、見つからない場合は組み込みの SOLID／DRY／KISS／TDD 原則を使用します。

4. SoloGraph で既存プロジェクトを調査します（重要：自分のコードベースから学びます）。

   コードを生成する前に、同じスタックを使用するアクティブなプロジェクトを調査します。そのままコピーしないでください。既存のプロジェクトには、レガシーなパターンや誤りが含まれている可能性があります。実際に役立つものを見極めます。

   a. 関連プロジェクトを探す — project_info() を使ってアクティブなプロジェクトを一覧表示し、スタックが一致するものを絞り込みます。 例：ios-swift の場合、同じスタックを使用する既存プロジェクトを探します。

   b. アーキテクチャの概要を確認する — 各関連プロジェクトに対して codegraph_explain(project="<sibling>") を実行します。 得られる情報：ディレクトリのレイヤー、主要なパターン（基底クラス、プロトコル、CRUD）、主な依存関係、ハブとなるファイル。

   c. 再利用可能なパターンを検索する — project_code_search(query="<pattern>", project="<sibling>") を実行します。

   • スタック固有のパターンを検索します：「MVVM ViewModel」、「SwiftData model」、「AVFoundation recording」
   • 共通インフラを検索します：「Makefile」、「project.yml」、「.swiftlint.yml」
   • サービスを検索します：「Service protocol」、「actor service」

   d. 共有パッケージを確認する — codegraph_query("MATCH (p:Project)-[:DEPENDS_ON]->(pkg:Package) WHERE p.name = '<sibling>' RETURN pkg.name") を実行します。 参考用にパッケージのバージョンを収集します（ただし、最新バージョンは Context7 で確認します）。

   e. 採用するパターンと採用しないパターンを慎重に評価します。

   • 採用： 一貫性のあるディレクトリ構造、Makefile のターゲット、設定パターン（.swiftlint.yml、project.yml）
   • 採用： 実績のあるインフラパターン（actor サービス、プロトコルベースの DIP）
   • 古くなっている場合は不採用： 古い API パターン（ObservableObject → @Observable）、非推奨の依存関係
   • 複雑すぎる場合は不採用： 不要な抽象化、新しいプロジェクトのニーズに合わないパターン
   • 必ず優先： 既存プロジェクトのパターンと競合する場合は、Context7 の最新のベストプラクティス

   目標： 生成されるコードは、自分のポートフォリオとの一貫性を保ちつつ、古いパターンを踏襲するのではなく、利用可能な最善のパターンを使います。 調査に集中できるよう、関連プロジェクトは 2〜3 件までにします。

5. Context7 での調査（最新のライブラリバージョンとベストプラクティス）：

   • スタック内の主要なパッケージごとに：
     • mcp__context7__resolve-library-id — Context7 のライブラリ ID を検索します
     • mcp__context7__query-docs — 「最新バージョン、プロジェクトのセットアップ、推奨されるファイル構成、ベストプラクティス」を検索します
   • 収集する情報：現行バージョン、推奨ディレクトリ構成、設定パターン、セットアップコマンド
   • 調査対象を絞るため、最も重要な 3〜4 個のパッケージに限定します

6. 計画を提示し、AskUserQuestion で確認を得る：

   • プロジェクトのパス：<projects_dir>/<name>（defaults.yaml または現在のディレクトリから取得）
   • スタック名と、Context7 で確認したバージョン付きの主要パッケージ
   • 提案するディレクトリ構成
   • ファイルを作成する前に、確認または調整してもらいます

7. プロジェクトディレクトリを作成する：

   mkdir -p <projects_dir>/<name>
   

8. スタックに基づいてファイル構成を作成する。SGR を優先し、ロジックやビューより先に、必ずドメインスキーマ／モデルから始めます。すべてのプロジェクトに、次の共通ファイルを作成します：

   <projects_dir>/<name>/
   ├── CLAUDE.md          # AI-friendly project docs (map, not manual — see Harness Engineering)
   ├── Makefile           # Common commands (run, test, build, lint, deploy, integration)
   ├── README.md          # Human-friendly project docs
   ├── docs/
   │   ├── prd.md         # Copy of PRD
   │   ├── QUALITY_SCORE.md  # Domain quality grades (harness: garbage collection)
   │   └── ARCHITECTURE.md   # Module boundaries and dependency rules
   ├── cli/               # CLI utility — mirrors core business logic (CLI-First Testing principle)
   │   └── main.ts|py     # Deterministic pipeline entry point (no LLM required)
   ├── .claude/
   │   └── skills/        # Product-specific workflow skills
   │       └── dev/
   │           └── SKILL.md  # Dev workflow skill (run, test, deploy)
   └── .gitignore         # Stack-specific ignores
   

   CLI 優先のテスト： lib/（または同等のディレクトリ）からコアビジネスロジックをインポートするスタブを含む cli/ ディレクトリを生成します。CLI は LLM、ネットワーク、UI を必要とせず、メインパイプラインを決定論的に実行できるようにします。これにより、make integration でパイプラインを検証できます。dev-principles.md → 「CLI 優先のテスト」を参照してください。

   .claude/skills/dev/SKILL.md — プロダクト開発ワークフローのスキル

   このプロジェクト固有の作業方法を Claude に教えるスキルを生成します。構成：

   ---
   name: <name>-dev
   description: Dev workflow for <Name> — run, test, build, deploy. Use when working on <Name> features, fixing bugs, or deploying changes. Do NOT use for other projects.
   license: MIT
   metadata:
     author: <github_org>
     version: "1.0.0"
   allowed-tools: Read, Grep, Glob, Bash, Write, Edit
   ---
   

   本文には次の内容を含めます：

   • スタック： 主要なパッケージ、バージョン、設定ファイルの場所
   • コマンド： make dev、make test、make build、make deploy（Makefile から）
   • アーキテクチャ： ディレクトリ構成、命名規則、主要なパターン
   • テスト： テストの実行方法、テストファイルの場所、テスト規約
   • 一般的なタスク： 新しいページ／画面の追加、API エンドポイントの追加、モデルの追加

   これにより、スキャフォールドされたすべてのプロジェクトをすぐに Claude 対応にできます。新しいセッションでは、このスキルを通じてプロジェクトのコンテキストを取得できます。

   MCP サーバー（任意）：PRD からデータ／AI／開発者向けのプロダクトだと判断できる場合は、MCP サーバーのスタブも生成します。 MCP を生成する条件を含む「MCP + Skills バンドル」のパターンとルールの詳細は、templates/mcp-skills-bundle.md を参照してください。

   次に、スタック固有のファイルを追加します。スタックごとのファイル一覧については、references/stack-structures.md を参照してください（8 つのスタック：nextjs、ios、kotlin、cloudflare、astro-static、astro-hybrid、python-api、python-ml）。

9. Makefile を生成する — スタックに合わせて、help、dev、test、lint、format、build、clean、deploy の各ターゲットを用意します。

   • プロジェクトに CLI または決定論的なパイプラインがある場合は、integration ターゲットを追加します（まだ実装されていない場合は、コメントを含むスタブにします）
   • ios-swift には、さらに次の項目を含める必要があります：generate（xcodegen）、archive（xcodebuild archive）、open（配布用に .xcarchive を開く）
   • Makefile は標準のコマンドインターフェースです。/build と /review は、生のコマンドではなく make ターゲットを使用します

10. 新しいプロジェクト用の CLAUDE.md を生成します（約100行、手動ではなくマップとして作成）：

• プロジェクトの概要（PRD の課題と解決策）
• 技術スタック（Context7 から取得したパッケージとバージョン）
• エージェントのデフォルト動作（Karpathy の原則）：
  • コーディングの前に考える：前提を明示し、混乱した場合は質問する
  • シンプルさを優先する：最小限のコードにし、推測に基づく抽象化はしない
  • 変更は必要な箇所だけにする：必要な部分だけを変更し、既存のスタイルに合わせる
  • 目標を重視する：指示を検証可能な成功基準に変換する
• スキルのセクション： 利用可能な .claude/skills/ を説明付きで列挙する
• ディレクトリ構成
• よく使うコマンド（make help を参照）
• 品質ゲート（タスクを完了する前に実施）：
  1. 「でたらめなものを作っていないか？」— 依頼内容を読み直す
  2. 「このコードはひどくないか？」— シニアエンジニアが受け入れる品質か？
  3. 「どうすれば最高のものにできるか？」— 誰もが見落としている洞察は何か？
• アーキテクチャ原則（dev-principles を参照。内容を直接記載しない）
• 禁止事項のセクション（プロジェクト固有の制約）
• 逸脱防止のセクション（アンチパターン：実行ではなくスケジュール設定、箇条書きではなくコード）
• MCP 連携のセクション（任意。MCP ツールが利用可能な場合）： 利用可能な MCP ツールを列挙します：project_code_search、kb_search、session_search、codegraph_query、project_info、web_search

11. README.md を生成します — プロジェクト名、説明、前提条件、セットアップ、実行／テスト／デプロイ。

12. .gitignore を生成します — 技術スタックに応じたパターンを記述します。

13. PRD を docs/ にコピー： ナレッジベースからコピーするか、その場で生成します。

14. Git を初期化して最初のコミットを作成：

    cd <projects_dir>/<name>
    git init && git add . && git commit -m "Initial project scaffold
    
    Stack: <stack-name>
    Generated by /scaffold"
    

15. GitHub のプライベートリポジトリを作成してプッシュ：

    cd <projects_dir>/<name>
    gh repo create <name> --private --source=. --push
    

16. プロジェクトを登録してコードをインデックス化します（任意。MCP ツールが利用可能な場合）：

    • project_code_reindex MCP ツールが利用可能な場合は、コード検索用に新しいプロジェクトをインデックス化します：

      mcp__solograph__project_code_reindex(project="<name>")
      

17. 概要を出力：

    プロジェクトのスキャフォールドが完了しました！
    
      Path:   <projects_dir>/<name>
      GitHub: https://github.com/<user>/<name>
      Stack:  <stack-name>
      PRD:    docs/prd.md
      CLAUDE: 設定済み
      Skills: .claude/skills/dev/（プロジェクトのワークフロー）
    
    次のステップ：
      cd <projects_dir>/<name>
      <install command>    # pnpm install / uv sync / など
      <run command>        # pnpm dev / uv run ... / など
    
    次に実行：/setup → /plan "First feature" → /build
    

検証

「プロジェクトのスキャフォールドが完了しました」と報告する前に、以下を実行します：

1. 生成されたすべてのファイルが存在することを確認します（ディレクトリツリーを ls で確認）。
2. インストールコマンド（pnpm install、uv sync など）を実行し、成功することを確認します。
3. 該当する場合は、dev／build コマンドを実行し、エラーが発生しないことを確認します。
4. git init と最初のコミットが成功したことを確認します（git log --oneline -1）。
5. GitHub リポジトリが作成されたことを確認します（gh repo view または URL を確認）。

インストールを実行して正常に動作することを確認せずに、「スキャフォールド完了」と言ってはいけません。

よくある問題

Stack YAML が見つからない

原因： スタックテンプレートが templates/stacks/ にないか、シンボリックリンクが設定されていません。 対処方法： テンプレートが見つからない場合、スキルは組み込みの知識を使用します。解決するには、solo-factory/templates/stacks/<stack>.yaml が存在することを確認します。

GitHub リポジトリの作成に失敗する

原因： gh CLI が認証されていないか、リポジトリ名がすでに使用されています。 対処方法： 先に gh auth login を実行します。名前が使用済みの場合は、別のプロジェクト名を選びます。

Context7 クエリに失敗する

原因： MCP サーバーが起動していないか、Context7 がレート制限されています。 対処方法： スキルは代替手段として、スタック YAML に記載されたバージョンを使用します。Context7 による補完は便利ですが、必須ではありません。

組織のデフォルト設定がない

原因： ~/.solo-factory/defaults.yaml が作成されていません。 対処方法： 一度だけセットアップするには、先に /init を実行します。実行しない場合、スキルがバンドル ID とチーム ID を対話形式で尋ねます。