scan-effect-solutions

Effect Solutions 準拠性監査

effect.solutions の Effect TypeScript ベストプラクティスに照らしてリポジトリを監査します。このスキルに従い、一貫性があり、根拠に基づく準拠性レポートを作成します。

前提条件

最新の effect.solutions の推奨事項を読み込みます。

effect-solutions list

このチェックリストで使用するガイダンスを読み込みます。

effect-solutions show tsconfig
effect-solutions show services-and-layers
effect-solutions show data-modeling
effect-solutions show error-handling
effect-solutions show config
effect-solutions show testing

Effect 固有の実装パターンについては、effect-ts スキルを読み込みます。

skill({ name: "effect-ts" })

---

監査チェックリスト

1. TypeScript の設定

tsconfig.base.json（または tsconfig.json）を調べ、次の項目を確認します。

• exactOptionalPropertyTypes: true
• strict: true
• noUnusedLocals: true
• declarationMap: true
• sourceMap: true
• Effect Language Service プラグインが設定されていることを確認します。
• module の設定がプロジェクトの種類に合っていることを確認します（アプリでは preserve/bundler、ライブラリでは NodeNext）。

参照：effect-solutions show tsconfig

2. サービスとレイヤーのパターン

Effect サービスを検索し、次の項目を確認します。

• サービスが Context.Tag を使って定義されていることを確認します。
• タグ識別子が @path/ServiceName のパターンに従っていることを確認します。
• レイヤーが Layer.effect または Layer.sync を使っていることを確認します。
• エントリーポイントで Effect.provide が一度だけ適用されていることを確認します。

参照：effect-solutions show services-and-layers

3. データモデリング

データモデリングを調べ、次の項目を確認します。

• レコードに Schema.Class が使われていることを確認します。
• バリアントに Schema.TaggedClass が使われていることを確認します。
• プリミティブ値（ID、メールアドレスなど）にブランド型が使われていることを確認します。
• パターンマッチングで Match.valueTags が使われていることを確認します。

参照：effect-solutions show data-modeling

4. エラー処理

エラー処理を調べ、次の項目を確認します。

• ドメインエラーに Schema.TaggedError が使われていることを確認します。
• 適切な箇所でエラーの回復に catchTag／catchTags が使われていることを確認します。
• 欠陥と型付きエラーが意図的に分けられていることを確認します。

参照：effect-solutions show error-handling

5. 設定

設定パターンを調べ、次の項目を確認します。

• 検証に Schema.Config が使われていることを確認します。
• 設定サービスのレイヤーパターンが存在することを確認します。
• シークレットに Config.redacted が使われていることを確認します。

参照：effect-solutions show config

6. テスト

テストを調べ、次の項目を確認します。

• テストで @effect/vitest が使われていることを確認します。
• Effect のテストで it.effect() が使われていることを確認します。
• テストレイヤーの合成が Effect のレイヤーパターンに従っていることを確認します。

参照：effect-solutions show testing

7. ランタイム実行のアンチパターン（アプリケーションコード内の Effect.runPromise／Effect.runSync）

アプリケーションコード内で Effect.runPromise と Effect.runSync が直接使われている箇所を検索します。テスト専用ファイルとテストヘルパー（__tests__/、*.test.ts、*.spec.ts、フィクスチャディレクトリ）は除外します。

プロジェクトのランタイム構成を介さない、単独の Effect.runPromise／Effect.runSync は指摘事項として扱います。単独での実行では通常、プロジェクトが提供するレイヤー（トレーシング、設定、ロギング、ドメインサービスなど）が適用されないデフォルトのランタイムが使われます。

プロジェクトに即して評価します。

• アプリケーションコードでは、プロジェクトのランタイムエントリーポイント（例：runtime.runPromise）を優先します。
• ランタイムの使用が現実的でない場合（例：ブートストラップ時や依存関係の循環が制約となる場合）は、明示的なレイヤーの提供を許容します。
• 専用のテストレイヤーを意図的に提供するテストは対象外とします。

Template-ts の規約例（監査対象リポジトリに該当する場合のみ使用します）。

• effect-runtime.ts 内の ManagedRuntime
• AppLayer の合成
• ランタイムから提供されるオブザーバビリティにおける SentryTracingLive

検索パターン：

• アプリケーションのソースディレクトリ（例：src/、apps/*/src/、packages/*/src/）内の Effect.runPromise(
• アプリケーションのソースディレクトリ（同じ範囲）内の Effect.runSync(

見つかった箇所ごとに、次の内容を報告します。

• ファイルパスと行番号
• runtime.runPromise を使用しているか（✅）、単独の Effect.runPromise を使用しているか（❌）
• 必要なオブザーバビリティ／設定レイヤーがランタイムから提供されているか、または Effect.provide によるフォールバックがあるか

参照：effect-solutions show services-and-layers

8. Option/Either の内部タグに関するアンチパターン

アプリケーションコードとテストで、Option／Either を直接 _tag で分岐している箇所を調べます。

• 本番コード：直接的な _tag の使用をすべて指摘し、置き換え方法を推奨します
• テスト：ドメインエラーの識別に関する _tag のアサーションは許容しますが、ヘルパーを使うべき制御フローの分岐パターンは指摘します
• 次を優先します：
  • Either.match、Either.isLeft、Either.isRight
  • Option.match、Option.isSome、Option.isNone、Option.getOrElse

検索対象に含めるパターン：

• if (.*\._tag === "Left")
• if (.*\._tag === "Right")
• if (.*\._tag === "Some")
• if (.*\._tag === "None")
• expect\(.*\._tag\)

参考：effect-solutions show error-handling

---

出力形式

次の項目を含む、構造化されたレポートを作成してください。

1. 概要：以下の評価基準に基づく全体の準拠スコア。

   評価基準（合計0〜16点）：

   • 各チェックリスト項目（1〜8）を0〜2点で評価します。
   • 2：完全に準拠、または軽微な見た目上の不足のみ。
   • 1：部分的に準拠しているものの、意味のある不足があります。
   • 0：準拠していない、またはパターンがありません。
   • 合計スコア＝各項目のスコアの合計。
   • パーセンテージ＝(合計 / 16) * 100 を整数に丸めます。

2. 適切な点：ベストプラクティスに従っているパターンを列挙します

3. 改善が必要な点：次の情報を含む具体的な問題を列挙します。

   • ファイルの場所
   • 現在のパターン
   • 推奨するパターン
   • 優先度（高／中／低）
   • スコープラベル：production または test

4. すぐにできる改善：直ちに実施できる簡単な修正

5. 次のステップ：改善の推奨順序

---

関連スキル

• effect-ts — Effect のサービス、レイヤー、エラー処理、設定パターン
• testing-patterns — Vitest と @effect/vitest のテストパターン
• code-review — 一般的なコードレビューの方法論（Effect のセクションを含む）