SpecKit スクリプトガイド

作成日: 2026-02-14 対象: .specify/scripts/bash/ ディレクトリ内のスクリプト

スクリプトの概要

.specify/scripts/bash/ ディレクトリには、SpecKit ワークフローを自動化する Bash スクリプトが含まれています。これらのスクリプトは、機能の作成、ドキュメントの準備、AI エージェントへのコンテキスト提供などを効率化します。

スクリプト一覧

スクリプト名	目的
`common.sh`	共通関数とユーティリティの提供
`create-new-feature.sh`	新規機能ブランチとディレクトリの作成
`setup-plan.sh`	実装計画ファイルのセットアップ
`check-prerequisites.sh`	必要なファイルと前提条件の確認
`update-agent-context.sh`	AI エージェント向けコンテキストファイルの更新

common.sh - 共通関数ライブラリ

概要

他のすべてのスクリプトから利用される共通関数を提供するライブラリです。Git/非Git 環境の両方に対応し、柔軟なパス解決を実現します。

主要関数

1. `get_repo_root()`

目的: リポジトリのルートディレクトリを取得
動作:
- Git リポジトリの場合: git rev-parse --show-toplevel を使用
- 非 Git の場合: スクリプトの場所から相対的に推測
戻り値: リポジトリのルートパス

2. `get_current_branch()`

目的: 現在の機能ブランチ/機能名を取得
優先順位:
1. 環境変数 SPECIFY_FEATURE
2. Git ブランチ名（Git 利用時）
3. specs/ ディレクトリ内の最新機能（番号順）
4. デフォルト: "main"
戻り値: ブランチ名または機能名

3. `has_git()`

目的: Git が利用可能かどうかを判定
戻り値: 成功（0）または失敗（1）

4. `check_feature_branch(branch, has_git_repo)`

目的: ブランチ名が機能ブランチの命名規則に従っているか検証
命名規則: ###-feature-name（例: 001-user-auth）
非 Git の場合: 警告を表示するが検証をスキップ

5. `find_feature_dir_by_prefix(repo_root, branch_name)`

目的: ブランチの数値プレフィックスに基づいて機能ディレクトリを検索
特徴:
- 複数のブランチが同じ仕様で作業可能（例: 004-fix-bug と 004-add-feature）
- specs/ 内で数値プレフィックスが一致するディレクトリを検索
戻り値: 機能ディレクトリのパス

6. `get_feature_paths()`

目的: 現在の機能に関連するすべてのパスを生成

出力:

REPO_ROOT='/path/to/repo'
CURRENT_BRANCH='001-feature-name'
HAS_GIT='true'
FEATURE_DIR='/path/to/repo/specs/001-feature-name'
FEATURE_SPEC='/path/to/repo/specs/001-feature-name/spec.md'
IMPL_PLAN='/path/to/repo/specs/001-feature-name/plan.md'
TASKS='/path/to/repo/specs/001-feature-name/tasks.md'
RESEARCH='/path/to/repo/specs/001-feature-name/research.md'
DATA_MODEL='/path/to/repo/specs/001-feature-name/data-model.md'
QUICKSTART='/path/to/repo/specs/001-feature-name/quickstart.md'
CONTRACTS_DIR='/path/to/repo/specs/001-feature-name/contracts'

7. ユーティリティ関数

check_file(path, label): ファイルの存在確認と表示
check_dir(path, label): ディレクトリの存在確認と表示（内容あり）

使用方法

# 他のスクリプトから読み込む
source "$SCRIPT_DIR/common.sh"

# パスを取得して環境変数に設定
eval $(get_feature_paths)

# ブランチをチェック
check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1

create-new-feature.sh - 新規機能作成

概要

新しい機能の開発を開始するための初期セットアップを自動化します。ブランチ作成、ディレクトリ作成、仕様ファイルの初期化を行います。

機能

機能番号の自動採番
- 既存の specs/ ディレクトリとブランチを調査
- 最大番号を見つけて +1 してユニークな番号を生成
- 形式: 001、002、003...（3桁ゼロパディング）
ブランチ名の生成
- 自動生成モード: 機能説明から意味のある単語を抽出
  - ストップワード（"the"、"a"、"is" など）をフィルタリング
  - 3-4 語を選択してハイフンで結合
