SpecPilot

SpecPilot

SpecPilotは、Claude Code、Cursor、ChatGPTなどのAIコーディングエージェント向けの、仕様駆動開発（SDD）CLIです。.specs/ディレクトリを初期化、検証、同期し、AIを活用したコーディングがコードベースから逸脱せず、常に最新の要件、アーキテクチャ、タスクの仕様に基づいて進められるようにします。

MCP サーバー

エディター内で作業を完結させたい場合は、SpecPilotをリモートMCPサーバーとしても実行できます。Claude Code、Cursor、Copilotがオンボーディングをすべて行い、リポジトリから推測できることには回答し、推測できないことだけを質問します。

claude mcp add --transport http specpilot https://init.specpilot.dev/mcp

次に、エージェントに「このプロジェクトをSpecPilotでオンボーディングして」と依頼してください。

Cursor、VS Code、その他のクライアントでは、HTTP（ストリーミング対応）サーバーとして追加してください。

{
  "mcpServers": {
    "specpilot": {
      "type": "http",
      "url": "https://init.specpilot.dev/mcp"
    }
  }
}

インストール不要、APIキー不要です。セットアップの詳細については、https://specpilot.dev/mcp-setupをご覧ください。

specpilot serveではローカルMCPエンドポイントも提供されるため、AI IDEからこのマシンの仕様を読み込んだり、タスクを追加・移動したり、フォルダーをセットアップしたりできます。以下のローカルMCPエンドポイントをご覧ください。

クイックスタート

# Install globally
npm install -g specpilot

# Create a new project
specpilot init my-project --lang typescript --framework react

# Add specs to existing project
cd existing-project
specpilot add-specs

# Validate specifications
specpilot validate

🚀 AIを使って仕様を作成する次のステップ

プロジェクトを作成したら、次の手順に従ってAIを使って仕様を作成します。

1. 生成されたガイドを開く：.specs/README.mdで詳しいガイダンスを確認します
2. オンボーディングプロンプトをコピーする：.specs/development/onboarding.mdのプロンプトを使います
3. AIエージェントに貼り付ける：ChatGPT、Claude、またはその他のAIアシスタントに貼り付けます
4. 生成された仕様ファイルを確認する：AIが生成した要件とアーキテクチャを確認します

このAI支援のアプローチにより、プロジェクトのニーズに合わせた、包括的で高品質な仕様を作成できます。

コマンド

コマンド	説明
init <name>	新しいSDDプロジェクトを初期化します
init <name> --dry-run	書き込みを行わず、作成されるファイルをプレビューします
add-specs	既存のプロジェクトに仕様を追加します
validate	仕様ファイルを検証します
archive	サイズが大きくなったprompts.md / tasks.mdのエントリーをアーカイブします
backfill	不足している指示、スラッシュコマンド、Claude Codeスキルを補完します
list	利用可能なテンプレートを表示します
migrate	旧形式の.project-specフォルダーを変換します（通常は不要です）
refine [desc]	プロジェクトの仕様を調整します
serve [folders...]	このプロジェクト、指定した各フォルダー、または~/.specpilot/projects.jsonに記憶されたプロジェクト（提供または開いたすべてのプロジェクト。.specs/がある場合は起動時に再度開かれます）の.specs/を対象に、ローカルWeb UIを提供します。また、.specs/がなく、記憶されたプロジェクトもないフォルダーでは、ページから開くまでプロジェクトを開かずに提供します（読み取り専用でない場合は、タスクの移動、新しいタスクの作成、コマンドファイルの「すべて再生成」、.specs/のないフォルダーのセットアップビューを利用できます）

ヒント — コマンドのエイリアス： すべてのコマンドには、正式名称の代わりに使える短縮エイリアスがあります。 init → i  ·  validate → v  ·  migrate → m  ·  list → ls  ·  refine → ref  ·  archive → ar  ·  add-specs → add  ·  backfill → bf 例：specpilot i my-appはspecpilot init my-appと同じです。

コマンドごとのオプション

コマンド	オプション
init	--lang · --framework · --dir · --specs-name · --no-prompts · --dry-run
validate	--fix · --verbose
migrate	--from · --to · --backup
list	--lang · --verbose
refine	--update · --no-prompts
archive	--dry-run · --force
add-specs	--no-analysis · --no-prompts
backfill	--dir · --specs-name · --dry-run · --no-prompts
serve	--port · --poll · --read-only · --open · --no-mcp · --stop

フラグの詳細とデフォルト値については、specpilot <command> --help を実行してください。

使用例

# Initialize with specific language/framework
specpilot init api --lang python --framework fastapi

# Preview files that would be created without writing anything
specpilot init api --dry-run

# Refine specifications
specpilot refine "REST API for user management" --update

# Validate with auto-fix
specpilot validate --fix

specpilot serve

プロジェクトの .specs/ をローカルの Web UI で提供します。ここでは、タスクを Backlog、Current Sprint、Review の間で移動したり、エージェントが完了したタスクを承認または差し戻したり、新しいタスクを追加したり、SpecPilot のコマンドファイルを最新の状態に更新したり、まだ .specs/ がないフォルダーに設定したり、ほかのプロジェクトを開いたりできます。フォルダーを指定しない場合は、実行元のプロジェクト（.specs/ を含むフォルダー）が提供されます。フォルダーを1つ以上指定すると、それらがすべて1つのサーバーから提供されます。または、ページから後で開くこともできます。停止するには Ctrl+C を押してください。

