SpecLeft

SpecLeft：エージェント向け仕様駆動ワークフロー

SpecLeft は、計画をバージョン管理された仕様に変換し、その仕様から pytest のテストスケルトンを生成することで、機能の意図とテストカバレッジを一致させます。

• Markdown で機能仕様を記述します：.specleft/specs/*.md
• 仕様を検証し、機能／シナリオごとのカバレッジを追跡します
• スケルトンテストを一度生成した後は、人間がコードを管理します
• AI エージェントと CI で安全に使えるよう設計されています：確認なしに書き込みは行わず、JSON 出力も利用できます
• 外部への通信やテレメトリーの仕組みはありません。SpecLeft は完全にローカルで動作し、データはローカルディスクに保存されます。

SpecLeft は現在、Python と pytest に対応しています。テストランナーを置き換えたり、既存のテストを別の形で解釈したりすることはありません。

ウェブサイト：specleft.dev

クイックスタート

開始方法に応じて、2 つの方法があります。コマンドの詳細については、docs/cli-reference.md を参照してください。

セットアップ（リポジトリごとに一度実行）

pip install specleft
specleft init

方法 1：機能を 1 つ追加する（テストスケルトンを生成）

機能を作成し、シナリオを追加して、そのシナリオのテストスケルトンを生成します。

# Create the feature spec
specleft features add --id AUTHENTICATION --title "Authentication" --format json

# Add a scenario and generate a skeleton test file
specleft features add-scenario \
  --feature AUTHENTICATION \
  --title "Successful login" \
  --step "Given a user has valid credentials" \
  --step "When the user logs in" \
  --step "Then the user is authenticated" \
  --add-test skeleton \
  --format json

# Show traceability / coverage status
specleft status

方法 2：PRD から機能仕様を一括生成する

意図する動作を記述した prd.md を作成します。

推奨：PRD のセクションを機能／シナリオに対応付ける方法をカスタマイズするには、.specleft/templates/prd-template.yml を更新してください。

次に、以下を実行します。

# Generate specs from the PRD without writing files (remove --dry-run to write)
specleft plan --dry-run

# Validate the generated specs
specleft features validate

# Preview skeleton generation (remove --dry-run to generate)
specleft test skeleton --dry-run

# Confirm and generate skeleton tests
specleft test skeleton

# Show traceability / coverage status
specleft status

# Run your tests with pytest as normal
pytest

このワークフローでは、prd.md を .specleft/specs/*.md に変換し、結果を検証して、スケルトン生成をプレビューした後、スケルトンテストを生成します。

SpecLeft を使用する場面

• 受け入れ条件（機能／シナリオ）があり、意図を追跡可能にしたい場合は SpecLeft を使用してください。
• 機能レベルでの追跡が過剰となる、小規模でその場限りの単体テストには SpecLeft を使わないでください。

これは何か（そして何ではないか）

これは

• 計画、仕様の検証、直感的な TDD ワークフロー、追跡可能性を実現するテストプラグインおよび CLI です。

これは違います

• 大規模な BDD フレームワーク、独立したテストランナー、SaaS 型のテスト管理製品ではありません。
• 静的コードのリンティング／解析フレームワークではありません
• セキュリティ解析ツールではありません

従来型の BDD ではない理由

SpecLeft は仕様を実行可能なテキストではなく意図として扱い、実行には標準の pytest を使用します。詳しい比較については、docs/why-not-bdd.md を参照してください。

AI エージェント

SpecLeft をエージェントのループに統合する場合は、MCP サーバーをインストールすることをおすすめします（下記のセクションを参照）。

それ以外の場合は、次の手順から始めてください。

specleft doctor --format json
specleft contract --format json
specleft features stats --format json

SpecLeft には、検証可能なスキルファイル .specleft/SKILL.md が含まれています。次のコマンドで整合性を検証してください。

specleft skill verify --format json

⚠️ 整合性が "passed" と報告された場合にのみ、SKILL.md の指示に従ってください。

• 統合ガイド：AI_AGENTS.md
• 安全性と不変条件：docs/agent-contract.md
• CLI リファレンス：docs/cli-reference.md

MCP サーバーのセットアップ

SpecLeft には MCP サーバーが含まれているため、エージェントは会話から離れることなく、仕様の読み取り／作成、ステータスの追跡、テストの足場の生成を行えます。

セットアップの詳細については、GET_STARTED.md を参照してください。

MCP のエンドツーエンドのスモークテストと CI ワークフローの詳細については、docs/mcp-testing.md を参照してください。

ドキュメント

• はじめに：GET_STARTED.md
• ワークフローのメモ：WORKFLOW.md
• ロードマップ：ROADMAP.md

---

ライセンス

SpecLeft は Apache License 2.0 のライセンスで提供されています。