# Smart Contractの仕様書をClaude Codeで生成してみる

> スマートコントラクトの仕様書を手作業で作成するのは、膨大な時間と労力がかかります。ABIを解析して関数やイベントを列挙し、各要素に適切な説明を付け、型情報をOpenAPI形式に変換し、さらにNatSpecコメントを抽出して反映する。

- URL: https://cardene.dev/articles/solidity-openapi-spec-generator
- 公開日: 2025-12-19
- 更新日: 2025-12-19
- トピック: Blockchain
- タグ: solidity, openapi, swagger, claude

# はじめに

初めまして。
『DApps開発入門』という本や色々記事を書いているかるでねです。

https://www.amazon.co.jp/dp/B0DQDWM1YK

以下でも情報発信しているので、興味ある記事があればぜひ読んでみてください！

https://cardene.notion.site/EIP-2a03fa3ea33d43baa9ed82288f98d4a9

https://twitter.com/cardene777

https://qiita.com/cardene

https://cardene.substack.com/

https://mirror.xyz/0xACAc709e21e7a4A5a4458BDeeCCA0fc98A6a8A4D

今回は「**Solidityで作成したスマートコントラクトの仕様書をClaude Codeで生成する方法**」についてまとめていきます。

この記事では、Solidityスマートコントラクトの仕様書とドキュメント、生成した仕様書とドキュメントを閲覧できるサイトの構築をClaude Codeで行う方法を提案しています。

以下の記事で*Solidityで作成したスマートコントラクトの仕様書の定義をしているので、よければ読んでください。

https://zenn.dev/heku/articles/solidity-openapi-spec

最終的には以下のようなサイト作成まで行ってくれます。

https://smartcontract-specification.vercel.app/

# Contract Documentation Generator

スマートコントラクトの仕様書を手作業で作成するのは、膨大な時間と労力がかかります。
ABIを解析して関数やイベントを列挙し、各要素に適切な説明を付け、型情報をOpenAPI形式に変換し、さらにNatSpecコメントを抽出して反映する。
この一連の作業を数十のコントラクトに対して行うのは現実的ではありません。

そこで、この作業をClaude Codeで自動化する**Contract Documentation Generator**を作成しました。
このシステムは3つの独立したClaude Code Skillで構成されており、仕様書生成からドキュメントサイトの構築まで段階的に実行できます。

## なぜ中間表現（Contract Spec JSON）を導入したのか

初期の設計では、ABIから直接OpenAPI仕様書を生成することを検討していました。
しかし、このアプローチには問題がありました。

ABIには関数の説明文やパラメータの意味、エラーの発生条件といった「人間が理解するための情報」が含まれていません。
一方で、OpenAPI仕様書には詳細な説明文、サンプル値、エラーレスポンスの定義が必要です。
この差を埋めるために、AIエージェントによる説明文の生成、NatSpecコメントの抽出、エラー解析といった複数の処理が必要になります。

これらの処理を一度に行うと、問題が発生した際にどの段階で何が起きたのかを特定することが困難です。
Contract Spec JSONという中間表現を導入することで、各段階で成果物がファイルとして保存され、問題の特定が容易になりました。

Contract Spec JSONのメリットは以下の通りです。

- **段階的な品質向上**
  生のABI → 構造化JSON → AI強化 → OpenAPIという流れで、各段階での検証が可能。
- **再利用性**
  同じContract Spec JSONからOpenAPI仕様書とMarkdownドキュメントの両方を生成可能。
- **デバッグ容易性**
  問題が発生した場合、どの段階で問題が生じたかを特定しやすい。

## 3つのSkillによる分業体制

Contract Documentation Generatorは、明確に分離された3つのSkillで構成されています。