specpilot serve                  # this project, at http://127.0.0.1:4321
specpilot serve --port 5000 --open
specpilot serve ../api ../web    # two projects on one server; switch in the left rail
specpilot serve ../new-project   # no .specs/ there yet: the page sets it up (or `specpilot serve .`)
specpilot serve --stop           # stop the server on port 4321 from another terminal (--port for another)

オプション	デフォルト	説明
--port <n>	4321	リッスンするポート（127.0.0.1 のみ）
--poll <ms>	1000	変更検出間隔（ミリ秒単位、最小値は250）。ポーリングはページが開いている間のみ実行されます
--read-only		タスクの移動、新しいタスクの追加、Setup ビューでの操作、フォルダーを開く操作、レジストリへのアクセスはできません。UI は読み取り専用となり、ドラッグ用ハンドル、Add ボタン、Archive ボタン、書き込み用ルートは表示されません
--open		デフォルトのブラウザーで UI を開きます
--no-mcp		/mcp のローカル MCP エンドポイントを含めません（デフォルトでは AI IDE 用に提供され、Home および Setup ビューに Connect Your AI IDE カードが表示されます。下記参照）。--mcp も引き続き受け付けられますが、何も変更しません
--stop		--port（デフォルトは4321）でこのマシン上で実行中の SpecPilot サーバーを、Ctrl+C を押した場合と同じように停止します。他のオプションは指定できません。--read-only サーバーはこの方法では停止できません。ターミナルで Ctrl+C を押してください