- 手動指定モード: --short-name オプションで指定
- 最終形式: ###-meaningful-name
Git ブランチ作成
- Git 環境: git checkout -b ###-feature-name
- 非 Git 環境: 警告を表示してスキップ
ディレクトリとファイルの初期化
- specs/###-feature-name/ ディレクトリを作成
- spec-template.md をコピーして spec.md を作成
環境変数の設定
- SPECIFY_FEATURE 環境変数を設定（現在のセッション用）

オプション

オプション	説明
`--json`	JSON 形式で結果を出力
`--short-name <name>`	カスタム短縮名を指定（2-4語）
`--number N`	ブランチ番号を手動指定（自動検出を上書き）
`--help`, `-h`	ヘルプメッセージを表示

使用例

# 自動でブランチ名を生成
./create-new-feature.sh "Add user authentication system"
# 結果: 001-user-authentication-system

# カスタム短縮名を使用
./create-new-feature.sh "Implement OAuth2 integration for API" --short-name "oauth-api"
# 結果: 002-oauth-api

# 番号を手動指定
./create-new-feature.sh "Add logging" --number 5
# 結果: 005-add-logging

# JSON 出力
./create-new-feature.sh "New feature" --json
# {"BRANCH_NAME":"003-new-feature","SPEC_FILE":"/path/to/specs/003-new-feature/spec.md","FEATURE_NUM":"003"}

内部動作

番号決定のロジック:

# Git ブランチから最大番号を取得
get_highest_from_branches()

# specs/ ディレクトリから最大番号を取得
get_highest_from_specs()

# 両方の最大値 + 1
BRANCH_NUMBER = max(branches, specs) + 1

ブランチ名のクリーニング:

# 大文字を小文字に変換
# 非英数字をハイフンに変換
# 連続するハイフンを1つに
# 先頭/末尾のハイフンを削除

GitHub の制限対応:
- ブランチ名は 244 バイト以内に制限
- 超過した場合は自動的に切り詰め

setup-plan.sh - 計画セットアップ

概要

実装計画フェーズの準備として、plan.md ファイルを作成します。

機能

環境確認
- common.sh から機能パスを取得
- 機能ブランチの妥当性をチェック
ディレクトリ作成
- FEATURE_DIR が存在しない場合は作成
計画ファイルの初期化
- テンプレート (plan-template.md) をコピーして plan.md を作成
- テンプレートがない場合は空ファイルを作成

オプション

オプション	説明
`--json`	JSON 形式で結果を出力
`--help`, `-h`	ヘルプメッセージを表示

使用例

# 通常の使用
./setup-plan.sh

# JSON 出力
./setup-plan.sh --json

出力例

テキスト形式:

Copied plan template to /path/to/specs/001-feature/plan.md
FEATURE_SPEC: /path/to/specs/001-feature/spec.md
IMPL_PLAN: /path/to/specs/001-feature/plan.md
SPECS_DIR: /path/to/specs/001-feature
BRANCH: 001-feature
HAS_GIT: true

JSON 形式:

{
  "FEATURE_SPEC": "/path/to/specs/001-feature/spec.md",
  "IMPL_PLAN": "/path/to/specs/001-feature/plan.md",
  "SPECS_DIR": "/path/to/specs/001-feature",
  "BRANCH": "001-feature",
  "HAS_GIT": "true"
}

check-prerequisites.sh - 前提条件チェック

概要

実装の各フェーズで必要なファイルと前提条件が満たされているかを検証します。

機能

必須ファイルの確認
- 機能ディレクトリの存在
- plan.md の存在（常に必須）
- tasks.md の存在（--require-tasks 指定時）
オプションファイルの検出
- research.md
- data-model.md
- contracts/ ディレクトリ（内容あり）
- quickstart.md
- tasks.md（--include-tasks 指定時）
複数の出力モード
- テキスト形式: ファイルの存在を ✓/✗ で表示
- JSON 形式: プログラムで解析可能な構造化データ
- パスのみ: 検証なしでパス変数のみ出力

オプション

オプション	説明
`--json`	JSON 形式で出力
`--require-tasks`	`tasks.md` の存在を必須とする
`--include-tasks`	利用可能ドキュメントリストに `tasks.md` を含める
`--paths-only`	パス変数のみ出力（検証なし）
`--help`, `-h`	ヘルプメッセージを表示

使用例

# タスク生成の前提条件をチェック（plan.md 必須）
./check-prerequisites.sh --json

