spec-to-repo

Spec to Repo

自然言語で書かれたプロジェクト仕様を、完全に実行可能なスターターリポジトリに変換します。単なるテンプレートへの入力ではなく、あらゆるスタックで実際に動作するコードを生成する仕様インタープリターです。

使用する場面

• ユーザーがアプリの説明文を提示し、コードを求めている
• ユーザーが PRD、要件定義書、機能一覧を持っており、コードベースを必要としている
• ユーザーが「〜するアプリを作って」「これをスキャフォールドして」「プロジェクトをブートストラップして」と言っている
• ユーザーがファイルツリーだけでなく、動作するスターターリポジトリを求めている

このスキルを使わない場合：ユーザーが特に Stripe + Auth を備えた SaaS アプリを求めている場合は、代わりに product-team/saas-scaffolder を使用してください。

基本ワークフロー

フェーズ 1 — 解析と解釈

仕様を読みます。以下の項目を内部で抽出します。

項目	情報源	必須
アプリ名	明示されているもの、または説明から推測	はい
説明	仕様の最初の文	はい
機能	動作を説明する箇条書きや文	はい
技術スタック	「FastAPI を使う」などの明示、または文脈から推測	はい
認証	「ログイン」「ユーザー」「アカウント」「ロール」	言及がある場合
データベース	「保存」「永続化」「レコード」「スキーマ」	言及がある場合
API サーフェス	「エンドポイント」「API」「REST」「GraphQL」	言及がある場合
デプロイ先	「Vercel」「Docker」「AWS」「Railway」	言及がある場合

スタック推測ルール（ユーザーが指定していない場合）：

手がかり	推測するスタック
「ウェブアプリ」「ダッシュボード」「SaaS」	Next.js + TypeScript
「API」「バックエンド」「マイクロサービス」	FastAPI（Python）または Express（Node）
「モバイルアプリ」	Flutter または React Native
「CLI ツール」	Go または Python
「データパイプライン」	Python
「高パフォーマンス」「システム」	Rust または Go

解析後、構造化した解釈をユーザーに提示します。

## Spec Interpretation

**App:** [name]
**Stack:** [framework + language]
**Features:**
1. [feature]
2. [feature]

**Database:** [yes/no — engine]
**Auth:** [yes/no — method]
**Deploy:** [target]

Does this match your intent? Any corrections before I generate?

曖昧な点を示します。確認の質問は最大 3 つまでにします。ユーザーが「とにかく作って」と言った場合は、妥当な推測に基づくデフォルト設定で進めます。

フェーズ 2 — アーキテクチャ設計

ファイルを書き始める前に、プロジェクトを設計します。

1. テンプレートを選択 — references/stack-templates.md からスタックに合うテンプレートを選びます
2. ファイルツリーを定義 — 作成するすべてのファイルを列挙します
3. 機能をファイルに割り当て — 各機能に、少なくとも 1 つのファイルまたはコンポーネントを割り当てます
4. データベーススキーマを設計 — 該当する場合、フィールドと型を含むテーブルまたはコレクションを定義します
5. 依存関係を特定 — バージョン制約とともに、すべてのパッケージを列挙します
6. API ルートを計画 — 該当する場合、メソッド、パス、リクエスト／レスポンスの形式とともに、すべてのエンドポイントを列挙します

生成を始める前に、ファイルツリーをユーザーに提示します。

project-name/
├── README.md
├── .env.example
├── .gitignore
├── .github/workflows/ci.yml
├── package.json / requirements.txt / go.mod
├── src/
│   ├── ...
├── tests/
│   ├── ...
└── ...

フェーズ 3 — 生成

すべてのファイルを書きます。ルール：