• 複数のプロジェクト：フォルダーはいくつでも指定できます。.specs/ のないフォルダーも提供され、その場合は（下記の）セットアップビューが表示されます。コマンドラインで指定した順に 0 から番号が付き（../api はプロジェクト 0、../web はプロジェクト 1）、その番号がサーバーの /api/ ルートにある ?project=<n> と、最初以外の各プロジェクトのページリンクの先頭にある #1/... に使われます（番号がない場合はプロジェクト 0 です）。各プロジェクトは、それぞれ独自のタスク、ファイル、ライブリロードを保持します。移動によって変更されるのは、そのプロジェクトの tasks.md だけです。（下記の）ページから開いたフォルダーには次の番号が割り当てられます。サーバーの実行中に番号が変わることはなく、1 台のサーバーで保持できるプロジェクトは最大 20 件です。
• 終了：左側のレール下部にある電源ボタンを押して確認すると、Ctrl+C や specpilot serve --stop と同様にサーバーを停止します（実行中のクローンがあれば、先に停止してクリーンアップします）。その後、ページに SpecPilot が停止したことが表示されます。他の開いているページも更新されなくなります。--read-only では表示されません。
• タスクの移動：行をドラッグするか、Alt+Up/Down で並べ替え、Alt+Left/Right で Backlog、Current Sprint、Review の間を移動します（Backlog と Current Sprint はどちらの方向にも移動でき、Current Sprint と Review の間も行き来できます）。またはカードのメニューを開き（右クリック、カード上の ⋯ ボタン、または Shift+F10）、Move to <lane>（そのレーンの末尾、または <lane>, top）、Move up、Move down を選択します。メニューには Open details と Copy ID もあります。移動によって .specs/planning/tasks.md の 1 行だけが変更され、それ以外は何も変更されません。元に戻す操作もできます。Completed と Won't do の行は移動できません。ページの読み込み後にディスク上のファイルが変更されていた場合は、移動を拒否してページを再描画します。移動を無効にするには --read-only を指定して起動してください。
• 作業中の警告：ページからの移動と Archive では、プロジェクトが main または master 以外のブランチにある場合、または .specs/ 内のファイルが直近 2 分以内にディスク上で変更されていて、その変更がページから行われたものではない場合（エージェントやエディターが作業中の場合）、最初に確認を求めます。ダイアログには起こりうることが表示されます（変更はブランチ上の作業に含まれてマージ時に競合する可能性があること、古い tasks.md をエージェントが保存すると変更が取り消される可能性があること）。Cancel または Move anyway を選べます。Archive では、この確認項目が独自の一覧に追加されます。ページが把握するのは、読み込み後に確認した内容だけです。Approve と Send back では確認されません。
• Review レーン：.specs/planning/tasks.md の ## Review には、完了扱いにする前に確認する、完了済みの作業を記載します。レーンの見出しには Review HITL（human-in-the-loop）と表示されます。AI エージェントは完了した作業を Current Sprint から Review に移動し、Completed には直接移動しません（生成される指示ファイルと MCP サーバーにもそのように記載されています）。Review カードを開くと、Approve は行に Approved <date> を追記して Approved チップを表示し、パネルに次の手順を表示します（エージェントに仕上げを依頼してください。Copy prompt でその文をコピーできます）。Send back はメモ入力欄（What needs fixing? (optional)、最大 200 文字、Cmd/Ctrl+Enter で送信、Escape でキャンセル）を開き、行に Sent back <date>: <note> を追記して、その行を Current Sprint の先頭に移動します。これにより、エージェントは次にその作業に取りかかります。どちらの操作も元に戻せます。パネルの History には以前のメモが一覧表示されます。ドラッグまたは Alt+← で Review から移動する操作は、メモなしの Send back として扱われるため、承認済みの行を戻すと承認状態ではなくなります。行に Approved と記載された後、エージェントが Completed の項目（番号、CD ID、コミット）を手作業で記入します。SpecPilot が記入することはありません。ファイルに ## Won't do がある場合、そのセクションは Completed の後にある読み取り専用レーンとして表示され、開くまでは折りたたまれて帯状に表示されます。--read-only では無効です。
• Type と Priority：Backlog、Current Sprint、Review が | ID | Type | Priority | Description | テーブル（init が作成する形式）の場合、各カードの最下行に Priority（P1～P3）と Type（feat、bug、chore）が表示されます。タスク詳細では、それぞれを 2 つのボタングループで設定でき、変更はまとめて保存されます。New Task でも設定できます。| ID | Description | の形式のテーブルも従来どおり動作します。3 つすべてがこの形式の場合、列の追加方法を示すメモ（Copy prompt）がレーンの上に表示されます。また、3 つのレーンの形式が異なる場合は警告が表示されます。Type または Priority を持つ行は、これらの列がないテーブルには移動できないためです。--read-only では無効です。
• セクション見出し：.specs/planning/tasks.md に ## Backlog、## Current Sprint、## Review、## Completed のいずれかがない場合、レーンの上に警告が表示されます。警告には空のレーン、ファイルに代わりに存在する内容、修正方法（ファイルを編集してください。セクションを参照する内容もすべて追従するため、AI IDE に依頼するのがおすすめです）が示され、Open tasks.md in VS Code と Copy prompt も表示されます。ボードが認識しない ## 見出しがある場合、その行はここには表示されないというメモが表示されます。既知のセクションにタスクがテーブルではなく通常の行やリストとして記載されている場合は、そのレーンには何も表示されないことと、テーブルに変換する方法を説明する警告が表示されます。警告はセッション中、1 行の帯状表示に折りたためます。メモは見出しが変更されるまで表示されます。specpilot validate は見出しがない場合に警告し、--fix は曖昧さのない別名を修正します。
• Commands と Skills：各ビューでは、ファイルが 2 つのグループに分けて一覧表示されます。From SpecPilot には、内容が SpecPilot のリリース済みバージョンと一致する specpilot-* コマンド（.claude/commands/ と .github/prompts/ 内）と、project.yaml に基づく SpecPilot 独自の生成内容のままである specpilot-project スキルが表示されます。それ以外は、編集した specpilot-* コマンドを含め、すべて Yours に表示されます。Commands の From SpecPilot 見出しにある Regenerate All を実行すると、コマンドファイルについて specpilot backfill と同じ処理が行われ、それ以外は何も行われません。プロジェクトに指示ファイルがある各 IDE について、すべての IDE のコマンドフォルダーに、不足している specpilot-* コマンドを追加し、未編集のものを現在のバージョンに更新します。ページに表示されないもの（.cursor/commands/、.windsurf/workflows/、.agent/workflows/、.codex/prompts/）も対象です。また、スキルが SpecPilot 独自の生成内容のままであれば、.specs/project/project.yaml から .claude/skills/specpilot-project/SKILL.md（name、language、framework、platforms、package manager、test framework、repository URL、license）を再生成し、存在しない場合は追加します。編集済みのスキルや、project.yaml に値がなくなったためその値から生成されたスキルとは一致しなくなったものは、does not match SpecPilot's render of project.yaml という理由とともにそのまま保持されます。編集済みファイル、リンク、リンク先フォルダー内のファイル、独自のコマンドとスキル、指示ファイル、.specs/ には書き込みません。処理内容は実行のたびにグループの上に表示されます。更新、追加、理由付きで保持されたファイル、ページに表示されないフォルダーが示されます。
• New Task：Backlog または Current Sprint のレーン見出しにある + Add ボタンを押すと、そのレーン用の小さなフォームが開きます。フォームには説明を入力し、その上に行に割り当てられる ID が表示されます。SpecPilot は .specs/planning/tasks.md 内のそのセクションのテーブル末尾に | <ID> | <description> | という行を 1 つ追加し、ファイル内のそれ以外は変更しません。ID は次に利用可能なものです。Backlog には BL-###、Current Sprint には CS-### が割り当てられ、tasks.md と tasks-archive.md で使用されている最大の番号の次になります（ID 列と先頭タグの ID のみが対象で、説明内にある ID は対象外です。欠番は埋めません）。説明は、入力したとおりに Markdown も含めて記録され、ラベルや日付は追加されません。改行、制御文字、|、末尾の \ を含む説明、または 4000 文字を超える説明は、理由とともに拒否されますが、入力内容はフォームに残ります。新しい行が選択され、詳細パネルに表示されます。ページの読み込み後にディスク上のファイルが変更されていた場合、何も追加せずページを再描画します。タスクの移動と同じ保護が適用されます。--read-only では無効です。
• Completed の古い行をアーカイブ：Completed レーンの見出しに Archive ボタンがあります。これを押すと、実行内容と適用される確認項目がそれぞれの状態とともに表示されるダイアログが開きます。確認項目はブランチ（specpilot archive の警告と同様に、マージ後、main または master でアーカイブ）と ## Completed の 40 行制限（specpilot validate の警告）で、移動対象の行数も表示されます。警告がある項目にはチェックボックスがあり、すべてにチェックを入れると Archive が有効になります。実行すると、そのセクションについて specpilot archive と同じ処理が行われます。最も古い行が日付入りのブロックにそのまま .specs/planning/tasks-archive.md の末尾へ移動し、新しい 20 行は残り、どちらのファイルのそれ以外も変更されません。レーンには残りの行が表示されます。制限以内でも、制限の確認項目にチェックを入れればアーカイブできます。prompts.md の処理は specpilot archive に任せます。タスクの移動と同じ保護が適用されます。--read-only では無効です。
• セットアップビュー：.specs/ のないフォルダー（指定したもの、ページから開いたもの、クローンしたもの）では他のビューの代わりにセットアップビューが表示され、Home の Start a New Project でも、Project name と Parent folder（Browse… 付き）を指定してセットアップビューを表示できます。セットアップは AI IDE が行います。コードを読み、わかる範囲で回答し、残りをユーザーに質問します。ビューには 3 つのステップで手順が表示されます。1 Connect your AI IDE：Copy ボタンと状態表示付きのこのサーバーの設定が表示され、IDE が /mcp に接続するまで Waiting for a connection、接続後は Connected · <the IDE's name> と表示されます。2 Tell it what to do：IDE に貼り付ける 1 行の指示（Set up SpecPilot for <folder> または Start a SpecPilot project called <name> in <parent>）が表示されます。3 Progress：IDE の呼び出しに応じて更新される 4 行（Read the code、Answer the questions、Write the files、Validate）が表示されます。.specs/ が作成されるとページがプロジェクトを開きます。Finish ボタンはありません。新規プロジェクトの場合、ページは入力中に名前と親フォルダーを確認し、<parent>/<name> をこのサーバーの実行中に新規プロジェクトを作成できる唯一の場所として記憶します。IDE が作成するまで何も作成されず、フォルダーが存在しないか空である必要があります。MCP がない場合は、そのことと再起動方法がビューに表示されます。specpilot add-specs（既存のフォルダーの場合）または specpilot init（新規の場合）を使うと、同じ質問がターミナルに表示されます。カレントディレクトリはセットアップの対象になりません（起動時に .specs/ が必要なためです。specpilot serve . で指定します）。セットアップが中断された場合、次に specpilot serve を実行すると、残された .specpilot-setup-<id>/ フォルダー（マーカーファイルで識別されるそのフォルダーだけ）が削除されます。
• Home：左側のレール上部にあるロゴ、プロジェクト一覧の下にある + タイル（または h キー、または #home）を押すと、「Your specs, as a board.」、Open a Project Folder ボタン、Recent projects（パス、最終アクセス時刻、すでに開いているプロジェクトの場合は git ブランチ）が表示されます。項目をクリックすると開き、Remove from list を選ぶと一覧から削除できます（フォルダー自体には変更を加えません）。specpilot serve は最初のプロジェクトの Tasks ビューで起動します（最初に指定したフォルダー、またはそれがない場合は、最後に開いたプロジェクト）。.specs/ のないフォルダーで、記憶されたプロジェクトもない場合は、プロジェクトを開かずに Home を表示します（ターミナルには No .specs/ folder in <folder> と表示されます。そのフォルダー自体は提供されません。specpilot serve . で指定します）。--read-only では Home がなく、.specs/ のないフォルダーの場合は引き続き終了コード 1 で終了します。
• ページからプロジェクトを開く：Home の Open a Project Folder を押すとシートが開きます（Clone a Repository を押した場合は Clone タブが開きます）。フォルダーのパス（/Users/you/project または ~/project）を入力するか、Browse… を押してシステムのフォルダーダイアログで選択し（macOS、zenity または kdialog を使う Linux、Windows）、Open を押します。フォルダーは他のプロジェクトと一緒に提供され、.specs/ がない場合はセットアップビューが表示されます。この方法で開いたフォルダーは次回から Recent projects に表示され、~/.specpilot/projects.json に記録されます（パス、最終アクセス時刻、ピン留めフラグ、最大 50 件。このファイルはプロジェクトを初めて提供したときに作成され、提供または開いたすべてのプロジェクトが追加されます）。起動時には、指定されたフォルダーの後に、.specs/ がある記憶済みプロジェクトが、ピン留めされたもの、新しく開いたものの順で、合計最大 20 件まで再度開かれます（ターミナルには Reopened <k> remembered projects from ~/.specpilot/projects.json. と表示されます）。.specs/ のないフォルダーはクリックできる状態で一覧に残り、存在しないフォルダーはスキップされます。再度開いてもファイルは変更されません。Remove from list はフォルダーに変更を加えず、一覧から削除します。Browse… はパスを入力するだけで、Open を押すまで開きません。Clone タブの Parent folder とセットアップビューの Parent folder（Start a New Project）にも同じ Browse… ボタンがあり、フィールドに入力するだけです。macOS で確認済みです。フォルダーを選択するとフィールドに入力され、Open を押すと開きます。Browse… 時も Open 時も、~/Documents 内のフォルダーの場合を含め、プライバシーに関する確認は表示されません。Linux と Windows のダイアログはまだ手動確認していません。ホームフォルダー、ドライブのルート、すでに開いているフォルダーは拒否されます。読み取れない projects.json はそのまま保持され、ページとターミナルにその旨が表示されます。リクエストにはタスクの移動と同じ保護が適用されます。
• ページからリポジトリをクローン：Home の Clone a Repository（または同じシートの Clone タブ）では、リポジトリ URL、親フォルダー、フォルダー名を指定します（リポジトリ名を使う場合は空欄にします）。インストール済みの git clone を実行して、結果を開きます。リポジトリに .specs/ がある場合は Tasks ビューで、ない場合はセットアップビューで開きます。受け付ける URL は https://host/path、git@host:path、ssh://host/path です。https URL にユーザー名やパスワードを含めることはできません（ターミナルと同様に、git は認証情報ヘルパーと ssh キーを使います）。そのため、Azure DevOps の場合は org@ の部分を省いてください。サブモジュールはクローンされず、ブランチや深さのオプションもありません。作成先フォルダーは存在しないか、空である必要があります。親フォルダーには Start a New Project と同じ規則が適用されます。URL を入力または貼り付けると、自分で入力するまでは Folder name にリポジトリ名が入力されます。クローン中は経過時間が表示され、git が報告した後は、git のステージと進捗率が表示されます（Receiving objects 42% · 0:13、続いて Resolving deltas と Updating files）。それまで、または git が進捗を報告しない場合は、動くバーが表示されます。git が応答待ちになるような質問をすることはありません。取得できないログインが必要なリポジトリの場合、git のエラーメッセージが表示されます。たとえば、最後の fatal: 行とその直前の行として Host key verification failed. fatal: Could not read from remote repository. が表示されます。クローンは 10 分後に停止します。ページから ssh ホストキーを承認することはできません。接続したことのないホストの場合は、ターミナルで ssh -T git@host を一度実行してから、再度クローンしてください。ssh の設定はそのまま使われます。SpecPilot は macOS と Linux では ssh オプションを設定しません。同時に実行できるクローンは 1 つだけです。クローンが失敗、停止、またはキャンセルされた場合（Cancel、Escape、タブを閉じる、Ctrl+C）、ダウンロードしたものは削除されます。Ctrl+C の場合、サーバーは最大 5 秒間その処理を待ちます。PATH に git が必要です。SpecPilot がページのために別のプログラムを起動するのはこれが唯一で、ネットワークを使用するのもこれだけです。Windows では ssh がバッチモードに設定されます（GIT_SSH_COMMAND、GIT_SSH、core.sshCommand のいずれかを設定している場合を除く）。停止したクローンでは git のヘルパープロセスが終了まで残ることがあり、その場合、ヘルパーが使用中のファイルをクリーンアップできないことがあります。メッセージでその旨が表示されます。
• VS Code で開く：各プロジェクトビューの右上にあるアイコン（およびフォルダーがまだ存在する場合は、Home の Recent project 各項目の横にあるアイコン）は、そのプロジェクトのフォルダーへの vscode://file/ リンクです。ブラウザーから VS Code に渡され、VS Code が開く前に確認します。SpecPilot 自体は何も起動しません。VS Code がインストールされていない場合は何も起こりません。タスクの詳細パネルにある Open tasks.md in VS Code を押すと、そのタスクの行を指定して .specs/planning/tasks.md を開きます。VS Code は選択したウィンドウ（デフォルトでは最後に使ったウィンドウ）でファイルを開きますが、それがこのプロジェクトのウィンドウとは限りません。Insiders や別のエディターではなく、VS Code のみを開きます。すべての .specs/ ファイルのファイルビューと、Instructions、Commands、Skills ファイルの詳細パネルにも Open in VS Code があり、該当ファイルを開きます。
• AI IDE で開く：Open in VS Code の横にあるきらめきアイコンを押すと、選択肢がある場合に短いメニューが表示されます。Open in Cursor（cursor://file/）は、SpecPilot が Cursor 用に作成する .cursor/rules/specpilot.mdc がプロジェクトにある場合に表示されます。.specs/development/onboarding.md が存在する間は、Send onboarding prompt to Cursor を選ぶと、Cursor 独自のリンクを通じてプロンプトを Cursor のチャットに送信します（このマシン上で処理されます。Cursor は確認を求め、前面にあるウィンドウを使うため、最初に Cursor でプロジェクトを開いてください）。また、Cursor へのリンクがない Claude Code や他の IDE 用には、Copy onboarding prompt でコピーできます。プロンプトが Cursor のリンクで扱うには長すぎる場合（10,000 文字）は、代わりにコピーされます。これはプロジェクトビューにのみ表示され、Home の行には表示されません。
• それ以外は何も書き込みません：.specs/ のあるプロジェクトでは、そのプロジェクトの .specs/planning/tasks.md と、Regenerate All を通じて更新される specpilot-* コマンドファイルおよび specpilot-project スキルだけが、サーバーによる変更対象です。名前を指定した .specs/ のないフォルダーでは、セットアップによって新しいファイルが作成され、既存のファイルは変更されません。新規プロジェクトは、新しいファイルが入った 1 つの新規フォルダー（または空のフォルダー）です。クローンは、git clone によって内容が入れられる 1 つの新規フォルダー（または空のフォルダー）です。プロジェクト外で書き込まれるファイルは ~/.specpilot/projects.json だけです。それ以外は、リクエストごとに読み込まれます。
• ループバックのみ：127.0.0.1 のみにバインドされ、127.0.0.1:<port> または localhost:<port> 以外の Host ヘッダーは拒否されます（403）。
• ライブリロード：ページが開いている間、許可リストにあるファイルを --poll ミリ秒ごとに stat() で確認し、/api/events で変更されたパスを送信します。開いているページはその場で更新されます。
• 表示内容：.specs/、CLAUDE.md、AGENTS.md、.github/copilot-instructions.md、.claude/commands/、.claude/skills/、.github/prompts/ を、各ファイルに記載されたとおりに表示します。
• 制限事項：シンボリックリンクされたフォルダーを経由するパス、隠しファイル、node_modules は表示されません。タスクの移動と新しいタスクの作成は、1 行だけを正確に変更できない場合、近似処理ではなく拒否されます。たとえば、テーブルのないセクション（新規プロジェクトの [TODO]）、末尾の改行がないファイルで最終行に関わる移動、または有効な UTF-8 ではない tasks.md が該当します。サーバーが tasks.md に書き込むのと同じ瞬間にエディターが保存すると、その保存が上書きされることがあります。git を使えば復旧できます。VS Code は :<number> で終わるパスを行番号として読み取るため、プロジェクトフォルダー名がその形式で終わる場合（notes:12）、Open in VS Code からフォルダーを開けないことがあります。このリンク内の Windows パス（C:\…）は未テストです。Cursor のリンクは Cursor がインストールされたマシンでは未テストです。Windsurf 用のリンクはまだありません。.cursor/rules/specpilot.mdc の追加または削除は、このファイルが監視対象ではないため、すぐには反映されず、次回のページ更新時に表示されます。セットアップビューの Connected 状態には、接続時に IDE が送信する名前（clientInfo）が表示されます。この状態は両方の MCP リビジョンでテストリクエストを使って確認しましたが、すべての IDE で確認したわけではありません。セットアップツールが求める順序は MCP の instructions とツールの説明に含まれています。IDE が instructions をエージェントに表示するかどうかは IDE 次第であり、確認したのはテストリクエストのみです。このページを読み取れるローカルプログラムは、新規プロジェクトのフォルダーも登録できます。セットアップツールはエージェントが誤って別の場所に書き込むことを防ぎますが、すでにマシン上で実行中のソフトウェアは対象外です。

