codebase-design

コードベースの設計

ユーザーが希望するスタイルでコードを設計・実装します。この実行では、../coding-standards/ を基準となる標準パッケージとして扱います。

手順

1. コア設計標準を読み込みます。

   • 必ず ../coding-standards/PRINCIPLES.md、../coding-standards/VOCABULARY.md、../coding-standards/MODULES.md を読みます。
   • 完了基準：構造を提案する前に、設計の優先事項、アーキテクチャ用語、モジュールの慣用パターン、シームのルールを把握していること。

2. 設計前にローカルの慣習を調査します。

   • モジュール構成、エラー処理、スキーマ解析、依存性注入、アダプター、可観測性、テスト、ツールチェーン、プラットフォーム境界に関する既存の選択を調べます。
   • 適合する場合は、既存のドメイン概念、パーサー、アダプター、サービス、prelude ヘルパーを再利用します。
   • 完了基準：新しいパターン、ライブラリ、アダプター、抽象化がすべて、ローカルの先例と照合されていること。

3. 関連するトピック標準を読み込み、ドメイン用語で問題を捉えます。

   • タスクが該当する場合は、../coding-standards/TYPESCRIPT.md、../coding-standards/CLOUDFLARE.md、または ../coding-standards/EFFECT.md を読みます。
   • ドメイン概念、不変条件、ライフサイクルの状態、信頼境界、想定される失敗、ランタイムのホップ、永続化の境界、キャンセル／リトライの経路、検証要件を特定します。
   • ユーザーの用語を優先します：Expected Failure、Adapter、Interface、Seam、Depth、Deep Module、Leverage、Locality、State Machine、Functional Core、Imperative Shell、Real Seam Test など。
   • 完了基準：設計上の問題がドメインの振る舞いとシームに基づいて定義されており、設計の各要素を選ぶ前に、関連するトピックファイルが読み込まれていること。

4. 最もシンプルで深い設計を選びます。

   • 実用上可能な限り、不正な状態を表現できないようにします。
   • 早い段階で解析し、正確な値を内部に渡します。
   • Functional Core の振る舞いをエントリーポイントに依存しないものにします。
   • I/O、フレームワークとの変換、テレメトリー、時間／乱数、依存関係の構築は、Imperative Shell または合成シームに置きます。
   • 深くまとまりのあるモジュール、狭い依存インターフェース、Effect 以外ではコンストラクター注入を優先します。Effect のコードベースでは Effect のサービス／レイヤーを使います。
   • 先回りしすぎたシーム、浅いラッパー、依存関係の詰め合わせ、テーブルごとのリポジトリを作る習慣、その場しのぎの移行は避けます。
   • 重要なインターフェースでは、実質的に異なるインターフェースの形を 2～3 種類検討してから選びます。設計の選択肢が広く、独立した試行が有益な場合は、並列エージェントを使います。
   • 完了基準：提案する各モジュール／インターフェースが、呼び出し側の負担を軽減する、不変条件を保つ、レバレッジ／局所性を高める、または実際のシームを変換することで、そのシームを設ける価値を示していること。

5. 失敗、非同期処理、検証を実装と併せて設計します。

   • 想定される失敗は型付きの値で表し、復旧不能な欠陥はスローしてもかまいません。
   • 到達可能なキャンセルとリトライは、第一級の要素として扱います。
   • 変更を伴うリトライ可能な処理には、冪等性または原子性の戦略を用意します。
   • 検証には、実際のシームを介して観測できる振る舞いを使います。一般的な不変条件の確認には、必要に応じてプロパティテストを使います。
   • 完了基準：計画で、意味のある失敗経路、並行処理／リトライのリスク、信頼性を裏付けるために必要な証拠が考慮されていること。

6. コード作成を依頼された場合は、ローカルの慣習に沿って必要な範囲で実装します。

   • 設計を満たす最小限の変更を行います。
   • 正確性、安全性、デバッグのしやすさ、またはユーザーからの明示的な依頼と矛盾しない限り、確立されたプロジェクトのスタイルに従います。
   • 関連するチェック／テストを実行するか、その実行を推奨します。
   • 完了基準：実装、テスト、引き継ぎがローカルの慣習を保ちながら、変更した箇所をこれらの標準に近づけていること。

出力形式

設計のみの作業では、十分な規模があり、この形式が役立つ場合は次の形式で返します。小規模な作業では、関連する箇条書きだけに絞ります。

• ドメインモデルと不変条件
• 提案するモジュール／境界
• 境界・障害・非同期処理の戦略
• 検証計画
• トレードオフと却下した代替案

実装作業では、次の内容を返します。

• 変更点の簡潔な概要
• 規格に関わる判断
• 実行した、または実行していないテスト／チェック
• フォローアップが必要なリスク（該当する場合）