SpecForge

5分で試す · 仕組み · 問題を見つける様子を見る · ドキュメント

エージェント不要で、60秒で確認できます。 インストールして、プロジェクトを作成し、1文字削ってチェックします。

curl -fsSL https://raw.githubusercontent.com/leaderiop/SpecForge/main/install.sh | sh
mkdir sf-demo && cd sf-demo
specforge init --extensions @specforge/software          # spec/hello.spec, which checks clean
sed -i.bak 's/\[user_logged_in\]/[user_loged_in]/' spec/hello.spec   # drop one letter
specforge check

[E003] Error: unresolved reference 'user_loged_in' in entity 'authenticate_user'
 20 │   produces [user_loged_in]
    │ Help: did you mean 'user_logged_in'?

[W007] Warning: event 'user_logged_in' is not produced by any behavior

1 error, 1 warning, 0 infos

レビュー担当者が読み、チェックで解決します。

問題点

AI エージェントに、決済サービスへの返金機能の追加を依頼します。きれいなコードが書かれ、テストは通り、プルリクエストにも問題はなさそうです。ところが2週間後、経理部門が返金額が対象の決済額を上回っていることに気づきます。

ルールは仕様書に書かれていました。PRDの隣にある、docs/ 内の Markdown ファイルです。エージェントがそれを読んだのは3回前のセッションだったかもしれませんし、一度も見つけていなかったかもしれません。何も失敗しなかったため、誰も気づきませんでした。

これはモデルの問題ではありません。ルールを置く場所の問題です。現在、重要なナレッジは、何も強制できない場所に置かれています。