```mermaid
flowchart TB
    subgraph Input["入力"]
        ABI[ABI ファイル]
        SOL[Solidity ソース]
    end

    subgraph Skill1["contract-spec-generator"]
        P1[Phase 1: 分析・選択]
        P2[Phase 2: Contract Spec JSON生成]
        P3[Phase 3: AI強化]
        P4[Phase 4: 品質検証]
        P5[Phase 5: OpenAPI生成]
        P1 --> P2 --> P3 --> P4 --> P5
    end

    subgraph Skill2["contract-doc-generator"]
        D1[テンプレート適用]
        D2[概要ページ生成]
        D3[サイドバー生成]
        D1 --> D2 --> D3
    end

    subgraph Skill3["contract-site-builder"]
        S1[Docusaurus初期化]
        S2[swagger-ui-react統合]
        S3[ダークモード対応]
        S1 --> S2 --> S3
    end

    Input --> Skill1
    Skill1 -->|OpenAPI YAML<br>Contract Spec JSON| Skill2
    Skill2 -->|Markdown<br>sidebars.js| Skill3
    Skill3 --> Site[Docusaurusサイト]
```

| Skill | 責務 | 入力 | 出力 |
|-------|------|------|------|
| **contract-spec-generator** | 仕様書生成 | ABI + Solidityソース | OpenAPI YAML + Contract Spec JSON |
| **contract-doc-generator** | ドキュメント生成 | OpenAPI + Contract Spec JSON | Markdown + sidebars.js |
| **contract-site-builder** | サイト構築 | Markdown + OpenAPI | Docusaurusサイト |

この分業体制により、各Skillは単一の責務に集中できます。
問題が発生した場合でも、該当するSkillだけを再実行すれば済みます。

### 仕様書生成（contract-spec-generator）

contract-spec-generatorは、5つのフェーズを経てOpenAPI仕様書を生成します。

#### Phase 0: 言語設定

ドキュメント生成言語を選択します。

- 対応言語: English (en)、日本語 (ja)、한국어 (ko)、简体中文 (zh-CN)
- 設定は`language.json`に保存され、後続のフェーズで参照されます

#### Phase 1: コントラクト分析と選択

ABIディレクトリをスキャンして対象コントラクトを特定します。

- テストコントラクト、抽象コントラクト、インターフェースを自動除外
- 既存仕様書がある場合は差分検出で増分更新が可能

#### Phase 2: Contract Spec JSON生成

ABIとソースコードを解析して中間表現を生成します。

- **抽出される情報**
  継承関係、構造体定義、modifier定義、ステート変数、関数シグネチャ
- **型マッピング**
  `address` → `pattern: "^0x[0-9a-fA-F]{40}$"`、`uint256` → `type: string`

#### Phase 3: AI強化

Contract Spec JSONをAIエージェントが強化します。

1. **NatSpecコメント抽出**
   `enhance-spec-from-source.py`がソースコードからコメントを抽出
2. **エラー解析**
   `analyze-errors.py`が関数呼び出しチェーンを追跡してエラーを特定
3. **spec-reviewerエージェント**
   説明文の改善、Modifier情報の追記、コントラクト固有の説明への置換
4. **language-translatorエージェント**
   英語以外の言語が選択されている場合に翻訳を実行

#### Phase 4: 品質検証

`validate-spec.py`がContract Spec JSONの品質をチェックします。

- 必須フィールドの存在確認
- 説明文の品質（最小文字数、空白チェック）
- 型マッピングの正確性
- エラーレスポンスの整合性

#### Phase 5: OpenAPI生成

検証済みのContract Spec JSONからOpenAPI 3.0 YAML形式の仕様書を生成します。

- **出力ファイル**
  - `{ContractName}.openapi.yaml` - OpenAPI仕様書
  - `doc-config.json` - サイト構築用の設定ファイル

### ドキュメント生成（contract-doc-generator）

contract-doc-generatorは、機械的な仕様書を人間が読みやすいドキュメントに変換します。

#### 個別コントラクトのドキュメント

各コントラクトのMarkdownドキュメントを生成します。

- 概要説明（2〜3段落）
- 継承関係
- 主要機能の説明（Mermaidシーケンス図付き）
- セキュリティ上の注意事項
- 要素一覧（定数、変数、Mapping、読み取り関数、書き込み関数、イベント、エラー、構造体、Modifier）

#### 概要ページ（7ページ必須）

システム全体を俯瞰する概要ページを生成します。

| ページ | 内容 |
|--------|------|
| **overview.md** | システム全体の目的と構成 |
| **architecture.md** | コンポーネント間の関係をMermaid図で可視化 |
| **roles.md** | アクセス制御ロールの一覧と権限 |
| **security.md** | セキュリティ上の考慮事項と対策 |
| **testing.md** | テスト戦略とカバレッジ |
| **upgrade.md** | UUPSパターンなどアップグレード方法 |
| **audit.md** | セキュリティ監査の履歴と対応 |

