GovTech東京 テックブログPublicationへの投稿
💬

GitHub社謹製Spec KitにCodex CLI対応のPRを送った話

本城博昭｜GovTech東京
に公開
GitHub
生成 AI
SDD
Codex
Spec Kit
tech

はじめに

GovTech東京 AI・イノベーション室の本城博昭です。

先日、GitHubが公開しているOSSプロジェクトSpec Kitに、Codex CLIサポートを追加するPull Request（#14）を送り、無事マージされました。本記事では、Spec Kitとは何か、なぜこのPRを送ったのか、そしてコミュニティとの議論を通じて得られた学びについて共有します。

Spec-Driven DevelopmentとSpec Kitとは

Spec-Driven Development（仕様駆動開発）は、AIコーディングエージェントを活用する際に詳細な仕様を定義してから実装に進むという開発手法です。これにより、事前設計を重視しない直感的な開発、いわゆるVibe Codingで起きがちな手戻りや品質のばらつきを防ぎ、より体系的で効率的な開発が可能になります。

Spec Kitは、GitHubが2025年9月に公開したSpec-Driven Development（仕様駆動開発）のためのオープンソースツールキットです。このツールは、AIコーディングエージェント（GitHub Copilot、Claude Code、Gemini CLIなど）を活用した開発において、以下の4つのフェーズで構成されるプロセスを提供します：

  1. Specify（仕様化）: 構築するものとその理由について定義し、詳細な仕様を生成
  2. Plan（計画）: 技術的な実装計画を生成
  3. Tasks（タスク化）: 実装を具体的なタスクに分割
  4. Implementation（実装）: AIエージェントが実際のコーディングを実行

なぜCodex CLI対応のPRを送ったのか

背景と動機

GovTech東京では、日々の業務の中で生成AIを活用し、開発の効率化や品質向上に取り組んでいます。その中でも「エージェンティックコーディング」を用いたPoC開発は、スピードと再現性が求められるため、Spec-Driven Development（仕様駆動開発）のような体系的な手法との親和性が高いと感じています。

PRを作成した時点（2025年9月初旬）で、Spec Kitは以下の3つのAIツールのみをサポートしていました：

  • GitHub Copilot
  • Claude Code
  • Gemini CLI

ちょうどこの時期、OpenAI社のCodex CLIが大幅にアップデートされ、開発者コミュニティで大きな話題となっていました。新しいCodexは、GPT-5をベースにエージェンティックコーディングに最適化されたGPT-5-Codexを搭載し、スクリーンショットやワイヤーフレームなどの画像共有機能、To-doリストによる進捗管理、Web検索やMCP（Model Context Protocol）による外部システム連携など、これまでのAIコーディングツールを大きく進化させる機能が数多く追加されました。さらに、ターミナル、IDE、Web、GitHub、iOSアプリなど、あらゆる開発環境でシームレスに作業を継続できる統合体験も提供されました。 これにより開発者の間では、どのツールがより優れているか、それぞれの強みは何かといった議論が交わされていました。

このような状況を踏まえ、業務でのPoC開発や技術検証においても利用頻度が高まると考えられるCodex CLIを、Spec Kitで扱えるようにすることは業務上も価値があると判断し、このPRの作成に至りました。

技術的な課題

Codex CLIの統合には、他のツールとは異なる特有の課題がありました：

  • コマンドの読み込み方式の違い: Codex CLIは${CODEX_HOME:-~/.codex}/promptsからプロンプトを読み込むため、プロジェクトごとの設定が難しい
  • メモリ管理: AGENTS.mdファイルを使用した独自のメモリ管理システム
  • 初期化の必要性: codex /initコマンドによる明示的な初期化が必要

PRの実装内容