• Markdown の仕様書（PRD、docs/*.md、spec-kit ファイル）は散文です。エージェントがルールを誤読したり、黙って読み飛ばしたりしても、仕様書に不足がないか、各部分の整合性が取れているかをチェックする仕組みはありません。
• ドキュメントや Wiki はコードから乖離していきますが、そうなっても何も壊れません。
• トレーサビリティ（どの要件にテストがあるか、どのルールがどこで適用されるか）は、誰かが手作業で更新するスプレッドシートです。更新をやめるまでは。
• セッションのたびに、すべてがゼロから始まります。 エージェントは、意図を再確認するために何十ものファイルを読み直し、それでも推測に頼ります。

AIに任せる作業が増えるほど、状況は悪化します。コードを書く速度が、人間のレビュー速度を上回るからです。

アイデア：暗黙のスキルではなく、強制されるスキル

チームの仕事の進め方を AI に教える方法は2つあります。

暗黙のスキルとは、AI のコンテキストに置くアドバイスです。Markdown の仕様書、PRD、スキルファイルなどです。役には立ちますが、あくまで散文です。AI が従うこともあれば、従わないこともあります。

強制されるスキルとは、プログラムが適用するルールです。チェックが失敗するため、AI は無視できません。

SpecForge は、強制されるスキルのためのツールです。 あなた（多くの場合はエージェント）が、真であるべきことを小さな構造化された .spec ファイルに記述します。SpecForge はコンパイラーがコードをチェックするように、それらをチェックします。すべての参照が実在するものを指していること、すべてのルールが何かによって適用されていること、すべての約束がテストによって証明されていることを確認します。そして、チェック済みの結果をコンテキストとしてエージェントに渡します。

意図を型チェックするツールと考えてください。

仕組み

1. 実現したいことを説明します。今日と同じように、会話の中で説明します。
2. エージェントが仕様の下書きを作成します。操作、常に満たすべきルール、イベント、そしてそれぞれについて、何がそれを証明するのかを記述します。
3. SpecForgeが下書きをチェックします。 誤字、誰も強制していないルール、不足している項目があると、該当する行と修正のヒントを示してチェックが失敗し、エージェントが修正します。この手順にはAIは関与しません。同じ入力には、毎回同じ判定が返されます。
4. エージェントがチェック済みの仕様に基づいて構築します。 リポジトリを読み直すのではなく、必要な部分をSpecForgeに問い合わせます。
5. テストが仕様を証明します。 各テストでは、何を証明するのかを指定します。specforge collect を実行すると、証明されたことと、まだ証明されていないことが記録されます。
6. あなたがレビューします。 エージェントが書いたすべての行を読む代わりに、何が約束され、何が証明され、何がまだ未解決なのかを確認します。

問題を検出する様子を見る

エージェントが返金機能の下書きを作成します。

invariant refund_within_capture "Refunds never exceed the captured amount" {
  risk high
  verify unit "rejects a refund larger than the captured amount"
}

invariant refund_needs_reason "Every refund records a reason" {
  guarantee "A refund without a reason is rejected"
  risk      medium
  verify unit "rejects a refund with no reason"
}

behavior issue_refund "Refund a captured payment" {
  category   command
  invariants [refund_within_capture]
  produces   [refund_isued]
  contract   "Given a captured payment, refunds up to the captured amount"
  verify unit "refunds the requested amount"
}

event refund_issued "A refund was issued" {
  verify unit "is emitted once per refund"
}

問題なさそうに見えます。specforge check の結果は次のとおりです。

[E003] Error: unresolved reference 'refund_isued' in entity 'issue_refund'
    ╭─[ refunds.spec:15:15 ]
 15 │   produces   [refund_isued]
    │ Help: did you mean 'refund_issued'?

[W003] Warning: invariant 'refund_needs_reason' is not enforced by any behavior
[W007] Warning: event 'refund_issued' is not produced by any behavior
[E006] Error: invariant 'refund_within_capture' is missing required field 'guarantee'

2 errors, 2 warnings, 0 infos

人間のレビュー担当者なら見落としそうな4つの問題です。

エラーがあると、必ずチェックは失敗します。specforge check --strict を実行すると警告がある場合も失敗し、これをCIで実行します。

エージェントが4つすべての問題を修正し、もう一度チェックを実行します。結果は 0 errors, 0 warnings, 0 infos です。仕様の整合性は取れましたが、まだ何も証明されていません。それはテストの役割です。各テストで証明する内容を指定し、specforge collect でテストを実行し、specforge review で何がカバーされ、何がまだ未解決なのかを確認します。

今見たルールはすべて、SpecForge自体ではなく拡張機能から得られたものです（ハードスキルは拡張機能を参照してください）。

5 分で試す

1. インストールします。 SpecForge は依存関係のない単一のバイナリです。

curl -fsSL https://raw.githubusercontent.com/leaderiop/SpecForge/main/install.sh | sh

# Homebrew (once the tap is published)
brew install leaderiop/tap/specforge

# Prebuilt binary via cargo-binstall
cargo binstall --git https://github.com/leaderiop/SpecForge specforge-cli

# From source (stable Rust toolchain)
git clone https://github.com/leaderiop/SpecForge && cd SpecForge
cargo install --path crates/surfaces/cli

2. プロジェクトを作成します。リポジトリ内で次を実行します。

specforge init --extensions @specforge/software

specforge.json と、spec/ 内に最初のファイルが作成されます。Cargo または vitest のプロジェクトでは、対応するテストランナーも有効になります。

3. エージェントを接続します。 SpecForge はMCPに対応しているため、どの MCP クライアントからでも仕様を読み取り、チェックできます。絶対パスを使用してください。

claude mcp add specforge -- specforge mcp /path/to/your/project

Cursor では、ワンクリックで開いているプロジェクト（${workspaceFolder}）に追加できます。

{
  "mcpServers": {
    "specforge": { "command": "specforge", "args": ["mcp", "/path/to/your/project"] }
  }
}

4. エージェントに仕様を作成するよう依頼します。 たとえば、次のように依頼します。

返金機能の仕様を spec/ に作成してください。動作、決して破ってはならないルール、発行するイベント、およびそれぞれを証明するものを含めてください。SpecForge のツールで検証し、すべてのエラーを修正してから提示してください。

5. 結果を自分で確認します。

specforge check     # is the spec consistent?
specforge review    # what is still unproven?

6. テストを紐付けます。 各テストには、どのエンティティを証明するかを記述します。Rust の場合（specforge-test クレートを使用）：

use specforge_test::prelude::*;

#[specforge_test(behavior = "issue_refund", verify = "refunds the requested amount")]
fn refunds_the_requested_amount() { /* ... */ }

