code-to-spec

to-spec — プロジェクト仕様のリバースエンジニアリング

既存のコードベースを分析し、プロジェクトの機能、構築方法、公開している契約をまとめた構造化された SPEC ドキュメントを作成します。出力されるのは、プロジェクトをゼロから再構築したり、新しい貢献者を受け入れたりする際に活用できる、生きた仕様書です。

---

使用する場面

• 既存のプロジェクトを包括的に理解したい場合
• 概要を把握する必要がある新しいチームメンバーを受け入れる場合
• 仕様書なしで構築されたプロジェクトを文書化する場合
• 実際の実装と意図された設計を比較する場合
• 書き換えや大規模なリファクタリングを準備する場合
• プロジェクトが実際に行っていることと、人々が行っていると思っていることを監査する場合

---

作業内容

1. スコープの確認 — 何を分析するか（リポジトリ全体、特定のディレクトリ、特定の側面）をユーザーに尋ねます
2. 詳細な調査 — プロジェクトの構成、エントリーポイント、設定、テスト、コアロジックを体系的に読み込みます
3. 統合 — 構造化された SPEC ドキュメントを作成します
4. レビュー — ユーザーに提示して、フィードバックと反復を行います
5. 保存 — 最終版の SPEC を合意した場所に書き込みます

---

ステップ 1：スコープの確認

調査を始める前に、ユーザーに尋ねます。

What should I analyze?

A. Entire repository (recommended for small-medium projects)
B. Specific directory or module: [path]
C. Specific aspect only (e.g., API surface, data model, auth flow)

Depth level:
1. Overview — high-level architecture + tech stack + key features (fast, ~5 min)
2. Standard — includes API contracts, data models, config, dependencies (default)
3. Deep — adds internal module interactions, error handling patterns, test coverage analysis

プロジェクトが大規模（ファイル数が 500 を超える）の場合は、概要または特定のモジュールから始めることを勧めます。

---

ステップ 2：詳細な調査

以下を体系的に分析します（プロジェクトに存在するものに合わせて調整してください）。

2.1 プロジェクトの概要

• package.json、go.mod、Cargo.toml、pyproject.toml、pom.xml など
• README、LICENSE
• Git の履歴（最初のコミット日、最近の活動、貢献者数）

2.2 アーキテクチャ

• ディレクトリ構成と組織パターン（モノレポ、レイヤード、ヘキサゴナルなど）
• エントリーポイント（メインファイル、CLI コマンド、サーバーの起動処理）
• モジュール境界と依存関係グラフ（内部）

2.3 技術スタック

• 言語とバージョンの制約
• フレームワークと主要ライブラリ
• ビルドツールとバンドラー
• 実行環境の要件（Node のバージョン、Docker など）

2.4 機能と動作

• ルート定義／CLI コマンド／エクスポートされた関数
• ビジネスロジックのモジュールとその役割
• バックグラウンドジョブ、cron タスク、イベントハンドラー

2.5 データモデル

• データベーススキーマ、マイグレーション、ORM
• 主要なデータ構造とその関係
• 状態管理の方式

2.6 API の公開範囲

• HTTP エンドポイント（メソッド、パス、リクエスト／レスポンスの形式）
• GraphQL スキーマ／gRPC のプロト／WebSocket イベント
• CLI インターフェース（コマンド、フラグ、引数）
• エクスポートされたライブラリ API（公開関数、クラス、型）

2.7 設定と環境

• 環境変数とその用途
• 設定ファイルとそのスキーマ
• 機能フラグ、切り替え設定

2.8 外部依存関係

• サードパーティサービス（データベース、キュー、API）
• インフラストラクチャの要件（クラウドサービス、ストレージ）
• 認証／認可プロバイダー

2.9 テストと品質

• テストフレームワークとアプローチ（ユニット、統合、E2E）
• カバレッジの傾向（テスト対象と未テストの範囲）
• リント、フォーマット、型チェックの設定

2.10 デプロイと運用

• CI/CD の設定
• デプロイ先と戦略
• モニタリング、ログ記録、ヘルスチェック

---

ステップ 3：SPEC ドキュメントの構成

以下のセクションで SPEC を作成します。該当しないセクションは省略してください。

# SPEC: [Project Name]

> Reverse-engineered specification — generated [date] from commit [short-hash]

## 1. Overview

### 1.1 Purpose
[One paragraph: what problem this project solves and for whom]

