SpecGuard - AIコーディング前に仕様を先に検査するCLI/Codexプラグイン

 (github.com/KoreaNirsa)
7 ポイント 投稿者 veltrix 6 일 전 | 1件のコメント | WhatsAppで共有

こんにちは。SpecGuardというオープンソースツールを作っています。

CodexやClaude CodeのようなAIコーディングツールを使うと、実装速度はたしかに速くなります。ですが何度か繰り返し使ってみると、実際に私がよくぶつかった問題は「AIがコードを書けない」ことよりも、「AIに渡した仕様そのものが不完全である」ことに近いと感じました。

仕様に欠陥があると、AIはその隙間をそれなりに推測して実装します。最初はもっともらしく見えますが、開発が進むほど次の問題が大きくなりました。

  • コードの品質と構造が徐々に崩れていきます。
  • 仕様とコードがだんだん一致しなくなります。
  • 後になると、コードが間違っているのか、仕様が古いのか、最初の要件が曖昧だったのか区別しにくくなります。

そのため、実装後のコードレビューだけでは不十分だと考えました。欠陥のある仕様がそのまま実装エージェントに渡る前に、仕様自体の抜けや曖昧さを先に表面化させる段階が必要でした。

SpecGuardはこの問題を減らすために作ったCLI/Codexプラグインです。コード生成後の成果物を検査するツールではなく、AIに実装を任せる前に仕様を先に検査するツールです。

私が意図した基本フローは次のとおりです。

  1. 人がプロダクト仕様を書く
  2. SpecGuardで仕様を検査する
  3. NOT_READY なら仕様を補強する
  4. READY になったらCodexやClaude Codeのような実装エージェントに渡す

SpecGuardは主に次のような種類の抜けを見つけます。

  • 認証/権限の境界が不明確
  • tenant/user ownership の範囲が抜けている
  • idempotency、replay、race condition の処理がない
  • 失効/撤回/状態遷移ルールが曖昧
  • 外部副作用、webhook、background job の再試行ポリシーがない
  • クライアント検証だけを信頼する要件

結果は大きく3つです。

  • READY: 実装エージェントに渡せる
  • READY_WITH_WARNINGS: 渡すことはできるが注意点がある
  • NOT_READY: Critical/Major の問題があり、仕様の補強が必要

デフォルトの経路は --no-llm ヒューリスティック検査です。CIやPR Reviewでは、結果が速く再現可能であることが重要だと考えたためです。OpenAI Platform または Codex ベースの詳細レビューも付けられますが、現時点ではより深く見たいときに選択的に使う補助経路として位置づけています。

v0.4.0で追加したもの

今回の v0.4.0 では、Codexアプリ向けプラグインMVPを追加しました。

pip install spec-guard  
specguard --help  
codex plugin marketplace add KoreaNirsa/spec-guard --ref main

Codexアプリで SpecGuard Plugins ソースを選択し、SpecGuard プラグインをインストールすると、Codex内でSpecGuardの実行を依頼できます。たとえばサンプル仕様を作成したあと、

specguard example copy specs/your-feature-name --force

Codexでそのフォルダを開き、次のように依頼できます。

1. @SpecGuard specs/your-feature-name について SpecGuard を実行して。  
2. @SpecGuard specs/your-feature-name の仕様パッケージに対して SpecGuard を実行し、READY/NOT_READY 状態と主要な finding を要約して。  
3. @SpecGuard specs/your-feature-name について SpecGuard を実行して。デフォルトのヒューリスティック検査で進め、結果の状態と次にやるべきことを要約して。

プラグインはSpecGuardエンジンを新たに実装するものではありません。既存の specguard CLI を呼び出し、生成された結果を読んで現在の状態と次のアクションを要約します。

SpecGuardで READY 状態になったら、実装エージェントに渡せるハンドオフ文書を作成し、その後Codexが実装を開始する流れを想定しています。

PR Reviewもサポートしています

GitHub Actions ベースの SpecGuard PR Review ワークフローも提供しています。

PRで仕様パッケージが変更されたときにSpecGuard Reviewを実行し、その結果をPRに残す流れです。この機能は OpenAI を呼び出して実行されます。

目標は「AIが作ったコードレビュー」ではなく、「AIに渡す前の仕様入力物レビュー」です。

チームで次のようなルールを設けたいときに使えます。

  • NOT_READY の仕様は実装に渡さない
  • Critical/Major の finding をPRで先に可視化する
  • 実装成果物ではなく、まず要件入力の品質を管理する

インストールはCLIで specguard actions install-pr-review を使うか、Codexに @specguard SpecGuard PR Review ワークフローを設定して。 と依頼して設定できます。

ただし、まだ試験機能のため自動セットアップはサポートしておらず、GitHub Secret に以下のように設定する必要があります。

SPECGUARD_OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx  
SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano  
SPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name

現在の状況と限界

まだ初期バージョンのため、あらゆる仕様を完全に判定できるツールではありません。

ただ、AIコーディングを使う中で「仕様が弱いために実装がぶれる問題」を経験している方であれば、実装前に一度ふるいにかける安全装置として使ってみる価値はあると思います。

フィードバックをいただきたいです。特に次の点が気になります。

  • どのような種類の仕様でうまく合うか
  • どの finding が過剰か、あるいは不足しているか
  • Codexプラグインの流れが実際に使い物になるか
  • PR Reviewで強制することがチームのワークフローに合うか

現在はまだベータ版以前で、ようやく開発が進み始めた段階ですが、今後は実務で十分使えるプロジェクトに育てていきたいと思っています。

関心のある方の issue / PR も歓迎します。現在、リポジトリの issue と PR は主に英語で管理していますが、日本語で書いていただいても大丈夫です。

GitHub : https://github.com/KoreaNirsa/spec-guard

関連記事

1件のコメント

 
veltrix 6 일 전

このプロジェクトのより詳しい内容は https://nirsa.tistory.com/487 でご確認いただけます。