ax-audit

AX Audit

エージェントがユーザーに代わって操作するアプリの、機能レベルのレビューです。問いは一つです。信頼に値するか、そしてどこで破綻するか？

• 対象： アーキテクチャ（rules-arch/）と信頼（rules-ax/）にわたる、エージェント機能を備えた画面（チャット、ツール実行、設定、ダッシュボード）のルールベースの監査です。リリース準備の判定と AX Relationship Summary で締めくくります。
• 対象外： 従来型のフロントエンド UX（ui-design の Audit モードを使用してください）、開発者向け API、CLI、型の使いやすさ（dx-audit を使用してください）、公開サイトやドキュメントのエージェントスコア（agent-ready を使用してください）、エージェント向け指示ファイル（agents-md を使用してください）、プロダクトが存在する前に何をすべきか（product-design を使用してください）。

対象となるエージェント機能がない場合は、ここで終了してください。フォームやリストに AX ルールを適用しても、ノイズになるだけです。

目次

• 監査ワークフロー
• 2 つのルールレイヤー
• 重大度と判定
• AX Relationship Summary
• 参照ファイル
• 注意点
• 監査のセルフチェック
• 関連スキル

監査ワークフロー

AX Audit progress:
- [ ] Step 1: Scope, via the diff against the PR base merge-base (PR mode) or explicit path (full sweep)
- [ ] Step 2: Detect agentic features per references/feature-playbooks.md
- [ ] Step 3: Run each detected feature's playbook in order, plus the diff-wide checks (PR mode only)
- [ ] Step 4: For each check, load the rule file and follow its detection recipe
- [ ] Step 5: Tier each finding per references/ship-readiness.md (rule override table wins)
- [ ] Step 6: Render verdict + findings + AX Relationship Summary per references/output-format.md
- [ ] Step 7: Run the audit self-check and report its evidence counts

PR モードの対象範囲は、差分と、それが触れるツール定義およびオーケストレーターです。変更されていないファイルに関する指摘は、今回の判定ではなく、全体監査で扱います。プレイブックの注釈はスキャン用のコピーであり、ルールファイルが正となります。parity-orphan-ui-action はすべての PR モード監査で実行し、差分を読み取る対象がない全体監査では実行しません。

ルールの grep では、最も一般的な識別子を指定していますが、すべてのフレームワークでの表記を網羅しているわけではありません。コード上でゲート、ストリーム、ツールの結果などが明らかに存在するのに grep で見つからない場合は、unknown と記録する前に、references/framework-signals.md でそのスタックにおける名称を確認してください。

2 つのルールレイヤー

レイヤー	フォルダー	ルール数	プレイブックで指定された場合に読み込むもの
1：アーキテクチャ	rules-arch/	11	rules-arch/<category>-<slug>.md
2：エクスペリエンス	rules-ax/	13	rules-ax/<category>-<slug>.md

カテゴリ：arch = parity、granularity、context、comm。ax = trust、control、context、comm。同じ接頭辞でもルールは異なります。rules-arch/comm-no-approval-gate.md（実行経路にゲートがない）と、rules-ax/control-no-approval-gate.md（ゲートはあるが、リスクに見合っていない）は別のルールです。

まずレイヤー 1 の comm／parity と、レイヤー 2 の control／trust を実行してください。ここにリリースを阻む問題があります。カテゴリーマップ：rules-arch/_sections.md、rules-ax/_sections.md。

優先度	レイヤー	カテゴリ	接頭辞	ルール数
1	arch	Communication	comm-	3
2	arch	Parity	parity-	4
3	ax	Control	control-	4
4	ax	Trust	trust-	3
5	arch	Context	context-	2
6	ax	Communication	comm-	4
7	ax	Context	context-	2
8	arch	Granularity	granularity-	2

重大度と判定

重大度は 3 段階です：release-blocker、fix-this-sprint、backlog。定義、汎用的なサーフェスによる重大度の引き上げ、判定ロジックは references/ship-readiness.md に記載されています。

優先順位：ルール固有のサーフェス上書き表 > 汎用的な引き上げ > defaultTier。調整は最大 1 回まで適用してください。

