GitHub Spec Kit ワークフローと省略可能なコマンドを調べる

  • 8 分

GitHub Spec Kit は、仕様と AI コーディング アシスタントを統合することで、仕様駆動開発 (SDD) を可能にするオープンソース のツールキットです。 高度な機能を探索する前に、基本的な概念を確認しましょう。

GitHub Spec Kit の基本を確認する

GitHub Spec Kit は、AI 支援型開発における基本的な課題である、コーディング アシスタントとの複数の対話間でのコンテキストと一貫性の維持に取り組んでいます。 次の 3 つの重要な機能が提供されます。

  • 永続的な成果物: 仕様、プラン、タスクは、マークダウン ファイルとしてリポジトリに格納されます。
  • 標準化されたワークフロー: 定義されたプロセスは、仕様、計画、タスクの内訳、実装という 4 つの SDD フェーズを案内します。
  • 再利用可能なコマンド: 組み込みのスラッシュ コマンドは、ベスト プラクティスのプロンプト パターンをカプセル化します。

コア コンポーネント

GitHub Spec Kit には、次のコア コンポーネントが実装されています。

コンポーネント 目的
specify CLI (コマンドラインインターフェース) 仕様書駆動型プロジェクトを初期化し、管理します。
Markdown アーティファクト ファイル constitution.md、 spec.md、 plan.md、 tasks.md 開発を推進します。
スラッシュ コマンド /speckit.specify、 /speckit.plan、 /speckit.tasks、GitHub Spec Kit ワークフローを呼び出 /speckit.implement 。

AI エージェント

GitHub Spec Kit では、GitHub Copilot、Claude Code、Cursor、Windsurf、Amazon Q Developer などの AI エージェントがサポートされています。 各エージェントは、基になる同じ成果物ファイルを使用しながら、特定のプロンプト形式で書式設定されたテンプレートを受け取ります。

機能追跡の環境変数

GitHub Spec Kit では、環境変数を使用して、現在開発中の機能を追跡します。 SPECIFY_FEATURE変数は、アクティブな機能ディレクトリを示します。

Git ベースのワークフローでは、GitHub Spec Kit はブランチ名からこの機能を推論します。 ブランチ feature/document-uploadを使用している場合、GitHub Spec Kit は自動的に features/document-upload/ ディレクトリで動作します。

Git 以外のワークフローまたは手動機能の仕様の場合は、環境変数を明示的に設定します。

$env:SPECIFY_FEATURE = "001-document-upload"

この設定は、Git ブランチに関係なく、 features/001-document-upload/ ディレクトリ内の成果物の読み取りと書き込みを GitHub Spec Kit に指示します。

この機能追跡により、 /speckit.planを呼び出すと、さまざまな機能の仕様を混在させずに、AI が現在の機能の正しい spec.md ファイルを読み取ります。

GitHub Spec Kit と Git ワークフローの統合

GitHub Spec Kit は、いくつかのメカニズムを使用して、既存の開発プラクティスに統合されます。

バージョン管理の統合

すべての GitHub Spec Kit 成果物は、Git リポジトリに格納されているプレーンマークダウン ファイルです。 このアプローチには、いくつかの利点があります。

  • 変更の追跡: 仕様、プラン、またはタスクに対するすべての変更によって、Git コミットが作成されます。 要件の変更履歴を確認し、決定が行われた理由を理解し、問題のある変更を元に戻すことができます。

  • ブランチ ベースの開発: 仕様成果物と実装コードの両方を含む機能ブランチを作成します。 このアプローチにより、要件と実装の同期が維持され、コード レビューが包括的になります。レビュー担当者は、構築している内容 (仕様) と、その構築方法 (コード) の両方を確認します。

  • プル要求ワークフロー: 機能の pull request を送信するときに、コードの変更と共に spec.md、plan.md、および tasks.md を含めます。 レビュー担当者は、実装が仕様と一致し、仕様がプロジェクトの目標と一致することを確認します。

たとえば、新しい機能を実装する場合、機能ブランチには次のものが含まれます。

  • spec.md アップロード要件の定義。
  • plan.md Azure Blob Storage アーキテクチャについて説明します。
  • tasks.md 実装手順を一覧表示します。
  • この機能を実装するソース コード。
  • 仕様の準拠を検証するテスト。

この完全な図により、徹底的なレビューが可能になります。 校閲者がファイルが 50 MB に制限されている理由を疑問に思う場合は、spec.md を参照し、この要件が利害関係者の議論から来ていることがわかります。