これらのページは**docs-reviewer**と**overview-reviewer**エージェントによって品質向上されます。

### サイト構築（contract-site-builder）

contract-site-builderは、生成されたドキュメントをWebサイトとして公開します。

#### 技術スタック

- **Docusaurus 3.9.2**
  静的サイトジェネレーター
- **swagger-ui-react**
  API仕様書のインタラクティブ表示

:::message
当初はRedocusaurusを検討していましたが、React 19との互換性問題があったため、swagger-ui-reactに移行しました。
これにより、ダークモード/ライトモードの完全対応が可能になりました。
:::

#### 開発時とビルド時の違い

| モード | ファイル管理 | 用途 |
|--------|-------------|------|
| **開発時** | シンボリックリンク | ソースファイルの変更がリアルタイムで反映 |
| **ビルド時** | ファイルコピー | Vercelなどのホスティング環境でも動作 |

ビルド時は`npm run build`の前に`npm run sync`が自動実行され、シンボリックリンクを実ファイルに置き換えます。

## 技術スタックの選定理由

Contract Documentation Generatorの開発過程で、いくつかの技術的な選択を行いました。

### Python への移行

スクリプト言語として当初はJavaScriptを使用していましたが、すべて**Python**に移行しました。
Claude Codeのコンテキストにおいて、Pythonは複雑なファイル処理やJSON操作で可読性の高いコードを書けます。
また、ABIの解析やソースコード処理といったタスクは、Pythonの標準ライブラリだけで十分に実装できます。

### OpenAPI 3.0 YAML への統一

出力形式は**OpenAPI 3.0 YAML**のみに統一しました。
初期バージョンではSwagger 2.0 JSON形式も併せて出力していましたが、メンテナンスの負担を増やすだけで実際に使用されることはありませんでした。

### React 18 互換性の確保

Docusaurusのバージョンは3.9.2を採用し、**React 18**との互換性を確保しています。
swagger-ui-reactもReact 18で問題なく動作します。

## 実際の使い方

Contract Documentation Generatorは、3つのコマンドを順番に実行します。

### Step 1: 仕様書生成

```bash
ABIは artifacts/@openzeppelin/contracts/token/ERC20/ERC20.sol/ERC20.json、コントラクトは node_modules/@openzeppelin/contracts/token/ERC20/ERC20.sol にあります。contract-spec-generator skillを使用して仕様書を作成してください。
```

5フェーズのパイプラインが完了すると、以下が生成されます。

- `docs/contract/specs/` - OpenAPI YAML仕様書
- `docs/contract/ir/` - Contract Spec JSON
- `docs/contract/doc-config.json` - サイト構築用設定

### Step 2: ドキュメント生成

```bash
contract-doc-generator skillを使用して、仕様書からドキュメントを作成してください。
```

各コントラクトのドキュメントと7つの概要ページ、`sidebars.js`が生成されます。

### Step 3: サイト構築

```bash
contract-site-builder skillを使用して、Docusaurusサイトを構築してください。
```

Docusaurusプロジェクトの初期化、swagger-ui-reactの統合、カスタムCSSの適用が行われます。
`http://localhost:3000`でサイトをプレビューできます。

### 追加機能

- **進捗管理**
  `progress.json`と`progress-docs.json`で進捗を管理。中断した処理の再開が可能。
- **多言語翻訳**
  英語、日本語、韓国語、中国語に対応。
- **差分検出**
  既存の仕様書とソースコードを比較し、変更があったコントラクトのみを更新。

:::message
ABIファイルはビルドツールによって出力先が異なります。
事前にコントラクトをビルドしてABIを生成しておいてください。

```bash
forge build
```
:::

# 生成されるサイトの構成

生成されたドキュメントサイトは、以下のようなページ構成になります。

https://smartcontract-specification.vercel.app/

システムの概要ページなども作成されます。

https://smartcontract-specification.vercel.app/docs/overview

ドキュメントページでは、コントラクトごとに主要な機能の説明が確認できます。

https://smartcontract-specification.vercel.app/docs/contracts/ERC20/

各コントラクトには、詳細な仕様書ページも用意されています。

