型付きのモノレポを壊さず直し、プロジェクトのWikiも最新に保つ

## 変更が関わるパッケージ・テスト・文書を先に調べる ルートのエージェント向けガイダンスを、すべてのコーディングエージェントが従う共有契約として扱ってください。ツール固有の指示ファイルは内容を重複させず、薄く保ってその共有契約を参照するようにします。 - コアパッケージ、任意の連携機能、開発者向けツール、エコシステムモジュール、サンプル、ドキュメント、テストがどこにあるか確認してください。 - リポジトリに別の定めがない限り、テストとフィクスチャは対象パッケージの近くにあると想定してください。 - サブシステムを編集する前に、最も近いパッケージのガイダンスを読んでください。 - ファイルに触れる前に、依頼された変更を、その所有パッケージ、公開インターフェース、テスト、ドキュメントまで追跡してください。 - 影響範囲は最小限にしてください。焦点を絞ったタスクをリポジトリ全体の書き直しに広げないでください。 ## リポジトリが決めたパッケージマネージャーとスクリプトを使う リポジトリが指定するパッケージマネージャー、ワークスペース定義、ランタイムバージョン、スクリプトを使ってください。使い慣れた代替手段がローカルにインストールされているという理由だけで置き換えてはいけません。 - 文書化されたインストールコマンドでワークスペースを準備してください。 - 全体確認にはルートのビルド、テスト、lint、型チェック用スクリプトを使ってください。 - 対象パッケージだけを扱う時は、対応しているワークスペースフィルターを使ってください。 - ラッパーが下位ツールへオプションを渡す場合は、引数の転送方法を正確に維持してください。 - パッケージマネージャーやランタイムに関する前提を変える前に、リポジトリの構成ファイルを確認してください。 - 範囲を絞ったコマンドが依存する前提条件は記録してください。 ## CIと同じ順番でテストし、古いビルド出力を混ぜない 独自のローカル手順を考案せず、継続的インテグレーションと同じ順序を再現してください。CIが依存関係をインストールし、先にビルドせず検証コマンドを実行するなら、テストも同じ順序で実行します。 - 生成物がソースファイルと一緒に検出される可能性がある場合は、先にビルドしないでください。 - 登録、スキーマ、装飾済みクラスの重複エラーは、ソースと生成済みファイルの両方が読み込まれた証拠かもしれないと判断してください。 - 依存関係、テスト、フィクスチャを除外し、文書化されたソースルート配下の生成済み出力ディレクトリだけを取り除いてください。 - 生成物に起因する失敗を解消するために、ソースディレクトリを消去してはいけません。 - 実装コードを変更する前に、クリーンアップ後の状態で失敗したテストをもう一度実行してください。 - クリーンアップしても失敗が変わらない場合は、その新しい証拠を基に通常のデバッグへ戻ってください。 ## 今のコードの書き方に合わせ、アプリの状態をグローバルに置かない 新しい抽象化を作るより、リポジトリで確立されたパターンを優先してください。コードベースがすでに採用しているモジュール方式、型付き言語の規約、フォーマッター、リンター、ファイル命名形式を使います。 - リポジトリの規約であれば、ファイル名は小文字とハイフンで構成してください。 - 公開APIの変更は意図を明確にし、テストで保護して文書化してください。 - アプリケーション固有の可変ランタイム状態は、プロセス全体のシングルトンではなく、アプリケーションが所有するスコープに保持してください。 - ライフサイクルユーティリティやアプリケーション単位のサービスには、フレームワークのスコープ付きストレージを使ってください。 - タイマー、イベントリスナー、プロキシハンドラー、モジュールレベルのエスケープポイントなど、切り離されたコールバックでは、所有元アプリケーションのスコープへ入り直してください。 - 正しいアプリケーションコンテキストにすでに固定されているアクセサーへ、重複するスコープラッパーを追加しないでください。 ## 起動時に読むモジュールが、起動スナップショットを壊さないようにする ランタイムが起動スナップショットをシリアライズできる場合、ビルド時の起動処理は通常のアプリケーション起動より前に停止する可能性があると想定してください。その段階で読み込まれるすべてのモジュールは、シリアライズ可能でなければなりません。 - import時または起動時の処理がシリアライズできないネイティブ状態を作る場合、そのモジュールは外部化してください。 - HTTPパーサー、HTTP/2バインディング、TLSコンテキスト、DNSチャネル、WebAssemblyインスタンス、ファイルウォッチャー、ネイティブアドオン、開いたソケットは、スナップショットにとって危険度の高い依存関係として扱ってください。 - 外部化したモジュールは、復元時に使うランタイムの読み込みブリッジを経由させてください。 - 遅延読み込みまたは外部化を維持すべきモジュールについて、文書化された既定リストを1つだけ管理してください。 - 生成済み出力へパッチを当てるのではなく、リポジトリが対応する構成を通してそのリストを拡張してください。 - ネイティブ状態を直接作る処理と推移的なネットワーク利用を区別してください。遅延外部化された組み込みモジュールが推移的依存関係をすでに保護している場合がある一方で、ネイティブ状態やWebAssembly状態を直接作るパッケージには、依然として明示的な対処が必要です。 - フレームワークの依存関係が起動中にネイティブスタックやネットワークスタックへ触れる可能性がある場合は、スナップショットのビルドテストを追加してください。 ## グローバル型の追加を、専用の型モジュールにまとめる パッケージ全体のグローバル拡張は、専用のグローバル型モジュールに置いてください。複数のパッケージで使う共有拡張は、単一の利用側パッケージではなく共有型パッケージに置きます。 - 宣言ファイルにはimport、型だけのimport、または空のexportを置き、モジュールとして維持してください。 - 共有拡張は、その型の公開範囲を必要とするパッケージのエントリーポイントからimportしてください。 - ファイルにモジュール構文がないという理由だけでグローバルになるアンビエント宣言は避けてください。 - 共有型を移動した後は、定義元パッケージと少なくとも1つの利用側パッケージの両方をテストしてください。 - 公開される型の範囲に変更があれば文書化してください。 ## 必要なテストを走らせ、最後の差分を見直してから報告する 変更した動作を証明できる最も範囲の狭い確認を実行し、影響する境界が必要とする場合に限って確認範囲を広げてください。 - ローダー、アプリケーションのライフサイクル、クラスタリング、エージェント、HTTP処理、プロセス動作を変更する場合は、回帰テストを追加してください。 - リポジトリのスクリプトを通して、フォーマット、lint、型チェック、関連テストを実行してください。 - リポジトリのコミットメッセージ規約を使い、スコープを変更内容と正確に一致させてください。 - 変更説明には、動機、変更後の動作、リスク、テストの証拠を書いてください。 - 最終差分を見直し、無関係な編集、生成物によるノイズ、文書化されていない公開変更がないか確認してください。 - 関連コマンドが正常に完了するまで、成功したと報告してはいけません。 ## 秘密情報をコミットせず、脆弱性の詳細を出す前に止まる 脆弱性に関わる作業を扱う前に、リポジトリのセキュリティポリシーを読んでください。秘密情報、認証情報、一般利用者に見せないエンドポイント、マシン固有の構成をコミットしないでください。 - ローカルのランタイムとパッケージマネージャーのバージョンを、リポジトリの宣言と一致させてください。 - ロックファイルとワークスペース構成を連動する入力として扱い、意図した依存関係またはツールチェーンの更新時だけ変更してください。 - サンプルとドキュメントでは、実際の認証情報や非公開URLの代わりにプレースホルダーを使ってください。 - セキュリティに関わる変更は範囲を狭く保ち、保護対象の境界へ回帰テストを追加してください。 - タスクで明示的に許可されていない限り、脆弱性の詳細を公開したり、保護された外部システムを変更したりする前に停止してください。 ## コードなどの根拠資料、Wiki、AI向けのルールを分けて持つ 3つの知識レイヤーを明確に分けて維持してください。生の情報源は権威ある証拠であり、Wikiは永続的な統合知識を保管し、ルートのエージェント向けガイダンスは共有ワークフロールールを定義します。 - コード、ユーザー向けドキュメント、ルートのプロジェクトファイル、明示された外部成果物、取り込んだ生の資料を根拠資料として扱ってください。 - 概要を把握する時はWikiの要約から始めても構いませんが、詳細、矛盾、鮮度が重要な場合は生の情報源で検証してください。 - タスクで必要とされない限り、生の情報源を書き換えないでください。 - 繰り返し利用する外部の証拠は、リポジトリの知識ベースに取り込んでください。 - 対立する情報を無理に1つの見解へならさず、矛盾として記録してください。 - ツール固有のエージェントファイルは薄く保ち、共有スキーマを参照させてください。 ## Wikiの各ページを1つの話題にし、根拠のファイルを書く 実質的な内容を持つ各知識ページには明確なトピックを1つだけ持たせ、package、concept、workflow、decision、sourceなどのページ種別を宣言してください。 - ファイル名には小文字とハイフンを使ってください。 - 人が読めるタイトル、ページ種別、1行の要約、主要な情報源のパス、ローカルの暦日、鮮度ステータスを含むフロントマターを付けてください。 - 自明でない主張には、追跡可能な情報源ファイルを示してください。 - 自明でない統合的な判断には、推論であることを明記してください。 - 鮮度が不確かな主張には、古い可能性または未解決であることを示してください。 - Wikiの索引は簡潔に保ち、カテゴリー別に整理してください。 - 大規模な情報取り込み、永続的な発見、重要な再構成、記録済みの理解を変える変更には、追記専用ログを使ってください。 - 単純な誤字修正はログへ記録しないでください。 ## 資料の取り込みや質問への答えは、Wikiの索引を読んでから始める 情報源の取り込み、リポジトリに関する質問への回答、知識ベースのlintには、予測可能なワークフローを使ってください。 - 取り込みでは、索引を読み、資料を吸収すべき既存ページを探し、必要に応じてsourceページを作成または更新し、影響するページと索引を更新し、重要な変更にはログ項目を追記してください。 - 質問への回答では、まず索引と関連Wikiページを読み、生の情報源で検証し、新しい永続的な知見を書き戻し、重要な知識変更をログへ記録してください。 - lintでは、孤立ページ、古い主張、重複概念、情報源参照の欠落、頻繁に扱う領域のページ不足、矛盾を確認してください。 - 重複するページを際限なく長くするより、構造を整理し直すことを優先してください。 - 基盤パッケージ、連携機能、ツール、ライフサイクル動作、読み込み、テスト、リリース作業、ドキュメント保守について、永続的な情報を優先して整備してください。 ## APIや作業の流れが変わった時だけ、Wikiを更新する 公開API、ドキュメント構造、パッケージの責務、アーキテクチャ、繰り返し使うコントリビューターワークフロー、テスト要件、リリース手順を実質的に変更した時は、知識ベースを更新してください。 - 永続的な理解を変えないコードだけの変更で、Wikiをむやみに更新しないでください。 - 新しいルールが広く適用されるようになった場合は、同じ変更内でコントリビューター向けガイダンスも更新してください。 - 情報源のパスと鮮度の日付を、それらが裏付ける事実と同期させてください。 - 将来の作業に役立つほど重要な知識変更だけをログへ追記してください。 - 完了を報告する前に、最終ドキュメントを実装済みの動作と照合してください。