coding-standards

TypeScript と Effect のコーディング標準

構築時点で正しさを担保します。データを意味のある型にパースし、想定される失敗を明示し、エフェクトを一貫性のあるサービスの内側に保ち、実際のインターフェースを通じてテストします。

判断の優先順位

ルールが異なる方向を示す場合は、次の優先順位に従います。

1. 正しさ、安全性、デバッグのしやすさを維持します。
2. 新しいコードと、変更対象の動作全体にこれらの標準を適用します。
3. 互換性のあるリポジトリのアーキテクチャと慣習に従います。
4. 互換性のない古いパターンは、既存の最も近い境界で封じ込めます。
5. より広範な移行が依頼されていない限り、無関係な動作は変更しません。
6. 重要なトレードオフは、該当コードの近く、またはリポジトリ既存の意思決定ドキュメントに記録します。

基本原則

• 想定される失敗は値として扱い、欠陥は例外をスローするかパニックを起こすことがあります。
• 確立済みの型の根拠を維持し、外部表現をパースして、新たな不変条件はその所有者のもとで確立します。
• 実用上可能な場合は、不正な状態を表現できないようにします。
• 重要なサービスは、明示的なインターフェースから開始します。
• 合成、関数型コア、命令型シェルを優先します。
• 削除テストを使って、呼び出し元の負担が少ない一貫性のあるモジュールを保ちます。
• モジュールのモックではなく、実際の、または忠実な実装を使い、実際のインターフェースを通じて動作をテストします。

1. ローカルルールを確認する

最も近い AGENTS.md、パッケージ設定、アーキテクチャドキュメント、および変更対象の領域におけるエラー、スキーマ、サービス、テスト、可観測性、ファイルに関する慣習を確認します。

ローカルの慣習とこれらの標準が矛盾する場合は、上記の判断の優先順位に従います。リポジトリのポリシーでこれらのガードレールをさらに厳しくすることはできますが、既存の公開互換性も設計上の制約となります。例や提案を導入済みのルールと見なすのではなく、実際に適用されているルールを確認するために、有効なリント設定とプラグインのエントリーポイントを読みます。

完了条件： 適用されるファイルとランタイム／ライブラリのバージョンを特定し、変更対象の動作に関わる、互換性のあるローカルパターンと互換性のないローカルパターンをすべて把握していること。

2. 動作を追跡し、該当するリファレンスを読み込む

呼び出し元から見える各操作について、入力からあらゆる判断と作用を経て、観測可能な結果に至るまで追跡します。変更する懸念事項を、ドメインの動作、アプリケーションポリシー、テクノロジー／フレームワークの仕組み、または構成／リソースの配線に分類します。

変更を設計する前に、該当するリファレンスをすべて最後まで読みます。

• references/effect.md — Effect コードを変更する場合。編集する前に、その分岐先のリファレンスも確認してください。
• references/effect-alchemy.md — Alchemy Worker、Durable Object、Workflow、バインディングを利用するサービス、または二段階のランタイム構成を変更する場合。
• references/errors.md — 動作が失敗する可能性がある場合、または不在が通常の状態である可能性がある場合。
• references/sensitive-data-and-observability.md — 動作がシークレット、個人データ、ログ、トレース、メトリクス、エラー報告を扱う場合。
• references/parsing-and-schemas.md — データが外部／シリアライズ境界を越える場合、パースや検証を追加／削除する場合、またはスキーマ／表現を変更する場合。
• references/domain-types-and-state.md — ID、単位、制約付きの値、省略可能な入力、エンティティ、ライフサイクル状態、操作オプションを変更する場合。
• references/modules-services-and-adapters.md — 責務の割り当て、ヘルパーの切り出し、複雑さの軽減、または依存関係、モジュール／サービスの設計、作用の順序を変更する場合。
• references/persistence.md — 動作がデータベース、キャッシュ、Durable Object、ORM モデル、トランザクション、永続化されたレコードを読み書きする場合。
• references/workflows-transactions-and-idempotency.md — 処理が境界をまたぐ、再試行／再開される、再配信を受け取る、遅延する、補償処理を行う、または複数回実行される可能性がある場合。
• references/configuration-and-resources.md — 動作が設定を読み取る、リソースを作成／クローズする、起動時の処理を行う、時刻／乱数を使用する、またはグローバル状態に触れる場合。
• references/testing.md — 動作、公開される型推論、テスト、またはテストの実装を変更する場合。
• references/typescript-safety.md — 型、シグネチャ、ミュータブルな値、型アサーション、非 null の前提、またはコンパイラー設定を変更する場合。
• references/lint-and-policy.md — lint 設定の変更、ルールの記述、またはパーサー／複雑さ／未使用エクスポートを防ぐツールの評価を行う場合。
• references/imports-exports-and-files.md — インポート、エクスポート、エントリーポイント、ヘルパーの配置、またはファイル構成を変更する場合。
• references/comments-and-jsdoc.md — エクスポートされたシンボル、コメント、JSDoc、ユーザー向けテキスト、または表示されるエラーを変更する場合。