ローカル MCP エンドポイント（specpilot serve）

サーバーは http://127.0.0.1:<port>/mcp でも MCP に応答するため、このマシン上の Claude Code、Cursor などの AI IDE は、ページと同じチェックを通じて仕様を読み取り、タスクを追加または移動できます。デフォルトで有効です。無効にするには --no-mcp を指定して起動してください（その場合、再起動方法は Setup ビューに表示されます）。--mcp も引き続き受け付けますが、何も変わりません。

specpilot serve
# MCP endpoint: http://127.0.0.1:4321/mcp
# Add to your IDE's MCP settings: {"mcpServers":{"specpilot-local":{"type":"http","url":"http://127.0.0.1:4321/mcp","headers":{"X-SpecPilot-Token":"<token>"}}}}

ターミナル、Home の AI IDE を接続カード、または Setup ビューのステップ 1（Copy ボタン）からこの行をコピーし、IDE の MCP 設定に貼り付けるか、プロジェクト内の .mcp.json に追加して、.mcp.json を .gitignore に追加してください。

• ツール：specpilot_list_projects、specpilot_read_spec、specpilot_list_tasks、specpilot_new_task、specpilot_move_task、specpilot_validate_specs（--fix なし。書き込みは行いません）、specpilot_regenerate_commands。各ツールでは project インデックスを任意で指定できます。2 つのタスク書き込みツールには、specpilot_list_tasks が返した sha256 が必要です。その後に tasks.md が変更されている場合、書き込みは拒否され（「最後に読み取ってから変更されています」）、何も書き込まれません。開いているページにはライブリロードで変更が反映されます。
• セットアップツール：specpilot_setup_questions（パス）は、コード内で検出された内容とすべての質問を、選択肢および提案とともに返します。specpilot_setup_project（パス、回答、ユーザーが回答した項目）は、.specs/、指示ファイル、スキルを書き込み（新しいプロジェクトのフォルダーを作成）、specpilot validate を実行して、書き込んだファイルと結果を返します。ツールは全部で 9 つです。これらのツールは、ページでセットアップ中のフォルダーでのみ動作します。対象は、指定、オープン、またはクローンした .specs/ のないフォルダー、または Setup ビューで指定した新しいプロジェクトのフォルダーです。サーバーは IDE に処理の順序（質問、コードからの回答、残りの質問をユーザーに確認、書き込み、結果の報告）を伝えます。Setup ビューの Progress の行には、これらの呼び出しが反映されます。
• ページと同じ保護機能：ループバックのみ、Host チェック、トークン（誤った、または欠落した X-SpecPilot-Token には 403 を返します）、JSON のみ、64 KB、ページの読み取り許可リスト、ページの書き込み許可リスト、ページと IDE で共有する単一の書き込みロック。Web ページからのリクエスト（Origin がそれ以外の場合）は 403 で拒否されます。IDE は Origin を送信しません。クローンとプロジェクト一覧はツールではありません。
• プロトコルのリビジョン：同じ URL で、MCP 2026-07-28（ハンドシェイクなし。バージョン、Mcp-Method、Mcp-Name の各ヘッダーはリクエスト本文と一致する必要があります）、および 2025-11-25 と 2025-06-18（initialize を使用）に対応します。両方の方式に対応するクライアントは、いずれか一方を選択します。設定行は同じです。Streamable HTTP、POST のみ、セッションなし。応答は常に JSON で、ストリームにはならず、変更通知も送信されません。
• トークン：serve の起動ごとに新しいトークンが生成されるため、再起動後は行をもう一度コピーする必要があります。行を固定するには、serve と IDE の環境変数に SPECPILOT_MCP_TOKEN（32 文字以上、空白なし）を設定してください。すると行には ${SPECPILOT_MCP_TOKEN} と表示され、Claude Code は環境変数から値を読み込みます（その他の IDE では、その箇所にトークンを入力してください）。SpecPilot がトークンをどこかに書き込むことはありません。
• --read-only：読み取りツール 4 つのみ（タスクの書き込み、Regenerate、セットアップツールは使用できません）。エンドポイントには専用のトークンが割り当てられ、ページも読み取り専用になります。
• 指示ファイル：init、add-specs、および AI IDE を介したセットアップで生成されるファイルには、もう 1 つプロセス上の要件が含まれます。接続されている場合はタスクに SpecPilot MCP ツールを使用し、接続されていない場合は .specs/planning/tasks.md を編集して、Backlog、Current Sprint、Review の下では表の形式（| ID | Type | Priority | Description |。同じ形式のファイルでは | ID | Description |）、Completed の下では | # | ID | Description | を保ち、タスクごとに 1 行にしてください。specpilot backfill は、Tasks 行がない既存ファイルにこの要件を追加します。