• スタブではなく、実際のコードを記述します。 すべての関数に実際の実装を含めます。// TODO: implement や pass のようなプレースホルダーは使いません。
• 構文的に有効であること。 すべてのファイルが、それぞれの言語でエラーなく解析できる必要があります。
• インポートと依存関係を一致させます。 すべてのインポートが、マニフェスト（package.json、requirements.txt、go.mod など）に含まれるパッケージに対応している必要があります。
• 型を含めます。 TypeScript プロジェクトでは型を使います。Python プロジェクトでは型ヒントを使います。Go プロジェクトでは型付き構造体を使います。
• 環境変数。 必須の変数をすべて含め、用途をコメントに記載した .env.example を生成します。
• README.md。 プロジェクトの説明、前提条件、セットアップ手順（クローン、インストール、環境の設定、実行）、利用可能なスクリプト／コマンドを含めます。
• CI 設定。 インストール、リンターが依存関係に含まれる場合は lint、テスト、ビルドを含む .github/workflows/ci.yml を生成します。
• .gitignore。 スタックに適した除外設定（node_modules、pycache、.env、ビルド成果物）を含めます。

ファイルの生成順序：

1. マニフェスト（package.json / requirements.txt / go.mod）
2. 設定ファイル（.env.example、.gitignore、CI）
3. データベーススキーマ／マイグレーション
4. コアビジネスロジック
5. API ルート／エンドポイント
6. UI コンポーネント（該当する場合）
7. テスト
8. README.md

フェーズ 4 — 検証

生成後、次のチェックリストに沿って確認します。

• インポートされたすべてのパッケージがマニフェストに存在する
• インポートから参照されるすべてのファイルがツリー内に存在する
• .env.example にコードで使用されるすべての環境変数が記載されている
• .gitignore がビルド成果物とシークレットを対象にしている
• README に実際に機能するセットアップ手順が記載されている
• ハードコードされたシークレット、API キー、パスワードがない
• テストファイルが少なくとも 1 つ存在する
• ビルド／起動コマンドが記載されており、実行できる

生成されたディレクトリに対して scripts/validate_project.py を実行し、よくある問題を検出します。

例

例 1：タスク管理 API

入力仕様：

「タスク管理 API を作ってください。ユーザーはタスクを作成、一覧表示、更新、削除できます。タスクにはタイトル、説明、ステータス（todo／in-progress／done）、期限があります。SQLite を使った FastAPI を使用してください。API キーによる基本認証を追加してください。」

出力ファイルツリー：

task-api/
├── README.md
├── .env.example              # API_KEY, DATABASE_URL
├── .gitignore
├── .github/workflows/ci.yml
├── requirements.txt          # fastapi, uvicorn, sqlalchemy, pytest
├── main.py                   # FastAPI app, CORS, lifespan
├── models.py                 # SQLAlchemy Task model
├── schemas.py                # Pydantic request/response schemas
├── database.py               # SQLite engine + session
├── auth.py                   # API key middleware
├── routers/
│   └── tasks.py              # CRUD endpoints
└── tests/
    └── test_tasks.py         # Smoke tests for each endpoint

例 2：レシピ共有 Web アプリ

入力仕様：

「レシピ共有サイトを作りたいです。ユーザーは登録して、材料や手順を含むレシピを投稿し、ほかのレシピを閲覧して、お気に入りを保存します。Tailwind を使った Next.js を使用してください。データは PostgreSQL に保存してください。」

出力ファイルツリー：

recipe-share/
├── README.md
├── .env.example              # DATABASE_URL, NEXTAUTH_SECRET, NEXTAUTH_URL
├── .gitignore
├── .github/workflows/ci.yml
├── package.json              # next, react, tailwindcss, prisma, next-auth
├── tailwind.config.ts
├── tsconfig.json
├── next.config.ts
├── prisma/
│   └── schema.prisma         # User, Recipe, Ingredient, Favorite models
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx          # Homepage — recipe feed
│   │   ├── recipes/
│   │   │   ├── page.tsx      # Browse recipes
│   │   │   ├── [id]/page.tsx # Recipe detail
│   │   │   └── new/page.tsx  # Create recipe form
│   │   └── api/
│   │       ├── auth/[...nextauth]/route.ts
│   │       └── recipes/route.ts
│   ├── components/
│   │   ├── RecipeCard.tsx
│   │   ├── RecipeForm.tsx
│   │   └── Navbar.tsx
│   └── lib/
│       ├── prisma.ts
│       └── auth.ts
└── tests/
    └── recipes.test.ts