https://smartcontract-specification.vercel.app/docs/api/ERC20

## ページ構成

サイトは以下のページで構成されます。

| ページ | パス | 内容 |
|--------|------|------|
| **トップページ** | `/` | カテゴリ別コントラクトカード一覧 |
| **概要ページ** | `/overview` | システム全体の説明、コントラクト一覧 |
| **ドキュメント** | `/docs/contracts/*` | 各コントラクトの詳細ドキュメント（Markdown） |
| **仕様書** | `/api/*` | OpenAPI仕様書（Swagger UI表示） |

## ヘッダー構成

ヘッダーのナビゲーションは以下のように配置されます。

| 位置 | 要素 | リンク先 |
|------|------|----------|
| **左端** | Logo + プロジェクト名 | `/` |
| **2番目** | **Docs** | `/overview`（システム概要） |
| **3番目以降** | カテゴリドロップダウン | `/api/{ContractName}`（仕様書） |
| **右端** | GitHub | リポジトリURL |

## トップページ

トップページでは、カテゴリ別にコントラクトカードが表示されます。
各カードには「仕様書を見る」ボタンがあり、クリックすると該当コントラクトの詳細仕様ページに移動します。

ヒーロー部分にはタイトルとサブタイトルのみを表示し、ボタンは配置していません。
カテゴリ名は中央寄せで表示されます。

## API仕様ページ

API仕様ページでは、**swagger-ui-react**コンポーネントを使ってインタラクティブな仕様書を表示します。
サイドバーには関数、イベント、エラー、構造体が分類されて表示され、クリックすることで該当箇所にジャンプできます。

:::message
swagger-ui-reactを使用することで、以下のメリットがあります:
- ダークモード/ライトモードの完全対応
- React 18との互換性
- カスタムスタイリングの柔軟性
- Mermaid図との統合が容易
:::

## ドキュメントページ

ドキュメントページは、Markdown形式で記述されています。
以下のセクションで構成されます。

### 構成

1. **タイトル & API仕様書リンク**
   ```markdown
   # ContractName
   > **[📋 API仕様書を見る](/api/ContractName)**
   ```

2. **概要セクション**
   - コントラクトの説明
   - 継承関係（継承しているコントラクトの一覧）

3. **主要機能セクション**
   - コントラクトが提供する主な機能の説明

4. **要素一覧セクション**

   各要素はトグル（`<details>`タグ）で折りたたみ可能な表形式で表示されます。
   詳細な定義はAPI仕様書に記載されているため、ここでは**名前と簡潔な説明のみ**を記載します。

   | カテゴリ | 表の左カラム | 内容 |
   |----------|-------------|------|
   | 定数 | 定数名 | 定数の名前と簡潔な説明 |
   | 変数 | 変数名 | 変数の名前と簡潔な説明 |
   | Mapping | Mapping名 | Mappingの名前と簡潔な説明 |
   | 読み取り関数 | 関数名 | view/pure関数の名前と簡潔な説明 |
   | 書き込み関数 | 関数名 | ステート変更関数の名前と簡潔な説明 |
   | イベント | イベント名 | イベントの名前と簡潔な説明 |
   | エラー | エラー名 | エラーの名前と簡潔な説明 |

   :::message
   パラメータや戻り値などの詳細情報は記載せず、API仕様書への参照に集約します。
   これにより、仕様書とドキュメントの二重管理を回避し、情報の一貫性を保ちます。
   :::

各ドキュメントページの先頭には、対応するAPI仕様書へのリンクが配置されます。

## 概要ページ

概要ページでは、システム全体の説明と、すべてのコントラクトの一覧が表示されます。
各コントラクトには、ドキュメントと仕様書の両方へのリンクが用意されています。

# 最後に

今回は「**SolidityスマートコントラクトをOpenAPI/Swagger形式で仕様書化する方法**」についてまとめてきました。

https://www.amazon.co.jp/dp/B0DQDWM1YK

https://cardene.notion.site/EIP-2a03fa3ea33d43baa9ed82288f98d4a9

https://twitter.com/cardene777

https://qiita.com/cardene

https://cardene.substack.com/

https://mirror.xyz/0xACAc709e21e7a4A5a4458BDeeCCA0fc98A6a8A4D