AI DEVELOPMENT CORE GUIDE / 02
State・Authority・Evidenceを分ける。複数AIでも現在地を失わない運用設計
AI開発では「作業した」「確認した」「公開した」が同じ会話の中で混ざりやすくなります。現在状態、実行権限、検証証拠を別々に持つと、並列実行や担当交代が起きても事実を再構築できます。
STATE
今どこまで進んでいるか
対象のIssue、Branch、HEAD、PR、merge、Deploy、Productionなど、現在地を表します。応答文の自己申告より、GitHubや外部システムの実状態を優先します。
AUTHORITY
誰が何を変更できるか
読み取り、コード変更、merge、Deploy、公開、削除など、実行可能な操作を分けます。担当者がいることと、その操作権限を持つことは別々に確認します。
EVIDENCE
何が確認できたか
CI、レビュー、readback、Production確認などの検証結果です。対象のCommit SHAやDeployment IDへ結び付け、後から同じ対象を指せる状態にします。
DELIVERY LEDGER
開発の各段階で、3つを答えられるようにする
同じ「完了」という言葉を使わず、段階ごとのState・Authority・Evidenceを記録します。
| 段階 | State | Authority | Evidence |
|---|---|---|---|
| Issue | 目的・制約・受入条件 | 誰が着手できるか | 要求と受入条件の記録 |
| PR / HEAD | 現在の変更版 | writer / reviewer | exact SHA・diff・CI |
| Merge | mainへ統合済みか | merge authority | merge commit・checks |
| Deploy | どの環境へ反映済みか | deploy authority | deployment ID・target SHA |
| Production | 公開状態が何か | 公開後の変更権限 | HTTP・画面・機能readback |
Evidenceは対象の版へ固定する
同じPRでもHEADが変われば検証対象が変わります。CIや独立レビューのPASSを再利用する場合は、同じSHAに対する結果かを確認します。Deploymentもtarget SHAとDeployment IDを対応付けます。
Exact SHAの実例を見る結果が不明ならStateを読み直す
タイムアウトや応答停止だけでは、外部処理の成否を確定できません。Netsujoではこの状態をOUTCOME_UNCERTAINとして扱う場合があります。再実行の前にGitHub、Deploy先、外部APIなどの実状態を照合します。
応答停止時の実例を見るNetsujoではControllerが現在地を管理する
ControllerはStateと進行可否、writerなどのAuthorityを管理し、Evidenceを受入条件へ結び付けます。Orchestratorは担当割当、並列実行、復旧、独立検証を調整します。これはNetsujoの運用上の役割分担です。