AI アシスタント統合シナリオ - GitHub Copilot

GitHub Spec Kit は、Visual Studio Code のチャット インターフェイスを通じて GitHub Copilot と連携します。 specify init --ai copilotを実行すると、ツールキットによってワークスペースが構成され、/speckit.*コマンドが認識されます。

GitHub Copilot Chat を開き、「 /speckit.specify」と入力すると、GitHub Copilot は .github/prompts/ ディレクトリから定義済みのテンプレートにアクセスします。 これらのテンプレートは、AI の出力を構造化して、必要なすべての仕様セクション (ユーザー ストーリー、受け入れ基準、機能要件、非機能要件、エッジ ケース) を含めるのに役立ちます。

統合はシームレスであり、テンプレートを手動で管理することはありません。 GitHub Spec Kit は、テンプレートの読み込みとコンテキスト挿入を自動的に処理します。 あなたの仕事は、機能の説明を提供し、明確な質問に答えます。 GitHub Copilot は、仕様の書式設定と完全性を処理します。

プロジェクト構造規則

GitHub Spec Kit では、一貫性のあるディレクトリ構造を使用して成果物を整理します。

my-project/
├── .github/
│   ├── agents/
│   └── prompts/
├── .specify/
│   ├── memory/
│   │   └── constitution.md
│   ├── scripts/
│   └── templates/
├── SourceCode/ 
│   └── ...
├── specs/
│   └── 001-document-upload-feature/
│       ├── plan.md
│       ├── spec.md
│       └── tasks.md

この構造体は、仕様成果物を同じリポジトリに保持しながら、実装コードから分離します。 機能には、開発順序を追跡するために順番に番号が付けられます (001、002、003)。

複数の機能に同時に取り組むチームの場合、各機能には、その完全な仕様、計画、タスクを含む独自のディレクトリがあります。 この分離により、混乱を防ぎ、競合のない並列作業が可能になります。

継続的なワークフローのサポート

GitHub Spec Kit では、コマンド チェーンによる反復的な開発がサポートされています。 初期仕様を生成した後、段階的に調整できます。

  1. 初期仕様の生成: /speckit.specify。
  2. ギャップを特定する: /speckit.clarify。
  3. 回答に基づいて仕様を更新します。
  4. 実装計画を作成する: /speckit.plan。
  5. 整合性の確認: /speckit.analyze。
  6. タスクの生成: /speckit.tasks。
  7. インクリメンタル実装: /speckit.implement。

要件が変更された場合は、いつでも以前のフェーズに戻り、成果物を更新し、ダウンストリーム成果物を再生成できます。 タスクの生成後に関係者がファイル サイズの制限に関する考えを変えた場合は、spec.md を更新し、アーキテクチャへの影響を反映するように plan.md を再生成し、更新された検証手順で tasks.md を再生成してから、実装コードを更新します。

この柔軟性は、要件が進化する実際の開発をサポートします。 仕様優先のアプローチでは、ドキュメントを更新せずにコードに修正プログラムを適用するのではなく、変更が体系的に伝達されるようにします。

GitHub Spec Kit のオプションの拡張機能コマンドを活用する

GitHub Spec Kit には、コア ワークフロー コマンド以外にも、仕様の品質と一貫性を強化するオプションのコマンドが用意されています。

ギャップ分析に /speckit.clarify を使用する

/speckit.clarify コマンドは、仕様を分析して、あいまいさ、不足している詳細、および指定されていないエッジ ケースを特定します。 初期仕様を生成した後、このコマンドを呼び出して、AI に明確な質問を依頼します。

AI によって仕様がレビューされ、次のような質問が生成されます。

  • "仕様では、ファイルのアップロードに言及していますが、同時アップロードの最大数は指定されていません。 制限が必要ですか?
  • "ネットワーク障害のエラー処理が指定されていません。 アップロード接続が失われた場合はどうすればよいですか?
  • "仕様にはファイルの検証が必要ですが、検証エラー メッセージは指定されていません。 ユーザーには何が表示される必要がありますか?

各質問について、AI は多くの場合、ギャップに対処する方法について複数の選択肢を提供します。 オプションを選択するか、カスタム回答を指定すると、AI によって仕様が適宜更新されます。

この対話型の絞り込みでは、実装が開始される前に問題がキャッチされます。 これは、経験豊富なアナリストにスペックをレビューして、見逃した内容を指摘してもらうようなものです。

整合性検証に /speckit.analyze を使用する

