AIのレビューと修正を自動で回すツールを、ユーザーのコードを失わずに作る

## コードを直す前に、ビルド定義と担当を書いた文書を読む コードを変更する前に、リポジトリのエントリーポイント、パッケージ構成図、ビルド定義、責任分担文書を読む。生成された複製や簡易要約は参照先を示すものとして扱い、競合する正本にしない。 ### リポジトリの把握 - 実行可能なエントリーポイント、実装パッケージ、共有基盤、ビルドシステムの場所を特定する。 - 古くなりうるコマンドをガイドへ転記せず、ビルド定義から現在のコマンド一覧を得る。 - 外部向け動作、設定キー、環境変数、運用上の不変条件ごとに、どの文書またはソースファイルが正本かを特定する。 - ホスト固有のアダプターを明示する。外部CLIの想定バージョンを固定し、worktreeの状態によって高水準コマンドが不安定になる場合は、安定したAPIの代替経路を使う。 ### 検証ゲート - 引き渡し前にformatとlintを実行し、生成物のdrift検査も含める。 - 反復中は対象を絞ったテストを実行し、その後、変更した境界に必要な正本のunit、integration、race、end-to-end suiteを実行する。 - プロセス、I/O、設定、Git、daemon、記録済みfixtureの動作にはend-to-end testを優先し、純粋なhelperはunit testで高速かつ局所的に確認する。 - 自明でない変更後は実際の実行ファイルをbuildする。 - bug修正とfeature開発にはtest-driven developmentを使い、未解決作業を無関係な編集へ隠さずissue trackerに残す。 ## キャンセルで子プロセスまで止め、Gitのディレクトリをはっきり渡す 長時間動く自動処理は、対応する全OS上でcancel、子孫プロセス、共有状態、filesystemへの影響を自ら管理しなければならない。 ### プロセス規律 - 長時間処理、subprocess、network処理へcancel contextを渡す。 - cleanup、probe、HTTP呼び出しには上限付きtimeoutを派生させる。 - cancel可能なsubprocessをprocess treeの境界内へ置き、直接の子だけでなく子孫もcancel時に終了させる。 - 正常終了、error、cancelのいずれでもprocess groupを回収する。継承されたpipeや残存する孫processをrunより長生きさせない。 - platform固有のchild-process強化を、1つの冪等なwrapperで適用し、background処理が不要なconsoleを開かないようにする。 - 共有する可変状態を標準の同期primitiveで保護し、goroutine、channel、worktree、一時directoryの所有者を明示する。 ### filesystemとGitの規律 - platform対応のpath helper、application所有のstate root、文書化されたfile modeを使う。 - platform aliasによって同じpathの比較結果が変わりうる場合はsymbolic linkを解決する。 - bare repositoryに対するGit操作は、Git directoryを明示的に渡すhelper経由にする。強化済みGit設定の下でcurrent directoryからの自動検出に依存しない。 - 所有権とlifecycle記録から安全だと証明できる場合にだけ、stateを取り除くか置き換える。 ## 動かすコマンドは、信頼できるブランチの設定だけで決める commandや実行可能agentを選ぶ設定はcodeである。信頼済みrevisionからだけ読み込み、contributorが制御できる設定と指示は信頼しないdataとして扱う。 ### 信頼できる入力 - fresh fetchで信頼済みdefault branchを解決し、code実行を選択する設定を読む前にcommitを正確に固定する。 - 信頼済みcommitまたは現在の設定をfetch、read、parseできなければ中止する。契約が許す場合、読める信頼済みtreeに設定が存在しない状態は有効としてよい。 - command selector、agent selector、documentation policy、project instructionの適用除外、repository commandの許可は、信頼済みcopyからだけ読む。 - repository commandの許可は既定で無効にする。pushされたbranchが自分自身へ実行権限を与えたり、信頼済みpolicyを弱めたりしてはならない。 - 実行を伴わないfeature設定は分離し、branch固有の動作が実行境界を越えないようにする。 ### 閉じる側へ倒す処理 - userまたはrepository由来の内容をagent promptへ入れる前に、敵対的な制御文を無害化しsecretを伏せる。 - instruction抑制optionが選択中のadapterで実際に機能することを、起動前に確認する。 - fetch、parse、authorizationの失敗後に、信頼できる状態を捏造しない。 - pushされた内容がcommandを自己承認したり、信頼済みpolicyを置き換えたり、閉じる側へ倒す動作を迂回したりできないことをregression testで証明する。 ## 常駐サービスを1つだけ動かし、ジョブ実行中の停止や更新を断る machine全体で動くserviceには、singleton所有、socket安全性、復旧、破壊的lifecycle commandをそれぞれ独立して防御する必要がある。 ### singletonと復旧 - 復旧処理やsocket bindより前にOSの排他lockを取得し、processの生存期間中は保持する。 - kernel lockが保持されている事実を生きた所有者の証拠とする。そのlockに独自のstale判定を持ち込まない。 - 既存socketを取り除く前にprobeし、connectionとhealth checkには別々の上限付きtimeoutを設定する。 - serviceの実行は明示されたmodeからだけ開始する。継承されたenvironment variableで通常のprobeをworkerとして解釈し直さない。 - startup cleanupをstate-awareにする。job記録がpendingまたはrunningのworktreeやresourceには触れない。 ### lifecycle制御 - active jobがある間は、operatorが明示的な破壊overrideを指定しない限りstop、restart、updateを拒否する。 - 非対話のconfirmation flagでactive-job guardを迂回させない。 - 処理を妨げているjobを列挙し、processとparentの帰属情報を含めてlifecycle呼び出しを監査記録へ残す。 - CI監視の上限をidle timeoutとして扱う。確認済みのupstream進捗があった時だけ再設定し、既存deadlineを短くせず、進捗を確認できなければ安全側で失敗させる。 - orphan abort処理を冪等にする。agent待機時刻は観測値に限定し、gateが実際に停止している間だけ設定し、gateの解決方法を変える用途には使わない。 ## レビューと修正のセッションを分け、変更を頼まれた目的と比べる reviewは、信頼しないtext、反映時期、fixerの説明によって判断を歪めず、完全な変更内容をsourceで確認できるintentと比較しなければならない。 ### intentとfinding - intentの出所を保持する。明示されたintentは権威あるacceptance criteriaとして扱い、推定したintentはconfidenceの低い手掛かりとしてだけ扱う。 - どちらにも同じ無害化、secretの伏せ字、非実行guardを適用する。 - fixerの変更が明示criteriaに反する場合は、userへ確認するfindingへ変換してrunを停止する。 - 反映前reviewでは、後続pipeline stageが担当する結果だけを対象外にする。外部または既存のlifecycle要件は引き続き検査する。 - finding actionが欠落または未知なら閉じる側へ倒し、自動修正可能とは扱わずuser確認に分類する。 ### sessionと修正の規律 - runごとに永続的なreviewer sessionを1つ、別に永続的なfixer sessionを1つ持つ。役割間でstateを共有してはならない。 - session再利用はreview loopだけに限定し、最小限のidentity情報だけを保持してpromptやtranscriptは保持しない。 - resumeに未対応、またはresumeが失敗した場合はそのidentityを破棄し、同じ役割のturnを新規状態で繰り返す。cancel後は再試行しない。 - 再reviewのたびにbranchの完全なdiffを対象とした敵対的reviewを行う。 - 1回のfix roundでは全修正を先に適用し、変更箇所に限定した検証を1回実行する。正本となるfull-suite testとlint gateは専用stageに任せる。 ## 生成される文書はソース側で直し、利用状況の記録にプロンプトやコードを入れない 各事実の正本を1つに保ち、派生guideを正本から再生成し、localの詳細な診断証拠と上限付きremote analyticsを分離する。 ### documentationと生成内容 - overview文書は簡潔に保ち、詳細なreference事実は指定の正本へ置いてguideからlinkする。 - 責任範囲が移動したらownership mapを更新する。 - 生成されるagent guidanceはsource側を編集し、承認済みbuildでartifactを再生成し、driftがあればlintを失敗させる。 - 同じ運用契約を表すsource guidanceと利用地点のcommand表示は一緒に変更する。 - 1回のagent処理がdocumentationとlintを兼ねる場合は、各resultを正確に1回ずつ消費する。resultが省略、無効、または信頼できない場合は独立した処理へ切り替える。 - documentation編集は今回の変更で古くなった範囲に限定し、全corpusの網羅scanを再導入しない。 ### プライバシーを守るobservability - 読み取り専用画面ではページビューを送らない。リモートのコマンドイベントは、状態変更と上限付き間隔の両方で制御する。 - mutation eventは完全な精度で保ちつつ、詳細なperformance証拠はlocalだけに保存する。 - invocation metricにprompt、応答、diff、secret、生のcommand argumentを保存しない。remote analyticsへrun identifier、path、session identity、呼び出し単位のrecordを送らない。 - terminal eventでは上限付きaggregate countだけを送る。 - metric定義と計測境界の実装を1つの正本へ集約する。取得不能値は捏造した0ではなくnullで表し、必要なら累積session値の差分からround単位の使用量を計算する。 ## force pushの前にリモートを確かめ、リリース用のビルドに必ず署名する 最優先の不変条件はuser codeを守ることである。観測できていない作業を上書きしかねない巧妙な復旧を試みず、安全でない同期や反映を拒否する。 ### repositoryとbranchの安全性 - pull requestのbase routingと任意のfork push先を分離する。hostがfork routingを最後まで扱えない場合は、不正なself requestを作らず作成自体を見送る。 - 通常同期はcleanなstrict fast-forward、またはpipeline headと完全に結び付いた同等divergenceの証明済み移動に限定する。 - passive statusではfetchもmutationも行わない。blocked pathではreset、stash、merge、rebase、force、switch、branch破棄、external remote更新を行わない。 - pushした正確なcommit、credentialを含まないtarget identity、generationを保持し、同期適用の直前に可変な前提をすべて再確認する。 - 未反映のterminal workをrecovery referenceで保護する。recoveryがclean worktreeを動かせるのはstrict fast-forwardだけとし、local workを保持する場合は新しいpipelineを起動せずcompare-and-swapでgateを更新する。 - rebase baseはfresh fetchした権威あるremote referenceから求める。未pushのdefault-branch commitが変更範囲を暗黙に広げる場合は停止する。 - force push前にremote headを再取得し、新規branch、同一head、前回観測から変化のないhead、またはremote追加commitがpatch identityで同等と証明済みの場合だけ進める。lookupや証明に失敗したら閉じる側へ倒す。 - leaseの基準はrunが実際に最後に観測したheadとし、force直前にfetchしたtipへ置き換えない。 ### releaseとdependencyの安全性 - 永続的なsigning contractを持つplatformでは、archive作成やchecksum計算の前に、固定application identity、hardened runtime、安全なtimestampで全official artifactへ署名する。 - signing credentialをrelease jobだけに限定し、一時storageへ取り込み、成功時も失敗時も取り除く。 - signatureが欠落または曖昧、identityやarchitectureが不正、identity要件が可変、hardeningがない、timestampがない場合はrelease検証を失敗させる。 - notarization、packaging format、universal binaryは、release contractに含まれない限り別scopeとして扱う。 - dependency追加前に現在の権威あるdocumentationを確認し、変更についてuserと相談する。 - format、lint、focused test、integration test、full suite、build check、documentation check、release固有検証の実結果が揃うまでreadyと報告しない。