Pound79/specproof

specproof は何をしますか？

AIが生成したテストの信頼性を維持します。AIがGherkin仕様を作成し、決定論的なSHA-256エンジンがCI上で仕様/実装/機能のずれを検出し、最終判断は人間が行います。CodexとClaude Code向けのエージェントスキル、およびPlaywright/Flutterのスキャフォールドを提供します。

概要

SpecProofは、AIエージェントが生成するテストコードの整合性を保証するためのツールです。AIにGherkin形式の仕様を生成させ、その仕様のハッシュ値をSHA-256で計算。CIパイプラインで常にハッシュ値を比較することで、仕様の変更や実装との乖離を自動検出します。

仕組み

1. AIがGherkin仕様を生成: CodexやClaude Codeが、与えられた要件からGherkin（Given-When-Then）形式の仕様を自動生成します。
2. SHA-256ハッシュの計算: 各仕様ファイルから決定論的なSHA-256ハッシュを計算し、.specproof/ ディレクトリに保存します。
3. CIでの検証: CIパイプラインで仕様が変更されていないか、ハッシュを比較。不一致が検出された場合、パイプラインが失敗し、人間のレビューを促します。
4. 人間の判断: 開発者は検出されたずれを確認し、仕様の更新、実装の修正、または意図的な変更として承認します。

対応プラットフォーム

• エージェントスキル:
  • Codex（OpenAI）
  • Claude Code（Anthropic）
• テストフレームワークスキャフォールド:
  • Playwright（E2Eテスト）
  • Flutter（ウィジェットテスト）

インストール

# リポジトリのクローン
git clone https://github.com/Pound79/specproof.git
cd specproof

# 依存関係のインストール
npm install
# または
pip install -r requirements.txt

使用方法

1. Gherkin仕様の生成（AIエージェントを使う場合）

CodexまたはClaude Codeに以下のプロンプトを送信します:

次の機能のGherkin仕様を生成してください: [機能の説明]

2. ハッシュの計算

npx specproof hash --dir features/

3. CIでの検証

.github/workflows/specproof.yml の例:

name: SpecProof
on: [push]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npx specproof verify --dir features/

設定

プロジェクトルートに specproof.config.json を作成します:

{
  "featuresDir": "features/",
  "hashStorage": ".specproof/",
  "algorithms": ["sha256"],
  "platform": "playwright"
}

環境変数

• SPECPROOF_VERBOSE: 詳細なログを出力（true/false）
• SPECPROOF_STRICT: 厳密モード（すべてのファイルのハッシュ一致を要求）

関連リソース

• GitHub リポジトリ
• Gherkin リファレンス
• Playwright ドキュメント
• Flutter テスト