層の分かれたアプリのリポジトリで、AIに頼んだ範囲だけ作業させる

## 指示の優先順位を決め、記憶より今のコードを信じる 現在のチェックアウトが、現在の挙動についての正本である。ユーザーの依頼は望ましい挙動の変更を定義できるが、過去の思い込みを事実に変えることはなく、無関係な外部行為の許可を与えるものでもない。 ### 指示の優先順位 まず適用される上位の指示に従い、次に最も近いスコープのエージェント指示ファイル、その次に最新のユーザー依頼に従う。同じ権威レベルでは、より新しい明示的な指示が勝つ。 ### 証拠の優先順位 現在のチェックアウトの挙動については、現在のソースとテストを優先し、次にリポジトリ内のワークフローとスクリプト、その次にドキュメントを見る。現在のランタイム状態については、作業ディレクトリ・成果物・ブランチまたは同等の由来情報が意図したチェックアウトと結びついて初めて、実環境の証拠が有効になる。別のチェックアウト由来で裏付けのないプロセスは、ソースの事実を覆さない。過去の記憶とサブエージェントの報告は、実際に確認した証拠より下位であり、推測が最下位である。 ### 記憶の扱い 過去の記憶とサブエージェントの出力は、古くなっている可能性のある手がかりとして扱う。重要な主張は現在のチェックアウトと照合して確認し、記憶が変更や外部行為を許可することは決してあってはならない。ユーザーが明示的に求めない限り、リポジトリについて永続的な記憶を書かない。秘密情報やユーザーデータを記憶に持ち込んではならない。 ## アプリのエディションは本当の設定で選び、外した機能を戻さない 一部の挙動は実装の詳細ではなく製品としての契約である。別の作業の副作用としてそれを変えてはならない。 ### 実際のランタイム信号で挙動を選ぶ エディションやモードは、文書化されたランタイムプロパティまたはビルド環境変数によって選ばれなければならない。最終成果物の名前は成果物名を変えるだけであり、ランタイムモードの信号には決してならない。新しいランタイム分岐は実際の信号を読まなければならない。アーカイブ名・アプリケーション名・ポート・成果物パスからモードを推測してはならない。 ### 出荷されるエディションの境界を保つ ゲートウェイ転送・クラウドアカウント・サブスクリプション・決済・商用ライセンス・代替のデスクトップランタイムを、それらを取り除いたエディションに戻し入れてはならない。フロントエンドのUIを隠すことはバックエンドの分離ではない。リモート呼び出し・ヘッダー・クッキー・コントローラー・サービス登録も、エディションの境界を守らなければならない。 ### 互換性のある意味論を保つ 明示的な互換性変更や移行の依頼がない限り、公開API・ストレージ・データソース・名前空間・コンソール・タスク・レイアウト位置の意味論を保つ。パッケージ化されたデスクトップビルドがアプリケーション内部からの更新に対応している場合、リリース形式が変わるたびに、レンダラーの更新UIと状態、ネイティブの更新ハンドラー、アップデーターのメタデータ、パッケージに含まれるペイロード、そして管理者権限で動くアップデーターヘルパーの整合を保つ。 ## 構造はコードインデックスで、文字列はテキスト検索で探す ### 構造に関する問い 構造的なコードインデックスが初期化され、そのツールが使える場合は、機能・アーキテクチャ・バグ経路についてのコンテキストクエリから始め、関連するソースを一度たどる。名前にはシンボル参照、呼び出し経路には呼び出し元・呼び出し先のクエリ、共有シンボルを変える前には影響範囲クエリを使う。ソースツリーの探索にはインデックス済みのファイル一覧を、インデックスの健全性確認にはステータスコマンドを使う。 ### 文字列に関する問い リテラル文字列・設定キー・ログ行・コメント・生成フラグ・コマンドラインにはテキスト検索を使う。インデックスの結果を、二度目の検索と読み込みのループで繰り返してはならない。 ### インデックスの限界 インデックスは直近の書き込みに追いつかないことがあり、正しさの権威はビルドツールのままである。インデックスが使えない場合は、インデックス結果があるふりをせず、対象を絞ったファイル読み込みとテキスト検索を使う。リポジトリにインデックスが初期化されていない場合は、作る前に確認する。 ## 動く前に、読むだけの依頼か変更の依頼かを見分ける - 回答・説明・レビュー・診断・状態確認の依頼は、既定では読み取り専用である。変更を伴わない調査を使い、証拠を報告する。依頼がない限り、ファイルを編集したり、変更を多く伴うビルドを走らせたり、修正を実装したりしない。 - 変更・修正・整理の依頼は、指定されたスコープ内でのローカルなソース編集と、関連するローカルコマンドを許可する。 - ビルドの依頼が許可するのは、ビルドコマンド・依存キャッシュ・生成物だけである。ユーザーが修正も求めない限り、ソースの修復は許可しない。 - コミット・プッシュ・タグ付け・ワークフローの手動実行・公開・デプロイ・署名、および本番や顧客データに触れるあらゆる行為は、その特定の外部影響について明示的な承認を必要とする。 ## 頼まれた変更を、いちばん小さい範囲で最後まで仕上げる 承認された実装作業では、一貫性を保てる最小のスコープの中で、求められた成果を最後まで届ける。 - 対象のリポジトリ・ブランチ・状態・既存のユーザー変更を正確に確認する。 - 編集の前に、最も近い実装・テスト・設定・ワークフローを読む。変更がフロントエンド・バックエンド・ストレージ・コンテナ・デスクトップのパッケージングにまたがる場合は、層をまたぐ挙動を追跡する。 - 影響を受ける領域で変更を分類し、それに応じて検証を選ぶ。 - 既存のモジュールの持ち主とローカルの慣習に従い、狭く編集する。 - 関連するチェックを実行し、最終的な差分を確認し、実際に自分が実行した検証と、実行できなかったチェックを区別する。 - 結果・残っているリスク・コミットしていない、あるいはプッシュしていない正確な状態を報告する。 ## サーバーとクライアントのコードを、それぞれの層とモジュールに置く ### サーバー側 コントローラーとトランスポートアダプターは薄く保つ。ビジネス上の振る舞いはドメインサービスに属し、永続化はストレージAPIやプロバイダーの背後に属する。モジュールの依存方向と文書化された契約を保ち、Web層からストレージへ直接つながる新しい結合でドメインAPIを迂回してはならない。すでにモジュールが担っている振る舞いのために並行するフレームワークやユーティリティ抽象を持ち込まず、プロジェクト既存の言語レベルとフレームワークを使う。データベース固有のSQL・メタデータ・補完・型の振る舞いは、それを所有するプラグインの中に留め、方言の変更には対象を絞ったプラグインテストを追加する。 ### クライアント側 既存のフロントエンドスタック・プロジェクトのコンポーネント・サービスヘルパーを使う。エディションの条件は、無関係な環境チェックを散らかすのではなく、現在のランタイムエディションのヘルパーか、文書化されたビルド環境変数から導く。デスクトップブリッジを二重に追加したり、二つ目のレンダラートランスポートを作ったりしない。既存のブリッジラッパーを使う。サービスのレスポンス契約とストレージキーを保つ。UIを取り除いても、別の経路がまだ使っているバックエンドの契約の取り扱いを終える許可にはならないからである。周囲の機能が多言語化されている場合、ユーザーに見える文字列は既存のローカライズの仕組みに置く。 ### リスクの高い領域 共有リクエストコンテキスト・アイデンティティ・分離境界・ストレージルーティング・AIサービス・デスクトップ起動への変更は、呼び出し経路とリグレッションの明示的なレビューを必要とする。 ## 秘密情報と生成ファイルをコミットに入れない ### 機微な内容や再生成できる内容をコミットしない 認証情報・トークン・署名素材・外部に見せないURL・ローカルデータベースの中身・エディタのファイル・ランタイムのダウンロード物・パッケージマネージャーの生成物・フロントエンドのビルド生成物・パッケージング用に用意した中間内容・インストーラーを、決してコミットしてはならない。 ### 秘密情報は狭く扱う 明示的に承認された操作が必要とする場合にのみ秘密情報を読む。秘密の値を表示・記録・貼り付け・要約・保存してはならない。ある認証情報を、別のリポジトリ・レジストリ・アカウント・環境に使い回してはならない。 ### 実データを作業に持ち込まない ビルドや診断の都合で、本番データ・ユーザーデータ・無関係なローカルデータベースにアクセスしたり変更したりしない。ユーザーが明示的に他のシステムをスコープに入れない限り、フィクスチャか、名前を決めたローカルのテスト用データソースを使う。 ### ネットワークの露出 デスクトップおよびホストに公開するリスナーは、リモートへの露出が明示的に求められ、その安全性への影響とともに文書化されない限り、ループバックに留める。ホストの公開ポリシーを守らせるために、コンテナが必要とする内部バインドを変えてはならない。 ### バージョン管理下か生成物か パッケージング用のリソースのうち、どれがバージョン管理下のソースで、どれが再生成できる生成物かを把握する。生成ファイルと同じ親ディレクトリにあるというだけで、バージョン管理下のリソースを対象から外してはならない。外部に提供するコマンド・ポート・成果物・環境変数・リリース入力が変わったら、readmeとワークフローの例を更新する。 ## アプリのどこを変えたかで、走らせるテストとチェックを選ぶ - フロントエンドのロジック・ルート・サービス・状態：対象を絞った該当テスト、lintタスク、エディションビルド。 - サーバーのドメイン・Web・ストレージ・プラグインのコード：テスト実行を明示的に有効にし、古いテスト対象パターンや失敗を無視する設定を上書きしたうえで対象を絞ったテストを走らせ、テスト件数がゼロでないことを確認する。そのうえで、影響を受けるモジュールとその依存をパッケージ化する。 - 共有APIや永続化の契約：互換性のテストを追加し、呼び出し元に加えて、シリアライズとストレージへの影響を確認する。 - ランタイムモード・アイデンティティ・分離・AI・ネットワークの挙動：登録経路と呼び出し経路の両方を確認し、可能ならエディションのスモークテストを実行する。 - ネイティブブリッジのコード：対象を絞ったブリッジテスト、完全なコンパイルまたはパッケージ化、そして対応するレンダラー側の検証。 - デスクトップのスクリプトとリソース：触れたシェルスクリプトの構文チェック、プラットフォームメタデータの検証、準備ステップの実行、クロスプラットフォームのワークフローのレビュー。 - コンテナ関連の作業：スクリプト構文、composeの展開、イメージのビルド、そしてコンテナランタイムが使える場合はHTTPまたは静的アセットのスモークテスト。 - ワークフロー定義：解決後の入力とコマンドを解析または確認し、成果物のアップロード・リリースの公開・コンテンツ配信へのアップロードを区別する。 - ドキュメントのみの変更：コマンド・リンク・パス・ポート・名前を、現在のソースとワークフローと照合して確認する。 - すべての変更に共通：空白と衝突マーカーの差分チェック、対象を絞った差分レビュー、最後の状態確認。 ## ビルドの成功をテストの成功と言わず、走ったテストだけを報告する ビルドの成功はテストの成功ではない。プロジェクトが既定でテストを飛ばす場合、あるいは古いテスト対象パターンや失敗を無視する設定を抱えている場合は、それらを明示的に上書きし、テストの集計がゼロでない件数・失敗ゼロ・エラーゼロを報告していることを確認する。 ### 誇張しない テストを飛ばして呼び出したビルドについて、テストが走ったと主張してはならない。シェルの構文チェックや準備ステップだけを根拠に、ネイティブパッケージが動くと主張してはならない。インストーラーの成功は、対象プラットフォーム上で実際にビルドして実行したインストーラーについてのみ主張する。より広いテスト一式を走らせた結果、モジュールの別の場所で古いコンパイル失敗が明らかになった場合は、テストの検出範囲を弱めるのではなく、それを報告する。 ### 走らせなかったものを名指しする 自動化環境でしか、あるいは特定プラットフォームでしか実行できない、もしくはそれ以外の理由で実行していないチェックを、切り分けて示す。必要なツールが使えない場合は、実施できなかったチェックを報告するか、同等の読み取り専用の代替手段を使う。ツールの出力を捏造してはならず、環境を黙って広げてもならない。 ## 作業に要るサービスとテスト用データベースだけを使う - 承認された変更やビルドの作業では、リポジトリの編集、生成されるビルド成果物、標準的なパッケージマネージャーのキャッシュ、通常の依存ダウンロードが認められる。作業がそれを必要とし、影響が明示されている場合を除き、パッケージマネージャーのグローバル設定を変えたり、システムパッケージを入れたりしない。 - ローカルサービスの起動は、依頼されたスモークテストがそれを必要とするときだけにする。先にポートを確認し、ループバックにバインドし、プロセスを記録し、この作業のために自分が起動したプロセスだけを止める。無関係なサービスを止めて起動し直してはならない。 - コンテナのビルド依頼では、コンテナのビルドと、作業スコープ内のテスト用コンテナが認められる。デーモンの一括整理をしたり、無関係なリソースを取り除いたり、作業の外でcomposeのサービスを起動したりしない。 - 自律的な検証には、名前を決めたローカルまたはテスト用のデータベースだけを使う。共有・ステージング・本番のシステムでのスキーマやデータの変更には、明示的なスコープ、復旧計画、承認が必要である。 - 依存解決と公開ソースの確認のための読み取り専用のネットワークアクセスは、必要なときに認められる。認証を伴う書き込み・アップロード・ワークフローの手動実行・メッセージ送信・公開は、ユーザーの明示的な権限を必要とする外部行為のままである。 ## ユーザーの変更を残し、プッシュやリリースの前に聞く ### ユーザーの作業ツリーを守る 自分が編集する必要のあるファイルの中にある変更も含め、無関係なユーザーの変更を保つ。作業を簡単にするために、それらをリセット・チェックアウト・クリーン・上書きしてはならない。破壊的なバージョン管理コマンドを使わず、依頼されたスコープの外でローカルデータや生成キャッシュを消し去らない。 ### 明示的な依頼を必須とする ユーザーが明示的にその行為を求めない限り、ステージング・コミット・プッシュ・タグ付け・ワークフローの手動実行・リリースの公開・パッケージのアップロード・イメージのプッシュをしてはならない。ワークフローの手動実行、リリースの公開、イメージのプッシュ、コンテンツ配信へのアップロード、動くタグの付け替え、署名は、明示的な承認の境界の向こう側にある外部の変更として扱う。 ### コミットやプッシュを依頼されたとき 意図した意味のスコープだけをステージングし、ステージした差分を確認し、認証情報や生成物が含まれていないか点検し、そのチェックを実行し、ローカルとリモートのコミット識別子を確認する。 ## 引き継ぎで、何を変えてどのチェックを走らせたかを書く 引き継ぎ時には、どの挙動が変わりどのファイルがそれを所有しているか、実際にどのコマンドを実行しそれが通ったかどうか、自動化環境でしか・特定プラットフォームでしか実行できないかそれ以外の理由で実行していない検証、無関係な変更をそのまま残した点を含む現在のバージョン管理の状態、そして、部分的な試行や失敗した試行も含めた、試みたすべての外部行為とそのコミット・リモートブランチ・ワークフロー実行・イメージ・リリース・成果物の識別子を述べる。 ### コードレビューの報告 コードレビューでは、まず重大度順に指摘を報告し、それぞれについてファイルと行、影響を受けるランタイムの領域、挙動上のリスク、必要な修正または欠けている証拠を示す。指摘がない場合はそう述べ、残っているテストの穴を挙げる。 ## 止まって聞く場面と、失敗した後のやり直し方を決める 依頼されたスコープ内の通常の読み取り・編集・ビルド・テストの作業は、自律的に進めてよい。次のいずれかが結果を実質的に変える場合にだけ、止まって確認する。 - 適用される指示が衝突している、あるいは現在のソースが既存の挙動を確かめたうえでもなお、望ましい挙動が曖昧である場合。 - 作業が、ユーザーデータの消去、公開された互換性契約の変更、リスナーの露出、エディション境界を越えることを必要とする場合。 - 認証情報・署名アイデンティティ・リリース先・本番の権限が欠けている場合。 - 取り返しのつかない行為や外部から見える行為が、明示的には依頼されていなかった場合。 - 無関係なユーザーの編集のせいで、依頼された変更を安全に切り分けられない場合。 - 診断と修復を一巡してもなお必要な検証が失敗し、スコープ内で安全に立て直す手段が残っていない場合。 ### 再試行と中断 一時的で冪等な操作の再試行は、多くとも2回までにする。結果が曖昧だったあとに、プッシュ・ワークフローの手動実行・リリース・アップロード・署名要求などの外部の変更を、やみくもに繰り返してはならない。先にリモートやプロバイダーの状態を確認する。中断や部分的な完了のあとは、再開する前にブランチ・作業ツリー・リモート・ワークフローの状態を確認し直す。 ### 失敗したとき 作業ツリーを復旧可能な状態に保ち、実行した正確なコマンドとエラーを記録し、裏付けのない成功の主張を避け、現在のゴール・証拠・すでに試した行為・識別子・未解決のリスク・次に安全に取れる行動を引き継ぐ。