principles

原則

以下の各原則では、適用される状況と定めるルールを示します。適用する前に、原則のファイル全体を読んでください。ここにある項目は参照先であり、原則そのものはファイルに記載されています。

コア

• Laziness Protocol. リファクタリング、差分の規模の見積もり、または抽象化やレイヤー、シグナルの受け渡しを追加したくなったときに適用します。削除を優先し、問題を解決する最小の変更にとどめます。
• Foundational Thinking. ロジックを書く前に、主要な型とデータ構造、足場と機能の実装順序、並行するアクターが共有するものを検討します。
• Redesign from First Principles. 新しい要件を既存の設計に統合するときに適用します。最初からその要件が基盤にあったかのように再設計します。
• Attack the Premise. 2つ以上の修正が同じ前提を共有している場合、同じ関門で失敗しています。次の修正を行う前に、どのアクターが不均衡を抱えているかを調べ、前提を置いた別の修正を書くのではなく、その前提自体を問い直します。
• Subtract Before You Add. 追加、リファクタリング、書き直しを行う順序を決めるときに適用します。まず不要なものを取り除き、よりシンプルな土台の上に構築します。
• Minimize Reader Load. 追跡が難しいコードをレビューまたは整えるときに適用します。レイヤーと隠れた状態を数え、呼び出し元が1つだけのラッパーを統合し、可変スコープを縮小します。
• Outcome-Oriented Execution. フェーズの境界が明確な、計画的な書き換えや移行に適用します。目標のアーキテクチャに収束させ、使い捨ての互換状態を維持しません。
• Experience First. プロダクト、UX、機能範囲のトレードオフに適用します。実装の都合より、ユーザーの喜びを優先します。
• Exhaust the Design Space. 前例のない新しい操作方法やアーキテクチャ上の判断に適用します。決定する前に、競合するプロトタイプを2～3個作り、比較します。
• Build the Lever. あらゆる重要な作業に適用します。手作業ではなく、作業を実行または検証するツール（codemod、スクリプト、ジェネレーター）を作ります。そのツールが、レビュー担当者が再実行する成果物になります。

アーキテクチャ

• Model the Domain. 状態を持つロジックを書くとき、分岐が多いコードを書くとき、または複数のファイルにわたって同じ形状の前提が繰り返されるときに適用します。条件分岐を散在させるのではなく、構造（ステートマシン、型付きモデル、テーブルまたはレジストリ、リデューサー、境界、適切なコレクション）でドメインを表現します。
• Boundary Discipline. バリデーション、エラー処理、フレームワークアダプターを組み込むときに適用します。システム境界でガードし、内部の型を信頼し、ビジネスロジックを純粋に保ちます。
• Type System Discipline. TypeScriptで型やシグネチャを設計するとき、またはLuaでLuaLSアノテーションを使うときに適用します。不正な状態を表現できないようにし、プリミティブ型にブランドを付け、境界で外部データをパースします。
• Make Operations Idempotent. クラッシュ、再試行、リソースの再起動が起きる状況で実行されるコマンド、ライフサイクルの各段階、ループを設計するときに適用します。同じ最終状態に収束させます。
• Migrate Callers Then Delete Legacy APIs. 古い呼び出し元が残っている状態で、新しい内部APIを導入するときに適用します。呼び出し元の移行と削除を一度に行います。
• Separate Before Serializing Shared State. 並行するアクターが同じファイル、ブランチ、キー、状態バッグ、行に書き込む可能性があるときに適用します。まず共有をなくします。

検証

• 動作を証明する。 タスクの完了後、完了を宣言する前に行います。プロキシや「コンパイルできること」ではなく、実際の成果物で検証します。
• 根本原因を修正する。 デバッグ時に行います。それぞれの症状を根本原因までたどり、まず再現し、根本原因にたどり着くまで「なぜ」を問い続けます。
• 作業を検証可能な単位に分割する。 複数ステップの作業（全体の一括確認、移行、類似編集の繰り返し）と、コミットや PR の積み上げ方に適用します。作業を小さな単位に分け、それぞれの最後にチェックを行い、次に進む前に検証します。また、手順そのものが成果を証明できるように、作業の提供順序を組み立てます。
• 実装ではなく振る舞いをテストする。 テストを作成、変更、維持するときに行います。利用者と同じ方法でコードを呼び出し、結果を明示的な期待値と照合します。インポートしたすべての関数が undefined を返してもテストが通るなら、アサーションを書き直すか、テストを削除します。

委任

• コンテキストウィンドウを守る。 大量の出力、長いファイル、繰り返しの読み込み、作業を分担する計画などでコンテキストが埋まっていきます。大量の作業はサブエージェントに任せ、要約はメインスレッドに残します。
• 人間の返答を待って作業を止めない。 元に戻せる作業で「X をしてもよいですか？」と尋ねたくなったら、作業を進めて結果を提示し、人間が必要に応じて軌道修正できるようにします。

メタ

• 教訓を仕組みに組み込む。 同じ指示を二度書こうとしていることに気づいたら、文章を増やすのではなく、リンター、メタデータフラグ、ランタイムチェック、またはスクリプトとして組み込みます。