完了条件： 変更される入力、出力、失敗、依存関係、作用、状態遷移、外部表現、テスト対象のすべてについて、担当モジュールと該当するリファレンスが特定されていること。

3. 公開型から内側に向かって設計する

実装を始める前に、呼び出し元向けの入力、出力、想定されるエラー、サービスインターフェースを定義または確認します。解析リファレンスを使って入力の出所と残る不変条件をたどり、内側のコードまで正確な型を維持します。ドメイン計算は純粋に保ちます。アプリケーションのポリシーと副作用の順序は、それを所有するサービスに置きます。フレームワークやプロバイダーの型は、それを所有する側の内部に留めます。

追加する前に、既存のモジュール、サービス、クライアント、アダプター、スキーマ、エラー、ヘルパーを確認します。削除テストを適用します。抽象化を削除したときに、意味のある複雑さが呼び出し元に広がる場合、その抽象化には存在する価値があります。新しい抽象化ごとに、検討した既存の所有者または直接実装と、それが適さない理由を記録します。

完了条件： 呼び出し元向けの入力、出力、想定されるエラー、サービスインターフェースが明示されていること。変更した依存関係と副作用のそれぞれに所有者が一つあること。各新しい抽象化について、最終報告向けの削除テストの根拠があること。フレームワークやプロバイダーの型が、それを所有する側の内部に留まっていること。

4. 変更された動作をすべて実装する

想定される失敗、外部データの変換、診断、リソースの動作を含め、呼び出し元から見える操作に必要なすべての経路を実装します。無関係な既存の動作は変更しません。既存の互換性のあるテレメトリーとエラー報告のフックを維持します。

完了条件： たどったすべての経路が、それを所有するインターフェースを通じて実装されていること。想定される失敗で明示的なエラー値が使われていること。外部データが解析済みの型として内側のコードに渡されること。公開アプリケーション／ドメインのコントラクトが、アプリケーション／ドメインの型を公開していること。

5. 公開インターフェースを通じて検証する

references/testing.md で求められているテストを追加または更新します。リポジトリで必須の検証コマンドを実行します。個別の型チェック、テスト、ビルド、または lint コマンドは、必須コマンドでカバーされていない場合にのみ追加で実行します。クリーンアップでは、削除したランタイム処理と API／型のみの変更を区別します。デコーダーや分岐の数が減ったことを根拠とせず、公開動作、失敗／復旧のセマンティクス、型推論を比較します。該当するリファレンスをそれぞれ読み直し、変更したシンボルを一つずつ照合します。例外は修正するか、具体的な根拠とともに報告します。

完了条件： 必須のチェックがすべて成功しているか、具体的な根拠とともに失敗が報告されていること。該当するリファレンスの各ルールが確認されていること。呼び出し元から見えるすべての機能に、必要なテストがあること。追加または変更したすべてのエクスポートが意図的なものであり、references/comments-and-jsdoc.md で求められるドキュメントが記載されていること。変更された動作における各抽象化、ヘルパー、キャストが必要であり、該当するリファレンスに準拠していること。すべての変更が依頼された範囲内に収まっていること。