例 3：CLI 支出管理ツール

入力仕様：

「支出を管理する Python CLI ツール。コマンド：add、list、summary、export-csv。ローカルの SQLite ファイルに保存します。外部 API は使用しません。」

出力ファイルツリー：

expense-tracker/
├── README.md
├── .gitignore
├── .github/workflows/ci.yml
├── pyproject.toml
├── src/
│   └── expense_tracker/
│       ├── __init__.py
│       ├── cli.py            # argparse commands
│       ├── database.py       # SQLite operations
│       ├── models.py         # Expense dataclass
│       └── formatters.py     # Table + CSV output
└── tests/
    └── test_cli.py

アンチパターン

アンチパターン	対策
プレースホルダーコード — // TODO: implement、pass、空の関数本体	すべての関数に実際の実装を用意します。複雑な場合は、動作する簡易版を実装します。
スタックの上書き — ユーザーが Flask と指定したのに Next.js を選ぶ	明示された技術の希望には必ず従います。ユーザーが指定していない場合に限り推測します。
.gitignore がない — node_modules や .env をコミットする	最初に作成するファイルの一つとして、スタックに適した .gitignore を生成します。
存在しないインポート — マニフェストにないパッケージをインポートする	完了前に、すべてのインポートを package.json／requirements.txt と照合します。
MVP の過剰な設計 — v1 に Redis キャッシュ、レート制限、WebSocket を追加する	動作する最小限のものを作ります。ユーザーは後から反復できます。
明示された希望を無視する — ユーザーが「PostgreSQL」と指定したのに MongoDB を生成する	仕様を注意深く読み取ります。明示された希望は必ず守ります。
環境変数の記載漏れ — コードが process.env.X を読み取るのに、.env.example に記載されていない	コードで使用するすべての環境変数を、コメントとともに .env.example に記載します。
テストがない — テストファイルが 1 つもないリポジトリを提供する	最低でも API エンドポイントごとに 1 つのスモークテスト、または主要な関数ごとに 1 つのテストを用意します。
API の幻覚 — 存在しないライブラリメソッドを呼び出すコードを生成する	ドキュメントが充実した安定した API を使用します。不確かな場合は、最も簡単な方法を選びます。

検証スクリプト

scripts/validate_project.py

生成されたプロジェクトディレクトリを調べ、よくある問題を検出します。

# Validate a generated project
python3 scripts/validate_project.py /path/to/generated-project

# JSON output
python3 scripts/validate_project.py /path/to/generated-project --format json

実施するチェック：

• README.md が存在し、空ではない
• .gitignore が存在する
• （コードが環境変数を参照する場合）.env.example が存在する
• パッケージマニフェスト（package.json、requirements.txt、go.mod、Cargo.toml、pubspec.yaml）が存在する
• コミットされた .env ファイルがない（シークレット漏えいを防ぐ）
• テストファイルが少なくとも 1 つ存在する
• 生成されたコードに TODO／FIXME のプレースホルダーがない

段階的な拡張

複雑な仕様の場合は、段階的に生成します。

1. MVP — 中核機能のみを実装し、最初から最後まで動作させる
2. 認証 — 要望があれば認証を追加する
3. 仕上げ — エラー処理、バリデーション、読み込み状態
4. デプロイ — Docker、CI、デプロイ設定

MVP の後でユーザーに尋ねます。「中核機能が動作しています。次に認証、仕上げ、デプロイを追加しますか。それとも、現在の内容を反復しますか？」

相互参照

• 関連：product-team/saas-scaffolder — SaaS に特化したスキャフォールディング（Next.js + Stripe + Auth）
• 関連：engineering/spec-driven-workflow — 仕様を優先する開発手法
• 関連：engineering/database-designer — データベーススキーマの設計パターン
• 関連：engineering-team/senior-fullstack — フルスタック実装パターン