🌊
2026年の新常識！？ OpenAPI.ymlを書かずにAPI開発する Notion × Claude Code × Serena MCP

mizumoto
2025/12/25に公開
Notion
OpenAPI
Model Context Protocol
Claude
tech
 はじめにこんにちは、クロステックマネジメントDevops Dept.所属の水本です。
DevOps Dept.はクロステック・マネジメントが提供するプロダクトのエンジニアリングを担当し、スクラム開発を軸に継続的な改善と価値提供を行なっています。
今回は、私たちのチームで実践している、AIを活用した新しいバックエンド開発フローについて紹介します。
API開発の現場で、こんな悩み抱えていませんか？
「実装前にOpenAPI.ymlを完璧に定義するのはコストが高すぎる」
「コードを修正したのにドキュメント更新し忘れて、フロントエンド担当に怒られる」
「Schema Firstって言うけど、結局YAMLとコードの二重管理で疲弊している」
従来の「OpenAPI.yml（Swagger）ファースト」な開発は、理想的ですが運用コストが高いのが現実です。
そこで今回は、私たちのチームで実践している、「Notionで要件を書くだけで、実装計画からコード、テスト、そしてOpenAPI仕様書までが自動生成される」という、新しい開発フローを紹介します。
主役は Claude Code + Notion MCP、そして OSSのCoding Agent Toolkit Serena です。

これらを組み合わせることで、バックエンド開発のパラダイムシフトが実現できます。


技術
バージョン


Go
1.25

Gin
v1.11

GORM
v1.31


 😫 従来の課題：OpenAPI.ymlファーストの限界これまでの一般的なフローは以下のようなものでした。
OpenAPI.ymlを手書き ✍️
レビュー 👀
コード生成（oapi-codegen等） ⚙️
実装 👨‍💻
仕様変更時は 1 に戻る 🔄
ここが辛い！

二重管理のコスト: YAMLとGoコード（構造体）の同期作業が発生する。

学習コスト: OpenAPI独自の記法や構成を覚える必要がある。

変更への弱さ: 開発中の「あ、やっぱり仕様変えたい」という変更コストが高い。

 🚀 新しいアプローチ：Notion要件定義ファースト私たちの解はシンプルです。「人間は自然言語（Notion）で要件だけ書く。あとはAIに任せる」

 なぜNotionなのか？NotionをSSOT（Single Source of Truth）にするメリットは以下の通りです。

誰でも書ける: 技術用語不要。日本語で要件を記述できます。

構造化: データベース機能でタスク管理と仕様書を統合可能。

Mermaid対応: DB設計図（ER図）もコードブロックで記述可能。

AIとの親和性: Notion MCPを通じて、Claudeが内容を正確に読み取れます。

 🛠️ 実際の開発フロー（所要時間：約18分）ここからは、実際に判定機能（RequirementResult）を開発した時の流れを紹介します。

※記事中のコマンドは、ターミナル上で動作する Claude Code (CLI) のプロンプトに入力するものを指します。

 Step 1. Notionで要件定義（人間：5分）Notionのチケットに、以下のフォーマットで要件を記述します。

ポイントは、自然言語での概要、具体的な入出力例（JSON）、そしてMermaidによるDB設計です。
!実際のNotionチケットの内容
📌 Overview

判定機能の構築 - APIを通じて要件判定データを管理する機能
📋 Requirements (Must/Want)

Must:
要件判定データの作成ができること
合否を登録することができること
DB
🔌 Interface Definition

Endpoint

POST /api/v1/requirement-results
Request Structure
{
  "requirement_assignment_id": 1,
  "pass_flag": true
}
Response Structure
{
  "result": "OK",
  "requirement_result": {
    "requirement_result_id": 1,
    "requirement_assignment_id": 1,
    "pass_flag": true,
    "created_at": "2025-12-04T00:00:00Z",
    "updated_at": "2025-12-04T00:00:00Z"
  }
}
ErrorPattern
存在しない requirement_assignment_id → usecase層で404 を発生させる
📝 Execution Plan (Output by Claude/Serena)

