Open source Agent Skills for AI code review
バグ修正を過剰修正なしに確かめ、機能の意図を問い、リファクタリングを守り、テストの検出力を評価する。
4つのReview Typeを、ひとつのワークフローで。
THE PROBLEM
テストがGreenでも、それだけでは変更意図や期待する振る舞いは証明できません。 AIが大量にコードを書くほどDiffは大きくなり、全行を追っても「なぜ変えたか」はコードだけでは確定できません。
Socraticは変更前後を観測可能な振る舞いで比較し、確定できない変更意図だけを人間へ質問。 回答から期待値とテストのOracleを明確にします。
HOW IT WORKS
変更を比較し、意図を明確にし、テストで確かめる。 3つのSkillが、曖昧な不安を判断可能な材料へ変えます。
比較して、論点を絞る
BaseとHeadの変更前後を比較し、仕様判断・振る舞い差・テスト不足を抽出。レビュー全体を組み立てます。
意図を引き出す
実装だけでは確定できない期待を、仕様オーナーが答えられる具体的な質問へ変換します。
反証して確かめる
BaseとHeadへ同じテストを実行し、さらにバグを注入してテストの検知能力を証明します。
THE REVIEW SURFACE
スコアも「Mergeしてよい」という結論も出しません。 確認できた範囲と、決めるべきことと、まだ残るリスクを分けて示します。
USE CASES
報告された不具合の
「解消」を確かめる
報告された失敗と維持すべき周辺の振る舞いを確立し、回帰の再導入と過剰修正の両方を事故Mutationで検査します。
› 報告された失敗の解消を検証
✓ バグを再導入すると対象テストが失敗し、維持すべき振る舞いはGreenのまま。
新しい振る舞いの
「正しさ」を決める
境界条件や例外時の期待を質問にし、仕様オーナーの回答をIntent Contractとテストへ結びます。
› Use $socratic to review this change
? 契約終了日と更新日が同日の場合、更新を許可する仕様で合っていますか？
リファクタリングの
振る舞い差を見つける
HostがMaterializeしたBase/Head Diffから観測可能なInvariantを確立し、対象のHead Baselineを証明した上で、現実的なMutantの失敗を要求します。安定した比較が差を示せば、意図した変更か回帰かを人間へ確認します。
AIが追加したテストの
「検知力」を測る
同じリスクMutationを既存・変更後のテストへ当て、増えた保護と、まだ守られていないリスクを分離します。
SAFE BY DEFAULT
DEFAULT: REVIEW-ONLY（見るだけ）PR・GitHub・手元の作業ファイルを書き換えません
PR、GitHub、手元の作業ファイルには書き込みません。
比較テストと、わざと小さな不具合を入れる検査（Mutation Test）は、使い捨てのコピー上で実行します。確認対象のコードは変更しません。
変更候補への登録（Stage）、履歴への保存（Commit）、GitHubへの送信（Push）、作業の枝分け（Branch）の切替、PR作成、コメント投稿を行いません。
有効性を確認できたテストも、ユーザーが「テストを反映する（Apply tests）」を選ぶまでは追加しません。
HOW IT IS CHECKED
Claude Codeの追加機能が、開始前・操作の直前・結果を出す直前にチェックします。AIへの注意書きだけで安全を判断しません。
依頼を送信した時点（UserPromptSubmit）で、この作業専用の監視役を起動します。監視役や必要な部品を準備できなければ、AIが調査を始める前に「実行不可（blocked）」で止まります。
道具を使う直前の検査（PreToolUse）が、確認対象への編集・保存・差分適用を拒否します。コマンド実行も、安全確認付きの実行役と、内容を見るだけのGit操作に限定します。
小さな不具合を入れる検査（Mutation Test）は、元のリポジトリ（コードの保管場所）の外に作った使い捨てコピー（Sandbox）で行います。書き込み先検査（Isolation Gate）が、コピー外への書き込みや、元のファイルへつながる抜け道を拒否します。
実行ごとの合言葉（Nonce）、設定票（Manifest）、改ざんを見つけられる実行記録（Hash-chain Ledger）、ファイルの指紋（SHA-256）、データ形式（JSON Schema）を照合します。対応するテスト記録がなければ「検知した／見逃した」と報告できません。
大切な前提: この追加機能の事前・直前チェック（Plugin Hook）は、利用者が内容を確認して有効にする仕組みです。利用者にも解除できない会社のルールにする場合は、OS側で管理する強制チェック（Managed Hook）と、必要な操作だけを許可する権限設定を併用してください。
GET STARTED
Claude Code MarketplaceからPluginをインストールすると、安全なHost連携を含むSocraticを利用できます。
詳しい使い方をREADMEで見る> /plugin marketplace add Shogo1222/socratic
> /plugin install socratic@socratic-marketplace
インストール後、信頼済みGit Repositoryで /socratic:socratic を実行
WHY SOCRATIC?
名前はソクラテスの問答法に由来します。分かっていないことを自覚して問いを立て、 対話によって相手の中から考えを引き出し、反駁によって主張を吟味する。 その進め方を、コードレビューの手順にしています。
コードだけでは分からないことを認め、人間が判断すべき変更意図を見つけます。
産婆術のように対話を通じて期待する振る舞いを言葉にし、Intent Contractへ記録します。
意図と異なる振る舞いをあえて作り、テストが実際に検知できるかを確かめます。
RESEARCH ROOTS
Socraticは、変更時にバグを捕まえるテストと、自然言語の意図から振る舞いの変種を作る Mutation Testingという、相互補完的な研究を接続しています。
将来の回帰を防ぐHardening Testと、変更で生じた欠陥を着地前に捕まえるCatching Testを定義し、Just-in-Timeなテスト生成の研究課題を整理した基礎論文です。
Read the paperMetaの大規模バックエンドで22,126件の生成テストを分析。変更を理解する生成と判定器により、人間の確認負荷を抑えながら本番前に重大な欠陥を捕捉できることを報告しています。
Read the paper自然言語で書かれた意図を少し変え、その意図を実装するMutantを生成する手法です。29プログラムの評価で、構文ベースMutationとは異なる欠陥クラスを補完できる可能性を示しています。
Read the paperSocraticのHuman-confirmed Intent Contract、4ブロックのレビュー結果、Copy-ready Commentsは独自設計です。 本プロジェクトは、各論文の著者・所属機関による実装または推奨ではありません。