対応言語とフレームワーク

TypeScript

• React：SPA アプリケーション
• Express：REST API
• Next.js：フルスタックアプリ
• Nest.js：スケーラブルなサーバーサイドアプリ
• Vue：プログレッシブ UI フレームワーク
• Angular：エンタープライズ向け SPA フレームワーク

JavaScript

• React：SPA アプリケーション
• Express：REST API

注：JavaScript ではフレームワークのプロンプトは表示されません。必要に応じて --framework を明示的に指定してください。

Python

• FastAPI：モダンな REST API
• Django：フルスタックアプリケーション
• Flask：軽量な REST API
• Streamlit：データサイエンス／ML アプリ

Kotlin

• Android：ネイティブ Android アプリ
• Spring：サーバーサイド REST API
• Ktor：非同期 Kotlin ウェブフレームワーク
• Compose：Jetpack Compose UI

Swift

• iOS：ネイティブ iOS アプリ
• SwiftUI：宣言型の Apple UI
• Vapor：Swift サーバーサイドフレームワーク

プロジェクト構成

SpecPilot は、整理されたサブディレクトリを含む .specs/ フォルダーを生成します。

.specs/
├── architecture/
│   ├── api.yaml              # CLI / REST API / GraphQL interface spec
│   └── architecture.md       # System design decisions and patterns
├── development/
│   ├── context.md            # Development memory, decisions, learnings
│   ├── onboarding.md         # One-time AI bootstrap prompt — delete after first use
│   └── prompts.md            # AI interaction log — MANDATED, update every session
├── planning/
│   ├── roadmap.md            # Release milestones and objectives
│   └── tasks.md              # Sprint tracker (backlog / current / completed)
├── project/
│   ├── project.yaml          # Project config and AI context (MANDATED)
│   └── requirements.md       # Functional & non-functional requirements
├── quality/
│   └── tests.md              # Test strategy, coverage targets, acceptance criteria
└── security/
    ├── security-decisions.md # ADR-style security design decisions
    └── threat-model.md       # Threat inventory with impact/likelihood/mitigation