（ここは空欄にしておく。後でAIが追記する場所）
!ここがすごい！AIへの伝わり方

Mermaid: 関連テーブル（requirement_assignments）も一緒に書くことで、AIは外部キー制約やリレーション関係を正確に理解します。

Request/Response JSON: Goの構造体（Struct）の定義は、このJSONから型推論されて自動生成されます。

ErrorPattern: 「usecase層で」と指定することで、アーキテクチャのどこにロジックを書くべきかをAIに指示できています。

 Step 2. 実装計画の自動生成（AI：2分）ここで登場するのが、OSSのCoding Agent Toolkit Serena です。

Serenaはコードベースの構造を理解し、計画的かつ正確にコード編集を行うためのMCPサーバーです。
Claude Code上で以下のコマンドを実行し、Serenaツールを呼び出します。
# Claude CodeのCLIプロンプトに入力
/serena [https://www.notion.so/your-page-id](https://www.notion.so/your-page-id)...
裏側でClaude × Serenaがやっていること

Read: Notion MCPでページの仕様を読み込む。

Analyze: コードベースを解析（「これはDDD構成だ」「既存の似た機能はこれだ」と理解）。

Plan: 具体的な実装計画を策定。

Write Back: Notionページに計画を書き込む。
まだコードは書きません。まずは計画を立てさせます。

 Step 3. 人間によるレビュー（人間：1分）Notionに戻ると、末尾に「🤖 Serena Execution Plan」が追記されています。
🤖 Serena Execution Plan (抜粋)
作成・修正するファイル一覧

internal/domain/requirement_result/requirement_result.go (Entity)

internal/usecase/requirement_result/create.go (Usecase)

internal/handler/requirement_result/create.go (Handler)
テスト戦略

TestNewRequirementResult: ドメインバリデーション確認

TestCreateUsecase: モックを使ったビジネスロジック確認
人間はこれを見て「うん、方針合ってるね」と確認するだけです。

 Step 4. 実装の実行（AI：10分）計画にGoサインを出します。
# Claude CodeのCLIプロンプトに入力
/serena --apply
Serena MCPが実装を開始します。
コード生成: DDDに基づいたディレクトリ構成でファイルを生成。
テスト実装: gomock を使ったユニットテストを自動生成。
Swaggerアノテーション付与: ここが重要！ ハンドラー関数にコメントとしてAPI仕様を追記します。
自動検証: make test, go vet, make docs を自動実行して品質チェック。
make docs の中身 私たちのプロジェクトでは、swaggo/swag を使用してアノテーションからOpenAPI仕様書を生成しています。docs:
swag init --parseDependency --generalInfo ./cmd/server/main.go --output ./docs/swagger
Serenaはこのコマンドの実行までを自動で行います。
生成されるコード例（Handler層）
// internal/handler/requirement_result/create.go

// CreateRequirementResult godoc
// @Summary       要件判定結果の作成
// @Description   要件割当に対する合否判定結果を登録します
// @Tags          requirement-results
// @Accept        json
// @Produce       json
// @Param         request body request.CreateRequest true "判定結果"
// @Success       200  {object}  response.RequirementResultResponse
// @Failure       400  {object}  response.ErrorResponse
// @Failure       404  {object}  response.ErrorResponse
// @Router        /v1/requirement-results [post]
func CreateHandler(deps *handler.Deps) gin.HandlerFunc {
    // ... 実装 ...
}

 Step 5. ドキュメント生成とPR作成（AI：30秒）実装完了後、自動的にSwagger生成コマンドが走り、Swagger UIが更新されます。swaggoで生成されるページを開けば、最新のAPI仕様書が出来上がっています。
最後にClaudeに一言、「PR作って」と指示します。 これで、NotionのタスクID（prefix ID）と紐付いたブランチ・PRが作成されます。

 🔧 （参考）Claude Code プロンプトの全容ここまでスムーズにAIを動かすために、私たちはClaude Codeに対して詳細な**システムプロンプト（カスタムコマンド定義）**を設定しています。 この定義により、「計画と実行の分離」や「テストコードの強制」、「Swaggerアノテーションの記述」を徹底させています。
興味のある方は、以下の詳細を展開して確認してください。
🛠️ 実際のシステムプロンプト・コマンド定義（クリックで展開）---
allowed-tools: Read, Glob, Grep, Edit, MultiEdit, Write, Bash, TodoWrite, mcp__serena__check_onboarding_performed, mcp__serena__delete_memory, mcp__serena__find_file, mcp__serena__find_referencing_symbols, mcp__serena__find_symbol, mcp__serena__get_symbols_overview, mcp__serena__insert_after_symbol, mcp__serena__insert_before_symbol, mcp__serena__list_dir, mcp__serena__list_memories, mcp__serena__onboarding, mcp__serena__read_memory, mcp__serena__remove_project, mcp__serena__replace_regex, mcp__serena__replace_symbol_body, mcp__serena__restart_language_server, mcp__serena__search_for_pattern, mcp__serena__switch_modes, mcp__serena__think_about_collected_information, mcp__serena__think_about_task_adherence, mcp__serena__think_about_whether_you_are_done, mcp__serena__write_memory, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, mcp__notion__read_page, mcp__notion__append_block_children
description: Notion連携と構造化されたアプリ開発のためのSerena MCPコマンド
---

## クイックリファレンス

```bash
/serena <NotionURL>                 # Notion連携：要件読込 → 計画作成 → Notionへ書込（実装はしない）
/serena <問題> [オプション]           # 通常モード：計画表示（チャット内）
/serena --apply                      # 計画実行（Notionの計画またはチャットの計画を実行）
/serena <問題> --yes [オプション]     # 即座実行（計画スキップ）

## Notion連携ワークフロー

Notion URLが入力された場合、以下の手順で処理が自動化されます：

1.  **Read**: Notion MCPを使用してページの要件・仕様を読み込む
2.  **Plan**: Serena MCPを使用してコードベースを調査し、実行計画を策定
3.  **Write Back**: **実装は行わず**、Notionページ末尾に「実行計画」を書き込む
4.  **Wait**: ユーザーからの `/serena --apply` を待機

---

## オプション

| オプション | 説明 | 使用方法 |
|----------|------|---------|
| `-q` | クイックモード (3-5思考/ステップ) | `/serena "修正" -q` |
| `-d` | ディープモード (10-15思考/ステップ) | `/serena "設計" -d` |
| `-c` | コード重視の分析 | `/serena "最適化" -c` |
| `-s` | ステップバイステップ実装 | `/serena "機能" -s` |
| `-v` | 詳細出力（プロセスを表示） | `/serena -v` |
| `--yes` | 即座実行（計画段階をスキップ） | `/serena "修正" --yes` |
| `--apply` | 承認済み計画の実行 | `/serena --apply` |

## コンテキスト（自動収集）
- プロジェクトファイル: !`find . -maxdepth 2 -name "package.json" -o -name "*.config.*" | head -5 2>/dev/null || echo "設定ファイルなし"`
- Gitステータス: !`git status --porcelain 2>/dev/null | head -3 || echo "Gitリポジトリではありません"`

## コアワークフロー

### 1. 入力タイプの検出
- **URL入力 (Notion)**: 要件定義書としての処理モード（Read & Plan & Write Back）
- **テキスト入力**: 通常のタスク処理モード（Plan & Approve）
- **フラグ入力 (--apply)**: 実装実行モード（Execute）

### 2. 問題検出とテンプレート選択 (Serena)
- **デバッグ**: エラー、バグ、問題 → 5-8思考
- **設計**: アーキテクチャ、システム → 8-12思考
- **実装**: 構築、作成、追加 → 6-10思考

## タスク実行手順

あなたはSerena MCPとNotion MCPを統合するエキスパート開発者です。入力内容に応じて以下のフローを厳守してください。

### ケースA: Notion URLが入力された場合（計画作成モード）

1.  **要件取得**:
    - 指定されたNotion URLのコンテンツをNotion MCP (`read_page`等) で取得する。
    - 要件、API定義、Req/Res構造を解析する。

2.  **現状分析 (Serena)**:
    - 要件に基づき、Serena MCP (`find_symbol`, `get_symbols_overview`等) を使用して、関連する既存コードや影響範囲を特定する。
    - コードの構造、既存の型定義、ルーティング等を把握する。

3.  **計画策定 (No Coding)**:
    - ギャップ分析を行い、具体的な実装ステップを策定する。
    - **重要**: この段階では `Edit` や `Write` ツールでコードを変更してはならない。

4.  **Notionへのフィードバック**:
    - 策定した「実行計画」をNotionページの末尾（または指定セクション）に書き込む。
    - Notion MCP (`append_block_children`等) を使用する。
    - **書き込みフォーマット**:
        ```markdown
        ## 🤖 Serena Execution Plan
        
        ### 📋 Steps to Implement
        1. [ファイル名] の [関数名] を変更...
        2. [ファイル名] を新規作成...
        
        ### 📁 Affected Files
        - `path/to/file`
        
        ### ⚠️ Risks & Notes
        - [リスクや注意点]
        ```

5.  **完了報告**:
    - 「Notionに実行計画を書き込みました。内容を確認し、問題なければ `/serena --apply` を実行してください」と応答し、終了する。

### ケースB: `/serena --apply` が入力された場合（実装実行モード）

1.  **計画の参照**:
    - 直前のコンテキストにある「実行計画」を参照する。
    - 直前がNotionタスクだった場合、Notion上に書き込んだ計画、またはチャットログ内の計画を正とする。

2.  **実装実行 (Serena)**:
    - Serena MCPの編集ツール (`insert_before_symbol`, `replace_regex`, `write_memory` 等) を使用して、計画通りにコードを実装する。
    - LSPの機能を活かし、シンボル単位で正確に編集を行う。
    - **【重要】テストコードの作成**:
        - **ドメイン層テスト**: ドメインモデルを作成した場合、`domain/{entity}/{entity}_test.go` を作成
            - エンティティ作成ロジック（`NewXxx`）のテスト
            - バリデーションロジックのテスト
            - Functional Options パターンのテスト
            - 外部依存なし、モック不要
        - **リクエストバリデーションテスト**: リクエスト構造体がある場合、`handler/{entity}/request_test.go` を作成
            - `testutil.RequestValidationTestCase` を使用して簡潔に記述
            - 正常系、エラー系（必須項目、型違い、範囲外など）をテスト
        - **ユースケース層テスト**: ビジネスロジックがある場合、`usecase/{entity}/*_test.go` を作成
            - `make generate-mocks` または `go generate ./internal/domain/...` でモック生成
            - インターフェースに `//go:generate mockgen -source=$GOFILE -destination=mock_{パッケージ名}_repository.go -package=$GOPACKAGE` を記載
            - `testutil.NewUsecaseTestHelper()` でロガーを取得
        - 参考: `docs/testing/TESTING_GUIDE.md`, `docs/testing/EXAMPLES.md`
    - **【重要】OpenAPI生成用コメントの記述**:
        - APIエンドポイントを実装する際は、Go言語の標準的な `swaggo/swag` 形式のアノテーションコメントを**必ず**記述する。
        - Notionから読み取った「Requestパラメータ」「Response構造」「HTTPステータスコード」を正確に `@Param`, `@Success`, `@Failure` として反映させる。
        - アノテーション例：
            ```go
            // ListSubjects godoc
            // @Summary      科目一覧取得
            // @Description  登録されている全ての科目を取得します
            // @Tags         subjects
            // @Accept       json
            // @Produce      json
            // @Success      200  {object}  response.SubjectListResponse
            // @Failure      500  {object}  response.ErrorResponse
            // @Router       /subjects [get]
            ```

3.  **テスト実行と検証**:
    - テストを実行し、全て通ることを確認: `make test`
    - 必要に応じてモックを再生成: `make generate-mocks`
    - ビルドが成功することを確認: `go build ./...`
    - 静的解析をクリア: `go vet ./...`

4.  **ドキュメント生成と完了**:
    - 実装完了後、`make docs` コマンドを実行し、Swaggerファイルを更新する。
    - 生成されたドキュメントは `docs/` ディレクトリに配置される。
    - 修正ファイルと更新されたドキュメントを報告する。
    - (可能であれば) Notion側のステータス更新やコメント追記を行う。

### ケースC: 通常のテキスト入力（従来モード）

1.  **引数チェック**：`--yes`フラグがあるか確認
2.  **計画段階**（`--yes`なし）：
    - チャット上に実行計画を表示し、承認待ち状態にする。
3.  **即座実行**（`--yes`あり）：
    - 計画段階をスキップし、Serena MCPを使用して直ちに実装を行う。

## ベストプラクティス

**Notion主導開発:**
```bash
# 1. Notionで要件を書く
# 2. URLを投げる
/serena [https://notion.so/my-task-page](https://notion.so/my-task-page)...

# 3. Notionに追記された計画を目視確認・修正
# 4. 実装
/serena --apply

**クイックフィックス:**
```bash
# Notionを経由せずサクッと直す
/serena "util.goのスペルミス修正" --yes

 ⏱️ 効果：作業時間の内訳このフローにより、1機能あたりの開発時間が約18分まで短縮されました。


工程
従来 (OpenAPI手書き)
新フロー (Notion × AI)


定義・設計
60分 (YAML記述)
5分 (Notion記述)

計画・レビュー
10分
3分 (AI生成 + 人間確認)

実装・テスト
90分
10分 (AI自動実装)

ドキュメント
20分 (修正・同期)
0分 (自動生成)

PR作成
5分
0.5分 (自動作成)

合計
約3時間
約18.5分


 🧠 なぜOpenAPI.ymlが不要になったのか？仕組みは 「Code First (with Annotations)」 への回帰ですが、AIのおかげで意味合いが変わりました。

要件定義書 = 人間用の仕様書

Notion上のJSONサンプルやMermaidが「仕様」として機能します。

Swaggerアノテーション = 機械用の仕様書

実装と同時にAIがアノテーションを書くので、コードとドキュメントの乖離が起きません。

Single Source of Truth

正解は常に「コード（アノテーション含む）」にあり、OpenAPI.ymlはそこから生成される「成果物」に過ぎなくなりました。

 🔮 Future: フロントエンドも「OpenAPIレス」になる未来このフローを突き詰めると、さらなる可能性が見えてきます。それは、フロントエンド開発におけるOpenAPIの完全な撤廃です。
現在は、バックエンドが生成した OpenAPI.yml を元に、フロントエンドが openapi-generator 等を使ってTypeScriptの型定義やAPIクライアントを生成するのが一般的です。

しかし、Notion上の「Interface Definition」が十分に構造化されていれば、AIはそこから直接：
Request/ResponseのTypeScript型定義
データフェッチを行うReact Hooks (TanStack Query等)
バリデーションロジック (Zod等)
これらを生成することが可能なはずです。

バックエンドとフロントエンドが、それぞれ独立して「Notionの要件」という共通の親を参照してコードを生成する。

そうなれば、中間成果物としてのOpenAPI（Swagger）すら経由する必要がなくなり、「要件定義書が即、動作するアプリケーションになる」という世界観が実現するのではないか、と考えています。

 🛡️ Future 2: AIの「ゆらぎ」をテストで完全担保するもう一つの展望は、品質保証の強化です。

AIによるコーディングは非常に強力ですが、使用するモデルのバージョンや、コンテキスト（Memory）の状態によって、出力されるコードに微妙な「ズレ」や「揺らぎ」が生じるリスクがあります。
この不確実性を排除するために、私たちは「実装の詳細」ではなく「テストの通過」を正義とするアプローチを進めていきたいと思っています。
Notionの要件定義には、入力（Request）と期待される結果（Response/DB状態）が明記されています。ここから実装コードだけでなく、以下のテストパターンを網羅的に生成・実行します。

Request/Handler層: バリデーションルールやステータスコードの単体テスト

Domain/Usecase層: ビジネスロジックと境界値の単体テスト

Integration Test: 実際にDB（Testcontainers等）を起動し、APIコールからDBのレコード保存までを一気通貫で検証する結合テスト
特に重要なのが 3. インテグレーションテスト です。

AIが内部でどのようなロジックを書こうとも、「DBに正しいデータが保存され、正しいレスポンスが返る」 という事実さえテストで担保できれば、その実装は「正しい」とみなせます。
「Notionからテストを生成し、そのテストをパスするまでAIが自己修正を繰り返す」

このサイクルが確立できれば、人間の見落としによるリスクは極限まで下がり、ソフトウェアの品質は保証されるようになるはずです。

 まとめ
Before: YAML手書き → コード生成 → 実装 → ズレて死ぬ 😇

After: Notion要件 → AIが計画・実装・アノテーション付与 → OpenAPI自動生成 → ハッピー 🥰
AIとNotion、そしてSerena MCPを組み合わせることで、ドキュメントは「書くもの」から「出力されるもの」へと変化しました。

ぜひ、皆さんのプロジェクトでもこの「爆速開発フロー」を試してみてください！

 おわりにクロステック・マネジメント社は、「教育×AI」で次世代の学びを創造するために生まれた芸術大学発のスタートアップです。

ご興味のある方は、ぜひお気軽にお問い合わせいただけると嬉しいです！

 参考リンク
oraios/serena (GitHub) - 今回使用したCoding Agent Toolkit
Model Context Protocol (MCP)

swaggo/swag - GoのSwagger生成ツール
技術	バージョン
Go	1.25
Gin	v1.11
GORM	v1.31
工程	従来 (OpenAPI手書き)	新フロー (Notion × AI)
定義・設計	60分 (YAML記述)	5分 (Notion記述)
計画・レビュー	10分	3分 (AI生成 + 人間確認)
実装・テスト	90分	10分 (AI自動実装)
ドキュメント	20分 (修正・同期)	0分 (自動生成)
PR作成	5分	0.5分 (自動作成)
合計	約3時間	約18.5分
GitHubで編集を提案
クロステックマネジメント（京都芸術大学）
京都芸術大学のテックブログです。採用情報：hrmos.co/pages/xtm/jobs 芸大など5校を擁する瓜生山学園は、通信教育で国内最大手、国内で唯一notionと戦略パートナー契約を結ぶなどDX領域でも躍進、EdTech領域でAIプロダクトを開発する子会社もあり、実は多くのエンジニアがいます。
はじめに

😫 従来の課題：OpenAPI.ymlファーストの限界

🚀 新しいアプローチ：Notion要件定義ファースト

なぜNotionなのか？

🛠️ 実際の開発フロー（所要時間：約18分）

Step 1. Notionで要件定義（人間：5分）

Step 2. 実装計画の自動生成（AI：2分）

Step 3. 人間によるレビュー（人間：1分）

Step 4. 実装の実行（AI：10分）

Step 5. ドキュメント生成とPR作成（AI：30秒）

🔧 （参考）Claude Code プロンプトの全容

⏱️ 効果：作業時間の内訳

🧠 なぜOpenAPI.ymlが不要になったのか？

🔮 Future: フロントエンドも「OpenAPIレス」になる未来

🛡️ Future 2: AIの「ゆらぎ」をテストで完全担保する

まとめ

おわりに

参考リンク

Discussion