vitest の場合：

test('refunds the requested amount',
  { meta: { specforge: { behavior: 'issue_refund', verify: 'refunds the requested amount' } } },
  () => { /* ... */ })

次に specforge collect を実行します。テストコマンドを実行する前に一度だけ確認を求め、各テストが何を証明するかを記録します。Rustとvitestのガイドを参照してください。

新しい言語を覚える必要がありますか？

仕様は自分で承認するものなので、読む必要はあります。ただし、書く必要はほとんどありません。ファイルの作成と修正はエージェントが行い、チェックによって誤りを知らせます。

読みやすいように設計されています。各ブロックは、種類、名前、タイトル、フィールドを備えた記入済みフォームのように、1 つの項目を表します。

invariant refund_within_capture "Refunds never exceed the captured amount" {
  guarantee "The sum of refunds on a payment never exceeds the captured amount"
  risk      high
}

仕様を手作業で書く場合は、作成チュートリアルと実例から始めてください。

…との違いは何ですか？

ハードスキルは拡張機能です

SpecForge 自体は、決済、ソフトウェア、その他の分野について何も知りません。仕様に含まれるすべての語（behavior、invariant、event）と、すべてのルール（「不変条件は振る舞いによって適用されなければならない」など）は、拡張機能に由来します。拡張機能とは、コードとしてパッケージ化されたハードスキルです。語彙と、その語彙を評価するルールで構成されます。

以下はバイナリに同梱されています。

specforge add @specforge/product で有効にできます。全リストは拡張機能一覧をご覧ください。独自のハードスキルを作成する方法については、SpecForge の拡張をご覧ください。

今後の展望

現在、AI による記述が最も多い分野であるため、まずソフトウェアから始めています。しかし、意図的にエンジンには組み込みのドメインを設けていません。専門知識にルールがあり、間違いが大きな損失につながるあらゆる分野に対応できるよう設計されています。規制対象のソフトウェア（IEC 62304、GAMP 5）、医薬品品質（バッチリリース、逸脱）、安全工学などが該当します。これらの分野では、「AI が下書きを作り、ハードスキルがチェックし、有資格者が署名する」は単なるスローガンではありません。それが業務の要件です。こうした分野向けの拡張機能は開発中であり、まだ組み込みではありません。

また、型付きの操作を通じてエージェントが仕様を編集する機能も計画されています。これにより、人間も AI も .spec のテキストを手作業で書く必要がなくなります。

SpecForge ではないもの

• AI ではありません。 モデル呼び出しは行いません。Rust で記述された決定論的なコンパイラーです。
• コードジェネレーターではありません。 意図をチェックします。コードはエージェントが記述します。
• テストフレームワークではありません。 テストは cargo test または vitest に残ります。SpecForge はコマンドの実行を承認した後にのみテストを実行し、そのテストが何を証明するかを記録します。

詳細情報

• 作成チュートリアル：ゼロから .spec ファイルを作成する方法。実例、レシピ集、ベストプラクティス、トラブルシューティングもご覧ください。
• Rust のテストトレーシングとvitest のテストトレーシング：テストを、そのテストが証明するエンティティにリンクします。
• 形式検証：SMT ソルバーがチェックする仕様と、正確な位置を示す反例について説明します。
• クイックリファレンス：すべてのコマンド、エンティティの種類、診断コードを1ページにまとめています。
• ビジョン：マニフェスト、原則、北極星をご覧ください。
• アーキテクチャ、クレートマップ、コントリビューション：SpecForge の構築方法、各クレートの役割、開発への参加方法について説明します。
• ドキュメントハブ：エンティティリファレンス、トレーサビリティチェーン、調査資料をご覧ください。

ライセンス

Apache License, Version 2.0 または MIT license のいずれかを選択してライセンスされます。