また、プロジェクトのルートには、選択した IDE／エージェントに応じた AI コンテキストファイル（.github/copilot-instructions.md、CLAUDE.md、.cursor/rules/specpilot.mdc 、.windsurfrules、.antigravity/rules.md など）も生成されます。

設定

SpecPilot ではグローバル設定は不要です。各プロジェクトは独立しており、設定は project.yaml に保存されます。

IDE とエージェントのサポート

SpecPilot は、プロジェクトの初期化時に AI エージェント設定ファイルを生成します。specpilot init を実行すると、使用する AI IDE／エージェントを選択するよう求められます。

デスクトップ IDE（ワークスペース設定）：

• GitHub Copilot - Copilot との統合を備えた業界標準
• Cursor - AI コンテキストを強化した AI ファーストのコードエディター
• Windsurf - 高度な AI コーディングアシスタント
• Antigravity - コンテキスト認識機能を備えた AI 搭載 IDE

クラウドベースの AI エージェント（指示ファイル）：

• Claude Code - Anthropic Claude Code CLI エージェント（CLAUDE.md）
• Codex - 指示コンテキストを備えた OpenAI Codex エージェント

生成される設定ファイル：

IDE／エージェントの選択ごとに、プロジェクトのルートに AI コンテキストファイルが 1 つ生成されます。