### 1.2 Key Capabilities
- [Bullet list of what the system can do, from a user's perspective]

### 1.3 Architecture Style
[e.g., "Monolithic Express.js API with React SPA frontend", "CLI tool with plugin system", "Microservices communicating over gRPC"]

---

## 2. Tech Stack

| Layer | Technology | Version |
|-------|-----------|---------|
| Language | ... | ... |
| Framework | ... | ... |
| Database | ... | ... |
| Build | ... | ... |
| Test | ... | ... |
| Deploy | ... | ... |

---

## 3. Project Structure

[Directory tree with annotations explaining each top-level directory's purpose]

---

## 4. Data Model

### 4.1 Core Entities
[For each entity: name, fields, relationships, constraints]

### 4.2 State Transitions
[If applicable: lifecycle states and valid transitions]

---

## 5. API Surface

### 5.1 [Interface Type: REST / CLI / Library / etc.]

[For each endpoint/command/function:]
| Method | Path/Command | Description | Auth |
|--------|-------------|-------------|------|
| ... | ... | ... | ... |

### 5.2 Request/Response Schemas
[Key request/response shapes with field types]

---

## 6. Configuration

| Variable / Key | Required | Default | Description |
|---------------|----------|---------|-------------|
| ... | ... | ... | ... |

---

## 7. External Dependencies

| Service | Purpose | Failure Impact |
|---------|---------|----------------|
| ... | ... | ... |

---

## 8. Business Rules & Constraints

- [Numbered list of invariants, validation rules, and business logic constraints discovered in the code]

---

## 9. Non-Functional Characteristics

### 9.1 Performance
[Observed patterns: caching, pagination, batch processing, etc.]

### 9.2 Security
[Auth mechanism, input validation patterns, secrets management]

### 9.3 Error Handling
[Error strategy: custom error types, error codes, retry policies]

---

## 10. Testing Strategy

| Type | Framework | Coverage Pattern |
|------|-----------|-----------------|
| Unit | ... | ... |
| Integration | ... | ... |
| E2E | ... | ... |

---

## 11. Known Gaps & Assumptions

- [Things that are unclear from the code alone]
- [Assumptions made during analysis]
- [Areas with no tests or documentation]

---

## 12. Appendix

### A. Dependency Graph
[Key module dependencies, import relationships]

### B. Environment Setup
[Steps to run the project locally, derived from config and scripts]

---

ステップ 4：レビューと反復

SPEC の作成後、内容を提示して次のように尋ねます。

SPEC generated. Please review:

- Are there sections that need more detail?
- Are there inaccuracies I should correct?
- Should I add/remove any sections?
- Is the depth level appropriate?

Reply OK to save, or provide feedback for iteration.

ユーザーが確認するまで、フィードバックを反映して再提示します。

---

ステップ 5：保存

保存先をユーザーに尋ねます。

Where should I save the SPEC?

A. docs/SPEC.md (recommended)
B. SPEC.md (project root)
C. Custom path: [specify]

---

分析のヒューリスティクス

目的の特定

• README の最初の行、パッケージの説明フィールド、CLI のヘルプテキストを確認します
• メインのエントリーポイントを確認します。何を起動していますか？
• テストの説明を確認します。期待される動作が平易な言葉で書かれていることがよくあります

アーキテクチャの把握

• import／require 文をたどって、ビルド時の依存関係グラフを作成します
• ディレクトリ名からレイヤーを特定します。例：controllers、services、models、routes、handlers、domain、infra
• 依存性注入のパターン、ミドルウェアチェーン、プラグインの登録を確認します

ビジネスルールの抽出

• 検証関数、ガード節、アサーション文を探します
• エラーメッセージを確認します。何が問題だったのかをビジネス用語で説明していることがよくあります
• テストのアサーションを調べます。期待される動作が記述されています

API コントラクトの特定

• ルート登録（Express：app.get()、FastAPI：@app.get()、Go：mux.HandleFunc()）
• 存在する場合は、OpenAPI／Swagger ファイル
• リクエスト検証スキーマ（Joi、Zod、Pydantic、構造体タグ）
• CLI フラグ／引数の定義（cobra、argparse、yargs）

データモデルの検出

• ORM モデル定義（Prisma、SQLAlchemy、GORM、TypeORM）
• マイグレーションファイル（時系列順）
• 中核となるドメインオブジェクトの型／インターフェース定義
• データベースのシードファイル

---

エッジケース

シナリオ	対応
プロジェクトに README もドキュメントもない	「既知の不足事項」に記載し、コードから目的を推測します
複数のサービスを含むモノレポ	分析するサービスをユーザーに確認します。サービスごとに SPEC を作成するか、境界を明確にした統合 SPEC を作成します
コード生成を使用するプロジェクト	生成コードの目的を記載しつつ、信頼できる情報源（スキーマ、proto ファイル、テンプレート）に重点を置きます
複数のパターンが混在するレガシープロジェクト	確認されたすべてのパターンを記載し、不整合を「既知の不足事項」に記します
ランタイムのないライブラリプロジェクト	公開 API の範囲、型コントラクト、テストから読み取れる使用パターンに重点を置きます
不完全または動作しないコード	存在するものを記載し、動作しない箇所や不完全な箇所を明示します
ファイル数が 1000 を超えるプロジェクト	エントリーポイントから始め、主要なフローをたどります。すべてのファイルを網羅的に読む必要はありません
1 つのリポジトリに複数の言語がある	各言語の役割と相互の連携方法を記載します

---

品質基準

リバースエンジニアリングで作成した優れた SPEC は、次の項目を満たす必要があります。

• プロジェクトに詳しくない開発者が、60 秒でその目的を理解できる
• 技術スタックのセクションに、開発環境を構築するために十分な情報が含まれている
• API コントラクトに基づいて、クライアントを実装できる
• データモデルに基づいて、スキーマを再作成できる
• ビジネスルールが明示されている（「コードを参照」に埋もれていない）
• 既知の不足事項が正直に記載されている（判断できない内容を作り上げていない）
• SPEC が実際のコードと一致している（理想を述べたドキュメントではない）

---

避けるべきアンチパターン

• 意図を作り上げないでください。 何かが存在する理由を判断できない場合は、その旨を記載します。根拠のない理由をでっち上げないでください。
• コードを SPEC にコピーしないでください。 実装を貼り付けず、動作とコントラクトを説明します。
• 一時的な状態を含めないでください。 SPEC が記述するのはシステムの設計であり、現在の実行時の状態ではありません。
• 内部の詳細を過度に規定しないでください。 境界、コントラクト、動作に重点を置きます。内部実装の詳細は仕様ではなく、コードコメントに記載します。
• README が正確だと決めつけないでください。 README の内容はコードに追いついていないことがよくあります。記載内容を実際の実装と照らし合わせて確認します。