ben-eddy74/agent-skills

Quarkus BCE バックエンドワークフロー

スコープとディレクトリ境界

• 厳格な境界: backend/ 内でのみ操作します。frontend/ のファイルには決して触れません。
• アーキテクチャ: 厳格なAdam Bien BCEパターン（com.app.<ドメイン>.{boundary, control, entity}）。
• テクノロジースタック: Quarkus、Jakarta EE（jakarta.* のみ—javax.* や org.springframework.* は絶対に使用しません）。

2フェーズ実行ゲート

フェーズ 1: 契約と骨子（人間によるレビューのために一時停止）

1. entity: ..<ドメイン>.entity 内に、不変のJava record ペイロード（@NotNull、@NotBlank、@Schema を付与）とJPA/Panacheエンティティを作成/更新します。control や boundary への依存関係はゼロです。
2. boundary: ..<ドメイン>.boundary 内に、JAX-RS @Path リソースのシグネチャ（@Transactional、@RolesAllowed、@Operation）を作成/更新します。
3. テスト: backend/src/test/java/..<ドメイン>/boundary/ 内に、失敗するJUnit @QuarkusTest または単体テストスタブを作成/更新します。
4. 一時停止: entity、boundary、テストの差分をユーザーに表示します。control の実装を書く前に承認を待ちます。

フェーズ 2: 実装とスキーマのエクスポート

1. control: ..<ドメイン>.control 内にビジネスロジックを実装します（@ApplicationScoped）。他のドメインの control を直接呼び出さず、常にその boundary を経由します。
2. 検証と契約のエクスポート: backend/ 内で以下を実行します。

   ./mvnw test
   

Java 25 LTS 言語およびJVMルール（必須）

Java 25 LTS のみを対象とします（<maven.compiler.release>25</maven.compiler.release>）。レガシーなJava 8/11/17のボイラープレートは絶対に記述しません。

1. 網羅的Switchとレコード分解（control および entity）：
   • ドメインの結果とステートマシンを、entity 内で sealed interface + record 実装を使用してモデル化します。
   • control 内では、網羅的な switch 式と、レコードパターン分解およびガード付き when 句（例：case PaidOrder(var id, var total) when total > 1000 -> ...）を使用して処理します。
   • sealed interface のスイッチには default ブランチを絶対に含めないでください。これにより、新しい状態が追加されたときにJava 25コンパイラが網羅性を強制します。
2. 柔軟なコンストラクタ本体（JEP 513）：
   • 膨大な静的ヘルパーメソッドを作成する代わりに、super(...) や this(...) を呼び出す前に、コンストラクタ内で直接フェイルファスト検証とデータ正規化を実行します。
3. 未使用変数（_）：
   • 未使用のラムダパラメータ、無視される例外変数、または未使用の分解されたレコードコンポーネントには常に _ を使用します（例：case Order(var id, _, _)）。
4. 仮想スレッドとスコープ値（JEP 506）：
   • Quarkus boundary 内のブロッキングI/Oエンドポイントでは、ストリーミングが必要でない限り、リアクティブな Uni<T> チェーンよりも @RunOnVirtualThread を優先します。
   • ThreadLocal は決して使用せず、スレッドスコープ内でコンテキスト状態を渡す必要がある場合は、常にJava 25の ScopedValue<T> を使用します。
5. モダンなコレクションとストリームギャザラー（JEP 485）：
   • インデックス計算 list.get(list.size() - 1) の代わりに SequencedCollection のメソッド（.getFirst()、.getLast()、.reversed()）を使用します。
   • 手動チャンキングループの代わりに Stream.gather(Gatherers.windowFixed(...)) を使用します。
6. プレビューフラグは要求がない限り使用しない：
   • 確定したJava 25 LTS機能に限定します（明示的に要求されない限り、JEP 507のプリミティブパターンやJEP 505の構造化並行性のために --enable-preview を有効にしないでください）。