👩‍🔬

spec-kit が作成するファイルを眺めてみた

に公開
speckit
tech

はじめに

GitHub が最近 spec-kit を発表した。

spec-kit がやっていることを知るために、spec-kit が最初に作成するファイルを一つずつ追ってみたので記録として残しておく。

プロジェクト作成

まずは以下のコマンドでプロジェクトを生成する。

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

spec-kit では GitHub Copilot, Claude Code, Gemini CLI が選べる。この記事では、GitHub Copilot を選択する。

すると以下のようなファイルが生成される。

.
├── .github
│   └── prompts
│       ├── plan.prompt.md
│       ├── specify.prompt.md
│       └── tasks.prompt.md
├── memory
│   ├── constitution_update_checklist.md
│   └── constitution.md
├── scripts
│   ├── check-task-prerequisites.sh
│   ├── common.sh
│   ├── create-new-feature.sh
│   ├── get-feature-paths.sh
│   ├── setup-plan.sh
│   └── update-agent-context.sh
└── templates
    ├── agent-file-template.md
    ├── plan-template.md
    ├── spec-template.md
    └── tasks-template.md

各ファイルを読んでみる。

.github.prompts/

specify.prompt.md

このファイルはGitHub Copilot の プロンプトファイル。

プロンプトファイルは、GitHub Copilot に具体的にどんな作業をしてほしいかを定義するもので、.github/prompts/hoge.prompt.md という形式でファイルを置くと、GitHub Copilot Chat で、/hoge のようにスラッシュコマンドとして使えるとのこと。

https://kiririmode.hatenablog.jp/entry/20250616/1750039165

specify.prompt.md で定義しているプロンプトは、/specify で、Spec-Driven Development（仕様駆動開発）の最初のステップ「新機能の仕様作成とブランチ生成」を自動化するコマンド。

  1. まずは scripts/create-new-feature.sh を実行し、新しいブランチ名と仕様ファイルの絶対パスを取得。このスクリプト内で、ブランチの作成と、仕様ファイル (spec/{BRANCH_NAME}/spec.md) の作成を行っている。

  2. spec-template.md を読み、必要なセクションや構成を把握し、spec/{BRANCH_NAME}/spec.md に仕様を書き込む。

plan.prompt.md

このファイルは/plan というプロンプトを定義していて、Spec-Driven Developmentの「実装計画」フェーズを自動化している。

  1. まずは scripts/setup-plan.sh を実行し、

    • 機能仕様ファイルパス（spec/{BRANCH_NAME}/spec.md）
    • 実装計画ファイルパス（spec/{BRANCH_NAME}/plan.md）

    などを取得。このスクリプトが spec/{BRANCH_NAME}/plan.md ファイルを作っている。

  2. spec/{BRANCH_NAME}/spec.md を読み、機能要件・ユーザーストーリー・受入基準・技術的制約などを把握

  3. constitution.md を参照し、プロジェクトの憲法（開発ルールや原則）を理解

  4. spec/{BRANCH_NAME}/plan.md の手順に従って計画を進める。各フェーズで成果物（research.md, data-model.md, contracts/, quickstart.md, tasks.md など）が生成される。

tasks.prompt.md

このファイルは、Spec-Driven Development の「タスク分解・管理」フェーズを自動化している。

  1. まずは scripts/check-task-prerequisites.shを実行し、plan プロンプトで作成したドキュメントのパスを取得している。

  2. 各ドキュメントを読んで把握

  3. tasks-template.md をベースにして、各ドキュメントから具体的なタスクを生成し、並び替えなどを行って、spec/{BRANCH_NAME}/tasks.md を作成する。

memory/

constitution.md

プロジェクト全体の憲法（= 開発ルールや原則）として機能するドキュメント、らしいのだが、このファイル自体はテンプレートのようになっていて、この雛形からプロジェクトごとの憲法を作る必要がありそう。ただ試してみたが具体的な憲法は生成されなかった。この辺りは謎。

# [PROJECT_NAME] Constitution
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->

## Core Principles

### [PRINCIPLE_1_NAME]
<!-- Example: I. Library-First -->
[PRINCIPLE_1_DESCRIPTION]
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->

...

constitution_update_checklist.md

プロジェクトの「憲法（constitution.md）」を更新する際に確認すべき項目や手順をまとめたチェックリスト。

このファイルがいつ、どこから読み込まれるのかは分からなかった。

scripts/

create-new-feature.sh

specify.prompt.md で実行指示をされているシェルスクリプト。このスクリプト内で、ブランチの作成と、仕様ファイル (spec/{BRANCH_NAME}/spec.md) の作成を行っている。

setup-plan.sh

plan.prompt.md で実行指示されているシェルスクリプト。このスクリプトが spec/{BRANCH_NAME}/plan.md ファイルを作っている。

check-task-prerequisites.sh

tasks.prompt.md で実行指示されているシェルスクリプト。plan プロンプトで作成したドキュメントのパスを取得して出力する。

common.sh

create-new-feature.sh、setup-plan.sh、check-task-prerequisites.sh で共通で使うユーティリティ処理が書かれている。

get-feature-paths.sh

ブランチ名やドキュメントのパスを出力するスクリプト。これがどこから使われているかは不明だった。

update-agent-context.sh

spec/{BRANCH_NAME}/plan.md から実行されるスクリプト

ちょっと複雑でぱっと見、何をやっているか分からなかったが、spec/{BRANCH_NAME}/plan.md に基づいて、各種エージェント向けルールファイル（CLAUDE.md, GEMINI.md, .github/copilot-instructions.md）を作成、更新している。

templates/

テンプレートファイルはそのまま雛形となるファイル。
spec-template.md ... spec.md のテンプレート
plan-template.md ... plan.md のテンプレート
tasks-template.md ... tasks.md のテンプレート
agent-file-template.md ... 各種エージェント向けルールファイルのテンプレート

まとめ

ざっと spec-kit が生成するファイルを眺めてみて、spec-kit がどうタスクを進めているのか大まかに把握できた。

ユーザが /specify に与えた初期のプロンプトから、ある程度品質が担保された仕様作成・計画立案・タスク分解ができるように工夫がされているように感じた。

  • spec.md、plan.md、tasks.md を生成するためのテンプレートがある。

  • 事前に用意したスクリプトによってファイルの作成や、前段のステップで作成されたドキュメントのパスの取得がされており、LLMが確実にタスクをこなせるようになっている。

よく分からなかった点としては、

  • テンプレートによって生成された plan.md の最初の段階で update-agent-context.sh スクリプトを実行するように仕込まれていたが、試しに生成したプロジェクトでは、タスクの中に update-agent-context.sh の実行が含まれていなかった。この辺りはタスクの規模にもよるのだろうか。

  • constitution.md や constitution_update_checklist.md がどう使われているのか不明だった。

Discussion