/speckit.analyze コマンドは、アーティファクト間の整合性チェックを実行します。 プランがすべての仕様要件を実装していること、タスクがすべてのプラン要素をカバーしていること、およびすべてが構成に合っていることを確認します。

plan.md と tasks.md を生成した後、実装を開始する前に、このコマンドを実行します。 AI は不整合を識別します。

  • "Plan は PostgreSQL を使用して提案しますが、構成には Azure SQL Database が必要です。"
  • "仕様には監査ログが必要ですが、計画ではログの実装は記述されていません。"
  • "タスク リストでは、プランに記載されているデータベース移行スクリプトが省略されています。"

識別された各不整合は、実装またはコード レビュー中に発生する問題です。 分析フェーズ中に検出すると、手戻りを防ぐことができます。

品質検証に /speckit.checklist を使用する

/speckit.checklist コマンドは、仕様に基づいてカスタム品質チェックリストを生成します。 これらのチェックリストは、要件の完全性、明確さ、一貫性 ("英語の散文の単体テスト" など) を検証するのに役立ちます。

AI は仕様を分析し、検証の質問のチェックリストを生成します。

  • "すべてのユーザー ストーリーに対応する受け入れ条件がありますか?
  • "すべてのエラー シナリオに特定のエラー メッセージが記載されていますか?
  • "非機能要件には測定可能な成功基準が含まれていますか?
  • "外部の依存関係はすべて明示的に一覧表示されていますか?

チェックリストを使用して、各質問に回答します。 "いいえ" の回答は、対処する必要がある仕様のギャップを示します。

この自己レビュー プロセスにより、利害関係者と共有したり、実装に進んだりする前に、仕様の品質が向上します。

さまざまな開発シナリオに GitHub Spec Kit を適用する

GitHub Spec Kit では、新しい機能をゼロから構築する以外にも、さまざまな開発シナリオがサポートされています。

グリーンフィールド開発

何もないプロジェクトから始まる新しいプロジェクトでは、GitHub Spec Kit は高度な製品ビジョンを具体的な実装に変換することに優れています。 まず /speckit.constitution プロジェクトの原則を確立し、アプリケーションを繰り返しビルドするときに各機能に対して /speckit.specify を使用します。

このシナリオは、GitHub Spec Kit の主要なユース ケースです。ワークフローは、まだ存在しないものを作成する 0 から 1 の開発用に設計されています。

ブラウンフィールドの機能強化

既存のアプリケーションの場合は、GitHub Spec Kit を使用して、既存のコードベースとの一貫性を維持しながら新機能を追加できます。 構成では、既存のアーキテクチャ パターンと制約を文書化します。 新しい機能仕様では、これらの確立されたパターンが参照されます。

ドキュメントアップロード機能を既存の従業員ポータルに追加する場合、仕様では、既存の React フロントエンド、.NET バックエンド、および Azure インフラストラクチャが認識されます。 この計画では、別の実装を提案するのではなく、新しい機能を現在のアーキテクチャと統合する方法を示します。

リファクタリングとモダン化

GitHub Spec Kit では、目的の終了状態を仕様として扱うことで、リファクタリング作業をガイドできます。 リファクタリングされたコードで達成すべき内容 (構造が改善された同じ機能) を文書化し、リファクタリング アプローチの計画を作成し、増分変更のタスクを生成します。

リファクタリングに対するこの構造化されたアプローチは、部分的に動作するコードでリファクタリングを開始し、プロセスの途中で失われるという一般的な問題を防ぎます。

探索的開発

複数の潜在的なアプローチを検討している場合は、GitHub Spec Kit を使用して、同じ仕様から複数のプランを生成します。 安定した仕様は達成したいものを表し、異なる計画では異なる技術的アプローチを検討します。

同じアップロード仕様から、Azure Blob Storage を使用して 1 つのプランを生成し、もう 1 つのプランを Azure Files を使用して生成できます。 両方を実装し、結果を比較し、想定ではなく実際のエクスペリエンスに基づいてより優れたアプローチを選択します。

概要

GitHub Spec Kit は、構造化されたワークフロー、永続的な成果物、再利用可能な AI コマンド パターンを統合することで、スペック駆動型の開発を可能にする強力なツールキットです。 仕様を動作する実装に変換するための体系的なアプローチを提供することで、GitHub Copilot などの AI コーディング アシスタントを使用する方法を変革します。 GitHub Spec Kit を使用すると、要件とコードの整合性を確保し、意思決定の追跡可能性を維持し、開発チーム間のコラボレーションを強化できます。