# 実装の前提条件をチェック（plan.md + tasks.md 必須）
./check-prerequisites.sh --json --require-tasks --include-tasks

# パスのみ取得（検証なし）
./check-prerequisites.sh --paths-only

出力例

テキスト形式:

FEATURE_DIR:/path/to/specs/001-feature
AVAILABLE_DOCS:
  ✓ research.md
  ✓ data-model.md
  ✗ contracts/
  ✓ quickstart.md

JSON 形式:

{
  "FEATURE_DIR": "/path/to/specs/001-feature",
  "AVAILABLE_DOCS": ["research.md", "data-model.md", "quickstart.md"]
}

パスのみモード:

REPO_ROOT: /path/to/repo
BRANCH: 001-feature
FEATURE_DIR: /path/to/specs/001-feature
FEATURE_SPEC: /path/to/specs/001-feature/spec.md
IMPL_PLAN: /path/to/specs/001-feature/plan.md
TASKS: /path/to/specs/001-feature/tasks.md

エラーハンドリング

機能ディレクトリが見つからない → /speckit.specify を先に実行するよう促す
plan.md が見つからない → /speckit.plan を先に実行するよう促す
tasks.md が必須だが見つからない → /speckit.tasks を先に実行するよう促す

update-agent-context.sh - AI エージェントコンテキスト更新

概要

plan.md から技術情報を抽出し、AI エージェント向けのコンテキストファイル（CLAUDE.md、GEMINI.md など）を更新します。

機能

環境検証
- 現在の機能ブランチの確認
- plan.md の存在確認
- テンプレートファイルの確認
plan.md からのデータ抽出
- Language/Version: **Language/Version**: Python 3.11 などを抽出
- Primary Dependencies: **Primary Dependencies**: FastAPI などを抽出
- Storage: **Storage**: SQLite などを抽出
- Project Type: **Project Type**: single などを抽出
エージェントファイルの作成または更新
- 新規作成: テンプレートからファイルを生成
- 既存更新: Active Technologies と Recent Changes セクションを更新
複数の AI エージェント対応
- Claude Code (CLAUDE.md)
- Gemini CLI (GEMINI.md)
- GitHub Copilot (.github/agents/copilot-instructions.md)
- Cursor IDE (.cursor/rules/specify-rules.mdc)
- Qwen Code (QWEN.md)
- その他多数（Windsurf、Kilo Code、Auggie、Roo、SHAI、Amazon Q など）

オプション

引数	説明
`[agent_type]`	更新する特定のエージェント（省略時は全エージェント）

対応エージェント: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, codebuddy, qoder, amp, shai, q, bob

使用例

# すべての既存エージェントファイルを更新
./update-agent-context.sh

# Claude のみを更新
./update-agent-context.sh claude

# Gemini のみを更新
./update-agent-context.sh gemini

内部動作

1. データ抽出

extract_plan_field() {
    local field_pattern="$1"
    local plan_file="$2"

    # "**Field**: value" 形式の行を検索
    grep "^\*\*${field_pattern}\*\*: " "$plan_file" | \
        sed "s|^\*\*${field_pattern}\*\*: ||" | \
        # "NEEDS CLARIFICATION" と "N/A" を除外
        grep -v "NEEDS CLARIFICATION" | \
        grep -v "^N/A$"
}

2. 新規ファイル作成

テンプレートのプレースホルダーを実際の値に置換:

[PROJECT NAME] → リポジトリ名
[DATE] → 現在の日付
[EXTRACTED FROM ALL PLAN.MD FILES] → 技術スタック
[ACTUAL STRUCTURE FROM PLANS] → プロジェクト構造
[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] → コマンド
[LANGUAGE-SPECIFIC...] → 言語規約
[LAST 3 FEATURES...] → 最近の変更

3. 既存ファイル更新

## Active Technologies
- Python 3.11 + FastAPI (001-user-auth)  ← 新規追加
- SQLite (001-user-auth)                 ← 新規追加

## Recent Changes
- 001-user-auth: Added Python 3.11 + FastAPI  ← 新規追加（最上部）
- 002-old-feature: Added...                   ← 既存（保持）
- 003-older-feature: Added...                 ← 既存（保持）
- 004-ancient-feature: Added...               ← 削除（最新3つのみ保持）

コマンド生成例

言語に応じたビルド/テストコマンドを自動生成:

Python: cd src && pytest && ruff check .
Rust: cargo test && cargo clippy
JavaScript/TypeScript: npm test && npm run lint