主な変更点

  1. Codex CLI用のテンプレート追加

    • spec-kit-template-codex-shとspec-kit-template-codex-psテンプレートを追加
    • POSIXシェルとPowerShell両方のバリアントをサポート

  2. コマンドディレクトリの自動設定

    • Codex CLIの制約（CODEX_HOME内のプロンプトのみ読み込み）に対応し、必要なファイルを自動配置
    • commands/ディレクトリにspecify.md、plan.md、tasks.mdを自動生成
    • プロジェクトごとのコマンドテンプレートをワークスペース内で管理可能に

  3. フォールバック機構の実装

    • パッケージ化されたテンプレートが利用できない場合の多段階フォールバック機構を実装
    • Codex専用テンプレート未公開時はCopilotテンプレートを使用、それも不可の場合は埋め込み最小限コマンドを生成
    • どのような環境でもユーザーが即座にツールを使い始められる仕組み

  4. 初期化フローの改善

    specify init <project_name> --ai codex
    • --ai codexオプションを追加し、Codex CLI用のプロジェクト初期化を完全自動化
    • Codex CLI特有の設定（commands/ディレクトリの生成、AGENTS.mdへのコンテキスト記録、シェルスクリプトの配置）を一括で実行
    • Codex CLIの動作確認（codex --version）を初期化時に自動実施

  5. AGENTS.mdファイルの統合

    • Codex用のコンテキスト更新がAGENTS.mdファイルをターゲットとするよう変更
    • 後に追加されたopencode との共通化を実現

コミュニティからの技術的な議論と改善

このPRで最も価値があったのは、実際にツールを使用している開発者たちとの建設的な議論でした。ここでは、主な技術的な議論とそれに基づく改善について紹介します。

初期の反応と実用性の検証（9月4-6日）

PRを提出してすぐに、複数の開発者から関心が寄せられました：

  • @adam-paterson: 本番ソフトウェアで2日間テストし、動作を確認。ただし、Codex CLIがネイティブでカスタムコマンドをサポートしていないため、LLMにcommands/ディレクトリのコマンドを使用するよう促す必要があることを指摘
  • @tabtablabs-dev: Codexに再利用可能なプロンプトが追加されたことを報告

これらのフィードバックから、実装の方向性が正しいことが確認できました。

設計に関する議論（9月7-15日）

コミュニティから以下のような技術的な問題提起がありました：

  1. フォールバック機構について
    • 「なぜCodexだけがCopilotテンプレートへのフォールバックシステムを持つのか？」という質問
    • 将来的に追加される他のアシスタントも考慮すべきとの指摘
    • 結論: Codex CLIのテンプレート配布が確立するまでの暫定措置として、この設計を維持することで合意
  2. ディレクトリ構造の最適化
    • /commands/plan.mdを/github/prompts/plan.prompt.mdへのシンボリックリンクにする提案
    • 簡略化されたバージョンよりも完全なテンプレートを使用すべきとの意見
    • 結論: プロジェクトローカルのコマンドディレクトリを維持し、Codex固有の制約に対応する現在の設計を採用
  3. プロジェクト単位の設定
    • CODEX_HOME環境変数を使用したプロジェクトごとの設定分離の必要性
    • 各プロジェクトでのログインが必要になる課題
    • 結論: ワークスペースレベルでのコマンド読み込みを優先し、ユーザーの利便性を重視

改善とリファクタリング（9月18-20日）

上記の議論を踏まえ、以下の改善を実施しました：

  1. エージェント固有のロジックの最小化
    • プロジェクトのMaintainerである@localdenより「Specifyにエージェント固有のコードを過度に含めたくない」との指摘
    • Spec Kitが複数のAIツールをサポートする汎用的なフレームワークとして成長する上で重要な設計方針
    • 共通ヘルパー関数を使用し、Codex固有のロジックを最小限に抑える実装へ変更
  2. ドキュメントの明確化
    • Codexが他のエージェントと異なる理由（ワークスペースからスラッシュコマンドを読み込む仕様など）を明確に説明
    • 将来的なメンテナンスを考慮した詳細なコメントを追加
  3. テスト容易性の向上
    • -no-gitオプションのサポート追加
    • 初期化フローの簡略化
  4. 新しく追加されたツールとの整合性確保
    • この期間中にCursor、Qwen、opencode、Windsurfなどのツールが次々と追加
    • Codexが8番目のツールとして自然に統合されるよう、他のツールの実装パターンを参考に調整

最終レビューとマージ（9月20日）

プロジェクトのMaintainerである@localdenによる最終レビューで「現在のPRは少し多くを追加しすぎており、新しいエージェントへの変更はもう少し外科的であるべき」とのフィードバックを受け、最終的なクリーンアップを実施しました。

最終的にマージされた実装内容：

  • Codex CLI用のテンプレート（ShellとPowerShell）の追加
  • プロジェクトローカルのcommands/ディレクトリ自動生成機能
  • AGENTS.mdファイルを利用したコンテキスト管理
  • 初期化コマンドspecify init <project_name> --ai codexのサポート
  • 他のAIツールと一貫性のあるインターフェース

