アプリとコマンドラインで使う製品の、コード置き場（リポジトリ）を整理して保つ

## 全体の決まりを先に読み、フォルダごとの決まりにも従う 横断的な境界、作業手順、コマンドについては、ルートのガイドファイルをリポジトリ全体の正本として扱う。 モジュール固有の詳細を重複させず、新しい貢献者が全体像を把握できる簡潔さを保つ。 - 製品、アーキテクチャ、貢献方法、レビュー、現行計画の各文書へ導く短い索引を公開する。 - 保管済みの旧仕様を明示し、古い判断を現行の挙動として決して扱わない。 - 各主要ディレクトリから、その領域の所有権と制約を定める専用ガイドへ案内する。 - 規則で管理されたディレクトリ内で作業する前に、ルート規則に加えてその領域のガイドも読む。 - 2つの文書が食い違う場合は、指定された正本に従い、内容を混ぜずに不一致を報告する。 モジュール単位の規則をルート文書へコピーしてはならない。 規則は、その内容を完全に所有できる最も狭い階層で更新し、見つけやすさのために必要な場合だけ上位文書からリンクする。 ## 変更の前に、新しいコードやテストの置き場を決める 各最上位領域の所有物と、その境界を越えられる依存関係を説明するリポジトリマップを維持する。 新しいコード、テスト、テンプレート、文書、実行時データの配置先は、このマップを基準に決める。 - ユーザー向けアプリケーション、共有契約、基盤プリミティブ、オーケストレーションツール、エンドツーエンドテスト、コンテンツ拡張を分離する。 - アプリケーションの業務ロジックから、プロセス制御やパッケージングの内部事情を切り離す。 - あるアプリケーションから別のアプリケーションの非公開ソースやテストを取り込ませない。 - 実行環境をまたぐDTO、イベント、エラー、タスク形式は、純粋な共有契約層へ昇格させる。 - テストは対象レイヤーが所有するディレクトリに置き、アプリケーション横断の整合性テストはエンドツーエンド層に置く。 - 廃止済みまたは非稼働のディレクトリを記録し、古いアーキテクチャが誤って再作成されるのを防ぐ。 再利用可能な関心事の所有者が明確でなければ停止し、別の共有場所を作る前に所有権の判断を得る。 ## データの保存場所を一か所で決め、ほかの部分へそのまま渡す 各実行時ルート、名前空間、識別情報は所有境界で一度だけ解決し、その確定値を下流へ渡す。 各コンポーネントはその値を使い、ポート、作業ディレクトリ、アプリケーション名、環境の代替値から再構築してはならない。 - 実行環境が所有するすべてのデータパスを、確定済みデータルートまたはそこから派生した定数から導く。 - 限定的な上書き値と移行元は、別のルートではなく明示的な例外として扱う。 - 一時的な通信情報と永続的な実行環境の識別情報を分離する。 - 子プロセスを開始する前に、パッケージ版と開発版の状態へ名前空間を割り当てる。 - 確定済み状態を子プロセスへ渡し、子側に保存場所を推測させない。 - 既知の旧式な迂回経路は廃止候補として文書化し、例として決して再利用しない。 明白な修正方法がある場合は、正規ルートまたは明示的な引数を経由させる。 正しい所有者が不明な場合は、新しい慣例を作らず、保守責任者へ判断を求める。 ## 新しい機能を、アプリとコマンドラインの両方に入れる ユーザー向け機能は1つのサービス契約を中心に設計し、対応するすべての操作面から利用可能にする。 インターフェース間の同等性は機能完成の一部であり、後から追加する拡張ではない。 新しい機能ごとに、次を行う。 1. 共有する要求、応答、エラー、イベントの契約を定義または更新する。 2. 単一の挙動正本としてサービスのエンドポイントを実装する。 3. そのエンドポイントを呼ぶグラフィカルインターフェースを追加する。 4. 同じエンドポイントを呼ぶコマンドラインインターフェースを追加する。 5. 必要に応じて、機械処理可能なコマンド結果と長いプロンプト向けのファイル入力を提供する。 6. 変更チェックリストを更新し、影響を受けるすべての提供面を明記する。 クライアントごとに異なる挙動を実装してはならない。 ある提供面が本当に該当しない場合は、黙って省かず、変更記録で理由を説明する。 ## 画面の部品を、使い回せて誰でも使いやすい形で作る 意図的なグローバル契約を維持しながら、視覚表現の所有権を最小の安定したコンポーネントへ割り当てる。 新しい局所的な派生版を作る前に、共有プリミティブを再利用する。 - グローバルスタイルシートを、意図的な読み込み境界およびデザイン変数の境界として保つ。 - コンポーネント所有のスタイルはその近くに置き、既定でスコープ付きモジュールを使う。 - グローバルセレクターは、リセット、デザイン変数、アプリケーションシェル、共有コンテンツ契約、外部連携点に限定する。 - スタイルシート分割時のカスケード順を維持し、詳細度が意図せず変わっていないことを確認する。 - ボタン、非表示ラベル、共通フォーム動作には、意味に即したコントロールと共有のアクセシブルなプリミティブを使う。 - 本当に再利用可能な場合だけ共有プリミティブを追加し、製品固有のレイアウトは製品レイヤーに置く。 - 終了アニメーションが重要な条件付き要素は配置したままにし、クラスで状態を切り替える。 - 素早いイーズアウト、開始より短い終了時間、0ではない開始スケールを優先する。 近接するグローバルスタイルを小さく検証可能な変更で安全に移行できる場合は、コンポーネントと一緒に移す。 広範な機械的移行と無関係な挙動変更を組み合わせてはならない。 ## 問題を見つけられる、いちばん軽いテストで変更を確かめる 要件を観測できる最も軽い検証層を選び、リスクが境界を越える場合だけ広い確認を追加する。 検証範囲は、変更の所有範囲とユーザーへの影響に合わせる。 - 不具合では、反証可能な回帰テストから始め、修正前に失敗することを確認する。 - テストを報告された挙動に限定し、周辺の不具合は別の後続作業として記録する。 - リポジトリのガードと静的検査に加え、変更したパッケージに絞ったテストまたはビルドを実行する。 - パーサーやエージェントストリームの変更では、外部AIを実際に呼ぶ前に記録済みセッションを再生する。 - 単体テストで証明できない表示上の操作、アニメーション、競合挙動にはブラウザ層の確認を使う。 - ワークスペースや依存関係の変更では、リポジトリが要求する生成済みリンクとパッケージハッシュを更新する。 - 周辺スイートに既知の失敗がある場合は、基準状態と比較する。 実装には、過去の例外ではなく、持続する不変条件を表現させる。 受け入れ条件が人の目による比較を必要とする場合、自動検査が通ったことだけで準備完了を主張してはならない。 ## 試し版と正式版を分け、出す前に配る版を確かめる 各配布チャネルについて、リリース識別情報、パッケージング動作、レビュー証拠を明確にする。 便利な近道でチャネルの分離を崩したり、信頼された検証を迂回したりしてはならない。 - 開発、内部検証、プレビュー、安定版の各チャネルに、異なる目的と一般向け識別情報を与える。 - 昇格時の依存関係を明示し、安定版チャネルを無関係なプレビュー工程に依存させない。 - パッケージ版の実行時パスへ名前空間を割り当て、一時ポートから独立させる。 - 呼び出し側でプロセス引数や走査規則を組み直さず、所有されたパッケージプリミティブを通じて処理を統括する。 - 変更説明には、動機となる用途、ユーザーが認識する効果、影響する提供面、検証証拠を必須とする。 - 表示上の変更には、孤立したコンポーネント画像だけでなく、利用開始点のスクリーンショットを添付する。 - 不具合修正を回帰テストと課題記録へ関連付ける。 - 正確性、安全性、データ整合性、契約互換性を妨げない限り、無関係な発見を今回の変更へ混ぜない。 リリース前に、ユーザーが実行するものと同じ経路で成果物を検証する。 リポジトリ境界への違反、必須検証の欠落、秘密情報の露出、永続データ破損の危険がある変更を承認してはならない。