IDE／エージェント	生成されるファイル
GitHub Copilot	.github/copilot-instructions.md
Codex	.github/copilot-instructions.md
Cursor	.cursor/rules/specpilot.mdc
Windsurf	.windsurfrules
Antigravity	.antigravity/rules.md
Claude Code	CLAUDE.md

すべてのコンテキストファイルには、プロジェクト名／技術スタック、重要な必須事項、コード哲学、コードルール、再アンカープロンプトが含まれます。

デスクトップ IDE の場合：.vscode/settings.json（または .cursor/、.windsurf/ など）

• コードと .specs 用の IDE 固有のワークスペースフォルダー設定
• 開発に推奨される拡張機能
• 仕様との統合を改善するための AI コンテキスト設定

生成されるスラッシュコマンド

IDE／エージェントを選択するたびに、8 個の specpilot-* スラッシュ／ワークフローコマンド（status、reanchor、report、sync、refine、validate、archive、backfill）も生成されます。これらは、主要な CLI 操作をエディター内のコマンドとして再現します。たとえば、Claude Code では .claude/commands/specpilot-status.md、Cursor では .cursor/commands/、GitHub Copilot では .github/prompts/ に配置されます。既存のプロジェクトで backfill を実行すると、設定済みの IDE に不足しているコマンドが補われ、編集されていないコマンドは最新バージョンに更新されます。編集済みのファイルはそのまま保持され、一覧に表示されます。各コマンドファイルは、追加、更新（最新バージョンに）、または理由付きで保持として報告されます。保持の理由は、kept: modified（変更されています。最新バージョンを取得するには、ファイルを削除して specpilot backfill を再実行してください）、kept: CRLF line endings（既知のバージョンが Windows の改行コードで保存されています）、kept: symbolic link（シンボリックリンクを介した書き込みは行いません）、kept: folder is a symbolic link or not a folder（リンクされた .claude/ などを介した書き込みは行いません）、または kept: could not be written: <code>（書き込みに失敗しました。ほかの処理は引き続き実行されます）です。specpilot serve ページの Regenerate All でも同じ処理が実行されます。完全な一覧と IDE ごとのパスについては、完全ガイドを参照してください。