判定：✅ READY（ブロッカー 0 件、スプリント内対応が 3 件以下） · ⚠️ READY WITH FOLLOW-UP（ブロッカー 0 件、スプリント内対応が 4 件以上） · ❌ NOT READY（ブロッカー 1 件以上） · 🚫 INCOMPLETE（セルフチェック失敗）。

ブロッカーは監査未完了より優先されます。release-blocker が 1 件以上あり、セルフチェックに失敗した場合は、❌ NOT READY と報告し、その下にセルフチェックの失敗を記載してください。ブロッカーは確認済みの指摘事項であり、引き続き対応可能です。一方、🚫 は「何も分からなかった」と受け取られ、読者を遠ざけてしまいます。🚫 は、ブロッカーがなく、監査範囲を保証できない場合にのみ使用してください。

AX Relationship Summary

エージェント機能が検出された場合は、指摘事項の後に出力してください。指摘事項はエンジニア向けであり、こちらはデザイナーと PM 向けです。項目は 4 つです：進化段階（ラベルではなく、挙動を記述）、信頼の兆候（高／中／低と、その理由を 1 行で記述）、主なギャップ（実行可能な文を 1 つ）、信頼に関する問い（調査でしか答えられない問いを 1 つだけ）。

参考ファイル

ファイル	読むタイミング
references/feature-playbooks.md	ステップ 2～3：検出ヒューリスティクス、機能ごとの順序付きチェック、差分全体のチェック
references/framework-signals.md	ステップ 4：コードで AI SDK、MCP、Claude Agent SDK、または AG-UI を使用している場合。各フレームワークにおけるゲート、ストリーム、完了シグナル、構造化結果の所在、およびルールが基準とする仕様のデフォルト値を確認します
references/ship-readiness.md	ステップ 5：ティアの定義、優先順位、汎用サーフェスによるティアの引き上げ、判定ロジック
references/output-format.md	ステップ 6：検出結果の JSON スキーマ、概要スキーマ、ターミナルでの表示
references/ax-evolution-curve.md	AX 関係の概要の作成：ステージ、アクションの深さ、見せかけと知性、ルールがなく keyGap に記録される指摘事項
rules-arch/_sections.md	レイヤー 1 のカテゴリ、デフォルトのティア、同時に検出されるペア
rules-ax/_sections.md	レイヤー 2 のカテゴリ、デフォルトのティア、同時に検出されるペア

注意点