ログ出力

INFO: Parsing plan data from /path/to/specs/001-feature/plan.md
INFO: Found language: Python 3.11
INFO: Found framework: FastAPI
INFO: Found database: SQLite
INFO: Updating Claude Code context file: /path/to/repo/CLAUDE.md
✓ Updated existing Claude Code context file

Summary of changes:
  - Added language: Python 3.11
  - Added framework: FastAPI
  - Added database: SQLite

使用例

ワークフロー全体の例

# 1. 新規機能を作成
./create-new-feature.sh "Add user authentication"
# → ブランチ: 001-user-authentication
# → ディレクトリ: specs/001-user-authentication/
# → ファイル: specs/001-user-authentication/spec.md

# 2. 仕様を編集（手動または /speckit.specify コマンド）
# spec.md にユーザーストーリー、要件、成功基準を記述

# 3. 計画をセットアップ
./setup-plan.sh
# → ファイル: specs/001-user-authentication/plan.md

# 4. 計画を編集（手動または /speckit.plan コマンド）
# plan.md に技術スタック、プロジェクト構造を記述

# 5. AI エージェントコンテキストを更新
./update-agent-context.sh
# → CLAUDE.md などが更新される

# 6. タスク生成前の前提条件チェック
./check-prerequisites.sh --json
# → plan.md が存在することを確認

# 7. タスクを生成（/speckit.tasks コマンド）
# → ファイル: specs/001-user-authentication/tasks.md

# 8. 実装前の前提条件チェック
./check-prerequisites.sh --json --require-tasks --include-tasks
# → plan.md と tasks.md が存在することを確認

# 9. 実装を開始（/speckit.implement コマンドまたは手動）

Git/非Git 環境の違い

Git 環境

# ブランチが自動作成される
./create-new-feature.sh "New feature"
# → git checkout -b 001-new-feature

# ブランチから機能を自動検出
./update-agent-context.sh
# → 現在のブランチ名を使用

非Git 環境

# ブランチ作成はスキップされる（警告表示）
./create-new-feature.sh "New feature"
# Warning: Git repository not detected; skipped branch creation

# 環境変数で機能を指定
export SPECIFY_FEATURE="001-new-feature"
./update-agent-context.sh
# → SPECIFY_FEATURE を使用

まとめ

SpecKit のスクリプトは、仕様駆動開発ワークフローを効率化する強力なツールセットです。

各スクリプトの役割

common.sh: すべてのスクリプトの基盤となる共通関数
create-new-feature.sh: 新規機能開発の起点
setup-plan.sh: 計画フェーズの準備
check-prerequisites.sh: 各フェーズの前提条件確認
update-agent-context.sh: AI エージェントとの連携

スクリプトの特徴

柔軟性: Git/非Git 環境の両方に対応
自動化: 手作業を最小限に抑える
検証: エラーを早期に検出
統合: AI エージェントとシームレスに連携

これらのスクリプトを活用することで、一貫性のある高品質なソフトウェア開発が可能になります。

SpecKit スクリプトガイド

目次

スクリプトの概要

スクリプト一覧

common.sh - 共通関数ライブラリ

概要

主要関数

1. get_repo_root()

2. get_current_branch()

3. has_git()

4. check_feature_branch(branch, has_git_repo)

5. find_feature_dir_by_prefix(repo_root, branch_name)

6. get_feature_paths()

7. ユーティリティ関数

使用方法

create-new-feature.sh - 新規機能作成

概要

機能

オプション

使用例

内部動作

setup-plan.sh - 計画セットアップ

概要

機能

オプション

使用例

出力例

check-prerequisites.sh - 前提条件チェック

概要

機能

オプション

使用例

出力例

エラーハンドリング

update-agent-context.sh - AI エージェントコンテキスト更新

概要

機能

オプション

使用例

内部動作

1. データ抽出

2. 新規ファイル作成

3. 既存ファイル更新

コマンド生成例

ログ出力

使用例

ワークフロー全体の例

Git/非Git 環境の違い

Git 環境

非Git 環境

まとめ

各スクリプトの役割

スクリプトの特徴

1. `get_repo_root()`

2. `get_current_branch()`

3. `has_git()`

4. `check_feature_branch(branch, has_git_repo)`

5. `find_feature_dir_by_prefix(repo_root, branch_name)`

6. `get_feature_paths()`