生成される設定／指示により、AI エージェントは自動的に次のように設定されます。

• AI コンテキストに .specs/ フォルダーを含める
• プロジェクトの構造と要件を理解する
• 仕様駆動開発の原則に従う
• 開発ガイドラインとオンボーディングプロンプトにアクセスする

例：

# During init, you'll be prompted to select your IDE/Agent
specpilot init my-project --lang typescript --framework react
# Respond with your preferred IDE/Agent:
# - vscode, cursor, windsurf, antigravity (desktop)
# - claude-code, codex (cloud agents)

トラブルシューティング

よくある問題

権限エラー

sudo chown -R $USER ~/.npm-global
npm config set prefix '~/.npm-global'

テンプレートが見つからない

specpilot list --verbose

検証の失敗

specpilot validate --verbose --fix

移行の問題

エラー：「Source structure 'complex' not found」

# For NEW projects, use:
specpilot init my-project

# For EXISTING projects without specs:
specpilot add-specs

# Only use migrate if you have an old .project-spec folder
specpilot migrate --from complex --to simple --backup

デバッグモード

DEBUG=specpilot specpilot <command>

SpecPilot を選ぶ理由

SpecPilot は、仕様を最初に作成する 仕様駆動開発（SDD） を実現します。

Specifications → Architecture → Code → Tests → Deployment

メリット：

• 明確さ：何を作る必要があるかを全員が理解できます
• 一貫性：プロジェクト間で標準化された構造を保てます
• 品質：検証とテストが組み込まれています
• AI 対応：AI アシスタント向けの明確なコンテキストを提供します
• 保守性：包括的なドキュメントを備えています

コントリビューション

このプロジェクトは SDD の原則に従っています。コントリビューションのガイドラインについては .specs/ を参照してください。

開発環境のセットアップ

git clone https://github.com/girishr/SpecPilot.git
cd SpecPilot
npm install
npm run build
npm link  # For local testing

specpilot serve のブラウザーテスト

ページ上のクリック、キー入力、フォーカス、ライブリロードは、npm test とは別に、ヘッドレス Chromium でテストされます。

npx playwright-core install chromium-headless-shell  # once, if Playwright's Chromium is not on this machine yet
npm run test:browser                                  # builds, then runs src/__browser__/ (about 10 s)

このテストスイートは、フィクスチャープロジェクト（src/__browser__/fixture/。このリポジトリ自体の .specs/ は使用しません）のスクラッチコピーを使い、一時的な HOME の下でビルド済みサーバーを起動します。そのため、リポジトリや ~/.specpilot/ には何も書き込みません。テストが失敗すると、エラーメッセージとスタックトレース、スクリーンショット、ページの HTML の保存先が一時フォルダーに出力されます。

コントリビューションのクイックガイド

1. .specs/project/requirements.mdを確認する
2. .specs/planning/tasks.mdを確認する
3. 変更を加える際は仕様を更新する
4. コミットする前に specpilot validate を実行する

リリースは docs/RELEASING.md のチェックリストに従います。

ドキュメント

• 完全ガイド：包括的なドキュメント
• SpecPilot と GitHub Spec Kit の比較：適切なツールを選ぶための詳細な比較
• 変更履歴：バージョン履歴
• 課題：バグ報告と機能リクエスト

ライセンス

MIT ライセンス。詳細は LICENSE ファイルを参照してください。

---

本格的な本番プロジェクト向けに、仕様駆動開発の原則に基づいて構築されています。