• ルールを適用する前に対象範囲を絞ってください。 3 ファイルの PR に対して 24 個のルールをリポジトリ全体で実行すると、リリースを妨げる新たな問題が既存のバックログのノイズに埋もれます。判定が「この PR をマージできるか」を意味しなくなります。
• ルールの上書きテーブルが優先されます。 comm-no-intent-handshake のデフォルトは fix-this-sprint ですが、テーブルではツール実行時に release-blocker と定められています。明示的な上書きに一般的な「ツール実行時は 1 段階引き上げる」というルールを重ねると、バックログの指摘が二重に引き上げられてブロッカーになります。
• AbortController.abort() に接続されていない停止ボタンは、見せかけの操作です。 control-no-escape-hatch は依然として不合格です。ボタンのラベルではなく、abort() の呼び出しを確認してください。そうしないと、ユーザーに偽りの表示をする UI を監査に通してしまいます。
• ストリームを閉じるだけのクライアントの stop() では、エグゼキューターが動き続けます。 useChat().stop() は fetch を中断します。ルートが req.signal を streamText({ abortSignal }) に渡し、ツールの execute がそれを読み取らない限り、ユーザーが Stop を押した後もサーバーは残りのツール呼び出しをすべて完了します。ボタンではなく、シグナルをループまでたどってください。
• ツールのアノテーションはヒントであり、信頼の根拠ではありません。 MCP では、クライアントは信頼できないサーバーからの annotations を信頼できないものとして扱うよう定めています。サードパーティーサーバーの readOnlyHint: true を根拠に自動承認するゲートは、制御権をそのサーバーに渡しています。comm-no-approval-gate はこれを不合格にします。仕様のデフォルト（destructiveHint: true、readOnlyHint: false）が、フェイルクローズの基準です。
• フレームワークの承認フラグはゲートへの入力であり、ゲートそのものではありません。 AI SDK の toolApproval: "user-approval" は tool-approval-request パートを出力して待機します。state === "approval-requested" を描画しない UI や、到着時に addToolApprovalResponse({ approved: true }) で応答する UI には、型システム上のゲートはあっても、ユーザーのためのゲートはありません。オプションではなく、レンダラーと応答呼び出しを確認してください。
• 不在の確認には、記録されたファイル一覧が必要です。 「X がないコンポーネントを探す」grep は、すべて合格の場合も、何もスキャンしていない場合も、何も返しません。まず候補ファイルを列挙し（rg -l <feature-pattern>）、それぞれで逆パターンを確認し、ファイル一覧を証拠として示してください。
• detection: observational ルールは、grep の証拠だけでは不合格にできません。 granularity-static-api-mapping、control-over-conversational、comm-no-generative-momentum、および trust-no-confidence-cues の不確実性勾配に関する部分には、インタラクションフローの判断が必要です。静的な証拠だけの場合は、fail ではなく理由を添えて unknown を返してください。
• ゲートが失敗する場所は 3 つあります。 パスに存在しない（comm-no-approval-gate）、存在するが重要度に合っていない（control-no-approval-gate）、正しいが内容を読み取れない（control-thin-approval-payload）のいずれかです。最初に該当するものを報告し、その順序で修正してください。
• インタラクティブなゲートは、無人実行をカバーしません。 Cron、webhook、キューのエントリポイントからは、プロンプトを出す相手がいないまま同じエグゼキューターに到達します。comm-unrequested-action-no-consent はその経路を監査します。証拠にはエグゼキューターではなく、エントリポイントを記載してください。
• ax-audit-ignore:<slug> コメントは pass ではなく suppressed として数えます。 判定ブロックに件数を記載してください。理由のない抑制自体が warn です。
• 重要度を不必要に引き上げないでください。 comm-no-generative-momentum と granularity-static-api-mapping のデフォルトは backlog です。指摘を 1 つでも release-blocker に引き上げると、PR 全体が ❌ NOT READY になります。そのため、見た目だけの指摘を引き上げると、チーム全体が判定を無視するようになります。
• ui-design の Audit モードの指摘を重複させないでください。 「ローディング状態がない」「エラー時にフォームがクリアされる」は ui-design の対象です。これらを重複して指摘すると、エンジニアが AX レポート全体を無視するようになります。
• 提案しかしない Personally Intelligent エージェントは、成長が止まっています。 メモリの段階は信頼ではありません。evolutionStage.behavior で最も高いアクション段階を示してください。そうしないと、丁寧なチャットボットを過大評価する要約になります。

監査のセルフチェック

次のいずれかに該当する場合は、監査に INCOMPLETE のフラグを付け、証拠として件数（プレイブックで計画されたルール数と実行されたルール数、unknown の割合、抑制された件数）を記載してください。

• 実行されたルール数が、プレイブックで計画されたルール数を下回っている
• unknown を返したルールが 30% を超えている。ここで数えるのは unknown のみで、out-of-scope は含めません。指定されたスコープに存在しないレイヤーのルールに正しく回答し、差分が狭いことも、Step 1 が求めるスコープに沿っています。正しくスコープを設定した監査を INCOMPLETE と判定すると、「何も分からなかった」と読める結論の下に、実際の阻害要因が埋もれてしまいます。
• fail／warn の指摘に file:line の証拠または修正スニペットがない
• すべての指摘が同じティアに分類されている（機械的な一括割り当ての疑い）
• エージェント機能が検出されているにもかかわらず、AX Relationship Summary がない

関連スキル

• ui-design の監査モード：エージェント機能を備えた画面における従来型のフロントエンド UX。エージェント機能に関する PR では両方を実行してください
• dx-audit：対象ファイルは同じですが、読者が異なります。このスキルではエージェントが操作や復旧を行えるかを確認し、dx-audit では API、CLI、型を利用する人にとって使いやすいかを確認します
• agent-ready：コーディングエージェントが公開ドキュメントや HTTP API を見つけられるかを確認します。このスキルでは、製品内のエージェント UX を監査します
• product-design：この監査の前に、エージェント機能が何をすべきかを検討します
• agents-md：CLAUDE.md／AGENTS.md の指示ファイル

メンテナンス専用：evals/evals.json と evals/evaluation-scenarios.md には、このスキルの変更に対する回帰シナリオが含まれています。どちらもユーザータスクの実行時には読み込まれません。