この実装により、Codex CLIユーザーは他のツールと同様の体験でSpec-Driven Development（仕様駆動開発）を始められるようになり、かつCodex固有の機能（ワークスペースレベルのコマンド、AGENTS.mdファイル）も活用できるようになりました。

Spec KitのContributorsのスクリーンショット
マージされたことによりContributorsに追加されました

活発なプロジェクトへの貢献で直面した課題

このPRのもう一つの側面として、Spec Kitプロジェクトが非常に活発に開発されていたことが挙げられます。前述の通り、私がPRを作成してからマージされるまでの約2週間の間に、以下のAIツールが次々とサポートされました：

  • Cursor
  • Qwen
  • opencode
  • Windsurf

これらの新しいツールのサポートが追加されるたびに、PRにコンフリクトが発生しました。各コンフリクトの解消には、新しいツールの実装パターンを理解し、Codex CLIの実装を他のツールと一貫性を保つよう調整する作業が必要でした。9月18日には大規模なリベースとforce-pushを実施（66257cdからc440ca0へ）し、最終的には4回以上の主要なコンフリクト解消を経てマージに至りました。

学んだこと

このOSS貢献を通じて、以下のような学びがありました：

  1. コミュニティとの協働の価値: 実際に使用している開発者からのフィードバックが、より実用的で汎用的な実装につながりました。特に@localdenの「エージェント固有のコードを最小限に」という指摘は、Spec Kitの将来的な拡張性を考える上で重要な視点でした
  2. 設計の簡潔性: 「必要最小限の変更で最大の効果を」という原則の重要性を実感しました。当初は機能を詰め込みすぎていましたが、レビューを通じて本質的な変更のみに絞ることができました
  3. 活発なプロジェクトへの貢献の難しさと価値: 頻繁な更新によるコンフリクトへの対処は大変でしたが、それだけ多くの開発者が関心を持ち、エコシステムが急速に成長している証でもありました
  4. 技術的な議論から得られる洞察: フォールバック機構やディレクトリ構造についての議論を通じて、異なるAIツール間の設計思想の違いや、汎用的なフレームワークを作る上での考慮点について深く理解できました
  5. Spec-Driven Development（仕様駆動開発）のプロセス理解の深化: このPRを通じて仕様駆動開発の各フェーズがどのように連携するかを深く理解でき、業務で実施しているエージェンティックコーディングのレベルアップにつながりました。例えば、PoC開発の初期段階で仕様を明示的に固め、AIに効率よくタスクを分解させる流れが以前よりスムーズになりました

統計データ

  • PR期間: 約16日間（9月4日〜9月20日）
  • コミット数: 11コミット
  • 追加されたAIツール数: 開始時3つ → マージ時8つ（5つ増加）
  • 主要なコンフリクト解消回数: 4回以上

まとめ

今回のPRを通じて、Spec KitにCodex CLIが追加され、さらに多くの開発者がSpec-Driven Development（仕様駆動開発）を活用できるようになりました。

特に価値があったのは、コミュニティとの技術的な議論を通じて、より良い設計にブラッシュアップできたことです。フォールバック機構、ディレクトリ構造、エージェント固有のロジックの最小化など、様々な観点からの議論が、最終的により汎用的で保守しやすい実装につながりました。

また、急速に成長するプロジェクトへの貢献は、コンフリクトの解消など技術的な困難もありましたが、それ以上にエコシステムの成長に立ち会い、多様なAIツールの設計思想に触れる貴重な機会となりました。

この経験を通じてSpec-Driven Development（仕様駆動開発）のプロセス理解が深まり、業務で取り組んでいるエージェンティックコーディングの実践にも直結しました。さらに、この知見はGovTech東京のAI・イノベーション室内で定期的に開催しているAI勉強会や、自チームの枠を超えて社内参加者を募り実施した「AIエージェント勉強会」などを通じて共有しています。OSSへの貢献で得た知見をチームや組織全体の開発文化に還元し、行政領域におけるAI開発の成熟と、オープンで学び合う文化の醸成を今後も推進していきたいと考えています。

参考リンク

GovTech東京 テックブログ
GovTech東京 テックブログPublication

東京都が設立した外郭団体「GovTech東京」のテックブログです。GovTech（ガブテック）は、Government×Technologyの融合させた言葉。このブログでは、行政DXへの技術的挑戦、現場で得た知見、そして組織のカルチャーを発信していきます。govtechtokyo.or.jp

Discussion