AI エージェントと使う
要件を 手形 (Tegata) に起こす作業は、AI エージェントに任せられます。その手形が何を許可するかの責任までは、エージェントに移せません。
この境界があるから、エージェントを使う意味があります。レビューする対象がアプリケーション中に散った適用コードではなく、1 つの仕様になるからです。Ninka はその仕様を検査してコンパイルしますが、元の要件が正しかったかどうかは判断しません。
1. Ninka の作業ルールをエージェントへ渡す
npx ninka-authz init
init は AGENTS.md を作成します。既にファイルがあり、Ninka の節だけが無い場合は、その節を追記します。生成されるルールは、次のようなことをエージェントに求めます。
- 認可を手形として管理する
- ポリシーを変更したらコンパイルする
- アプリケーション側では生成された Consumer Projection を使う
- 要件の解釈で判断した点を、レビューできる形で残す
一方、既存の AGENTS.md に Ninka の節がある場合、init はその節を上書きしません。つまり AGENTS.md は、現在エージェントが実際に読む指示ではありますが、Ninka のバージョンに合わせて自動更新されるファイルではありません。アップグレードでコマンド名や作業手順が変わった場合は、コミット済みの Ninka セクションも確認してください。
Ninka がエージェントだけに渡す、別の隠れた認可ルールはありません。
2. AI には認可仕様を書かせる
エージェントには、認可要件と、その要件を subject・action・resource・conditions・relationships に対応づけるために必要なアプリケーション側の情報を渡します。
レビューする対象は手形です。生成された認可ロジックをアプリケーションコードの各所へ直接書かせることが目的ではありません。
要件の解釈が必要だった場合は、その判断を audit.ambiguities に記録します。たとえば「自分のドキュメント」という要件なら、どの subject 属性と resource 属性を所有関係として扱ったのかを明示します。
audit はレビューのための情報であり、認可判定自体は変えません。正確なデータ構造は 手形 (Tegata) と 手形スキーマ を参照してください。
プロジェクトが閉世界の 語彙 を使っている場合、未宣言の role・action・resource type・対象属性はコンパイルエラーになります。AI が新しい語を勝手に使っても、その追加が語彙ファイルの diff に現れないまま認可仕様へ入り込むことはできません。
3. 診断は修正の材料として使う
提案された手形をコンパイルします。
npx ninka-authz compile
スキーマや関所の診断は、Ninka が機械的に検出できる構造上・意味上の問題を示します。AI エージェントは、その診断をもとに手形を修正できます。
ただし、コンパイルに成功したからといって、認可要件が承認されたわけでも、要件の解釈が正しかったと証明されたわけでもありません。成功したのは、その実行で行われた検査とコンパイル工程です。
4. 変更を受け入れる前に、人間がレビューする
責任の境界は、人間が認可仕様をレビューするところにあります。元の要件と手形を突き合わせ、allow / deny の範囲、条件、関係、audit.ambiguities に残された解釈を確認します。
Authorization Reference や生成された validation は、そのレビューを助ける証拠です。レビュー自体の代わりにはなりません。詳しくは 認可をレビューする を参照してください。
Ninka は「人間が承認した」という状態をローカルに保持しません。承認は、プルリクエストで手形の差分を確認するといった、開発・変更管理のプロセス側で行います。
5. 移行では、Ninka の外に残る認可も報告させる
既存アプリケーションへ Ninka を導入する場合、手形の diff だけで移行前の認可挙動をすべて表せるとは限りません。
AI エージェントには、少なくとも次を明示させてください。
- Ninka へ移したもの
- まだ別の認可経路に残っているもの
- 意図的に変更しなかったもの
- 確信を持って分類できなかったもの
この報告はレビューの材料であって、Ninka が網羅性を検証した証明ではありません。旧実装との比較や認可の切り替えについては OPA から移行する を参照してください。