arch-cross-service-integration

Codex 互換性に関する注意：

• Codex では $skill-name を使ってリポジトリのスキルを呼び出してください。このミラー版では、従来の Claude の /skill-name 参照を書き換えています。
• タスクトラッカーの必須事項：ワークフローまたはスキルの手順を実行する前に、すべての手順についてタスクの追跡を作成または更新し、進捗に応じて同期してください。
• ユーザーへの質問を促すプロンプトでは、Codex でユーザーに直接質問してください。
• Claude 固有のモード切り替え指示が現れた場合は無視してください。
• 厳格な実行規約：ユーザーがスキルを明示的に呼び出した場合は、そのスキルのプロトコルに記載されたとおりに実行してください。
• サブエージェントの認可：スキルがユーザーによって呼び出された場合、または AI によって検出された場合、そのプロトコルでサブエージェントが必要とされていれば、そのスキルの有効化によって、そのタスクに必要な spawn_agent サブエージェントの使用が許可されます。
• ユーザーが事前に逸脱を明示的に承認しない限り、プロトコルの手順を省略、並べ替え、統合しないでください。
• ワークフロー系スキルでは、記載された各子スキルの手順を明示的に実行し、手順ごとの根拠を報告してください。
• 必須の手順またはツールをこの環境で実行できない場合は、適応方法を変更する前に停止してユーザーに確認してください。

Codex でのプロジェクト参照資料の読み込み（フックなし）

Codex には、Claude のフックによるドキュメントの自動挿入機能がありません。 コーディング、計画、デバッグ、テスト、レビューの際は、このルーティングに従ってプロジェクトのドキュメントを明示的に開いてください。

必ず読むもの：

• docs/project-config.json（プロジェクト固有のパス、コマンド、モジュール、ワークフロー／テスト設定）
• docs/project-reference/docs-index-reference.md（docs/project-reference/* カタログ全体へのルート）
• docs/project-reference/lessons.md（常に適用するガードレールとアンチパターン）

状況に応じて読むもの：

• バックエンド／CQRS／API／ドメイン／エンティティの変更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
• フロントエンド／UI／スタイリング／デザインシステム：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 仕様／テストケースの計画、または TC マッピング：feature-docs-reference.md
• 統合テストの実装／レビュー：integration-test-reference.md
• E2E テストの実装／レビュー：e2e-test-reference.md
• コードレビュー／監査：変更されたファイルに応じた上記のドメインドキュメントと code-review-rules.md

すべてのドキュメントをむやみに読まないでください。docs-index-reference.md から始め、タスクに関連するファイルだけを開いてください。

クイックサマリー

目標： サービス間通信、データ同期、サービス境界のパターンを設計・実装します。

ワークフロー：

1. 事前確認 — ソース／ターゲットのサービス、データの所有者、同期か非同期かを特定します
2. パターンの選択 — エンティティイベントバス（推奨）、直接 API、共有 DB は使用しない
3. 実装 — 依存関係の待機と競合状態への対処を含め、プロデューサーとコンシューマーを実装します
4. テスト — 作成／更新／削除のフロー、順不同メッセージ、強制同期を検証します

主なルール：

• 別のサービスのデータはメッセージバスまたはその API 経由で読み取り、データベースに直接アクセスしないでください。理由：DB への直接アクセスはサービス間の結合を強め、データの所有権を損ないます
• 競合解決には LastMessageSyncDate を使用します（より新しい場合にのみ更新）
• コンシューマーは TryWaitUntilAsync を使って依存関係を待機する必要があります
• メッセージは共有プロジェクトで定義します（共有メッセージ定義、バスメッセージクラスを検索してください）

懐疑的に考えてください。批判的思考と逐次的思考を適用してください。すべての主張には、追跡可能な根拠と確信度をパーセンテージで示してください（アイデアは 80％を超える必要があります）。

必須・重要・要注意 次のプロジェクト固有の参照ドキュメントを読むための ToDo タスクを計画してください。

• backend-patterns-reference.md — バックエンドの CQRS、エンティティイベントバス、メッセージバスのパターン

ファイルが見つからない場合は、サービス間メッセージの定義、エンティティイベントのプロデューサー、メッセージバスのコンシューマーを検索してください。

サービス間連携ワークフロー

このスキルを使用する場面

• サービス間通信の設計
• データ同期の実装
• サービス境界の分析
• サービス間の問題のトラブルシューティング

事前チェックリスト

• ソースサービスとターゲットサービスを特定する
• データの所有権を確認する
• 通信パターン（同期または非同期）を選択する
• データ変換の要件を整理する

サービス境界

注記： project-structure-reference.md またはプロジェクトのサービスディレクトリを検索し、プラットフォームのサービスマップ、データ所有権マトリックス、共有インフラストラクチャコンポーネントを確認してください。

通信パターン

パターン 1：エンティティイベントバス（推奨）

次の場合に使用します：ソースサービスがデータを所有し、ターゲットサービスにコピーが必要な場合。

Source Service                    Target Service
┌────────────┐                   ┌────────────┐
│  Employee  │──── Create ────▶ │ Repository │
│ Repository │                   └────────────┘
└────────────┘                          │
      │                                 │
      │ Auto-raise                      │
      ▼                                 ▼
┌────────────┐                   ┌────────────┐
│  Producer  │── MsgBus  ────▶ │  Consumer  │
└────────────┘                   └────────────┘

⚠️ 必ずお読みください： エンティティイベントバスのプロデューサーとメッセージバスコンシューマーの実装パターンについては、CLAUDE.md を参照してください。

パターン 2：直接 API 呼び出し

次の場合に使用します：リアルタイムデータが必要で、ローカルコピーが不要な場合。

// In Service A, calling Service B API
public class ServiceBApiClient
{
    private readonly HttpClient _client;

    public async Task<UserDto?> GetUserAsync(string userId)
    {
        var response = await _client.GetAsync($"/api/User/{userId}");
        if (!response.IsSuccessStatusCode) return null;
        return await response.Content.ReadFromJsonAsync<UserDto>();
    }
}

考慮事項：

• 回復性を高めるため、サーキットブレーカーを追加する
• 可能な場合はレスポンスをキャッシュする
• サービスが利用できない場合に対処する

パターン 3：共有データベースビュー（アンチパターン！）

:x: 使用禁止：サービス境界に違反します

// WRONG - Direct cross-service database access
var accountsData = await accountsDbContext.Users.ToListAsync();

データ所有権マトリックス

注記： エンティティ所有権マトリックスについては、project-structure-reference.md またはプロジェクトのドキュメントを検索してください。各エンティティを所有するサービスは必ず 1 つだけとし、コンシューマーはメッセージバスを介して同期されたコピーを受け取ります。

同期パターン

全件同期（初期同期／復旧）

// For initial data population or recovery
public class FullSyncJob : BackgroundJobExecutor // project background job base (see docs/project-reference/backend-patterns-reference.md)
{
    public override async Task ProcessAsync(object? param)
    {
        // Fetch all from source
        var allEmployees = await sourceApi.GetAllAsync();

        // Upsert to local
        foreach (var batch in allEmployees.Batch(100))
        {
            await localRepo.CreateOrUpdateManyAsync(
                batch.Select(MapToLocal),
                dismissSendEvent: true);
        }
    }
}

差分同期（イベント駆動）

// Normal operation via message bus
internal sealed class EmployeeSyncConsumer : MessageBusConsumer<EmployeeEventBusMessage> // project message bus base (see docs/project-reference/backend-patterns-reference.md)
{
    public override async Task HandleLogicAsync(EmployeeEventBusMessage message, string routingKey)
    {
        // Check if newer than current (race condition prevention)
        if (existing?.LastMessageSyncDate > message.CreatedUtcDate)
            return;

        // Apply change
        await ApplyChange(message);
    }
}

競合解決

順序付けには LastMessageSyncDate を使用します。メッセージの日時が新しい場合にのみ更新してください。実装の詳細については、CLAUDE.md のメッセージバスコンシューマーパターンを参照してください。

統合チェックリスト

統合前

• データ所有権を明確に定義する
• 同期するフィールドを文書化する
• 依存関係が見つからない場合に備える
• 競合解決戦略を定義する

実装

• メッセージが共有プロジェクトで定義されている
• プロデューサーが適切なイベントをフィルタリングする
• コンシューマーが依存関係を待機する
• 競合状態への対処を実装する
• 論理削除に対処する

テスト

• 作成イベントが正しく処理される
• 更新イベントが正しく処理される
• 削除イベントが正しく処理される
• 順序どおりでないメッセージに対処できる
• 依存関係が見つからない場合に対処できる
• 強制同期が機能する

トラブルシューティング

メッセージが届かない

# Check message broker queues (search for: queue management commands)

# Check producer is publishing
grep -r "HandleWhen" --include="*Producer.cs" -A 5

# Check consumer is registered
grep -r "AddConsumer" --include="*.cs"

データが一致しない

# Compare source and target counts
# In source service DB
SELECT COUNT(*) FROM Employees WHERE IsActive = 1;

# In target service DB
SELECT COUNT(*) FROM SyncedEmployees;

メッセージが停止している

// Check for waiting dependencies
Logger.LogWarning("Waiting for Company {CompanyId}", companyId);

// Force reprocess
await messageBus.PublishAsync(message.With(m => m.IsForceSync = true));

避けるべきアンチパターン

:x: データベースへの直接アクセス

// WRONG
await otherServiceDbContext.Table.ToListAsync();

:x: トランザクション内での同期的なサービス間呼び出し

// WRONG
using var transaction = await db.BeginTransactionAsync();
await externalService.NotifyAsync();  // If fails, transaction stuck
await transaction.CommitAsync();

:x: 依存関係の待機を行わない

// WRONG - FK violation if company not synced
await repo.CreateAsync(employee);  // Employee.CompanyId references Company

// CORRECT
await Util.TaskRunner.TryWaitUntilAsync(() => companyRepo.AnyAsync(...));

:x: メッセージの順序を無視する

// WRONG - older message overwrites newer
await repo.UpdateAsync(entity);

// CORRECT - check timestamp
if (existing.LastMessageSyncDate <= message.CreatedUtcDate)

確認チェックリスト

• データ所有権が明確に定義されている
• メッセージバスパターンを使用している（DB への直接アクセスではない）
• コンシューマーが依存関係を待機している
• タイムスタンプを使って競合状態に対処している
• 論理削除が適切に同期されている
• 強制同期の仕組みが利用できる
• 監視／アラートが設定されている

関連項目

• arch-security-review
• api-design

---

[IMPORTANT] 作業を始める前に、すべての作業を小さなタスクに分割し、各ファイルを読むタスクも含めて、タスク追跡を必ず使用してください。長いファイルによるコンテキストの喪失を防げます。簡単なタスクの場合、AI は省略してよいか必ずユーザーに尋ねてください。

• docs/project-reference/domain-entities-reference.md — ドメインエンティティのカタログ、関係、サービス間同期（タスクにビジネスエンティティ／モデルが関係する場合に読む）（関連する場合は直接読み、フックによって会話に挿入されたテキストに頼らないでください）

次のステップ

必須・重要・例外なし：このスキルを完了した後、必ずユーザーに直接質問し、次の選択肢を提示してください。タスクが「簡単」または「明白」に思えても省略しないでください。決めるのはユーザーです。

• 「$plan（推奨）」 — サービス間統合設計から実装計画を作成する
• 「$architecture-design」 — より広範なアーキテクチャ上の懸念について、引き続き決定が必要な場合
• 「スキップして手動で続行」 — ユーザーが決定する

Council へのエスカレーション（常に提示する、2 回目のプロンプト）

既存の ## Next Steps プロンプトの処理が完了した後、2つ目の独立した、ユーザーへの直接質問を提示してください（最初の質問に統合しないでください）。

• 「評議会をスキップ — 統合設計に進む（推奨）」 — 設計済みのメッセージコントラクト／コンシューマートポロジーで続行します。推奨されるデフォルトです。
• 「$llm-council にエスカレーション」 — 11 個のサブエージェントによる評議会（アドバイザー 5 人＋レビュー担当 5 人＋議長）を実行します。統合によって 3 つ以上のサービスが利用する新しいメッセージコントラクトが導入される場合、ホットパスで同期 API と非同期イベントのどちらを採用するか選ぶ場合、またはサガ／アウトボックス／オーケストレーションパターンを採用する場合に最適です。サービス間コントラクトは、コンシューマーのデプロイ後は元に戻すのが困難です。より低コストな代替手段：$why-review、$plan-validate（まだ実行していない場合は、先にこれらを実行してください）。

AI の誤り防止 — すべてのタスクで避けるべき失敗パターン：

削除する前に、下流の参照を確認してください。 コンポーネントを削除すると、ドキュメントやコードの陳腐化が連鎖的に発生します。削除する前に、参照しているすべてのファイルを洗い出してください。 AI 生成コンテンツを実際のコードと照合して確認してください。 AI は API、クラス名、メソッドシグネチャを幻覚することがあります。ドキュメントに記載したり参照したりする前に、必ず grep で存在を確認してください。 編集後は依存関係の全チェーンをたどってください。 定義を変更しても、そこから派生する下流の変数やコンシューマーを見落とすことがあります。必ずチェーン全体をたどってください。 正しさを検証するときは、すべてのコードパスをたどってください。 コードが存在することの確認は、そのコードが実行されることの確認ではありません。正常系だけでなく、早期終了、エラーブランチ、条件によるスキップも必ずたどってください。 デバッグ時は、修正する前に「どちらの責任か」を確認してください。 バグが呼び出し側（誤ったデータ）にあるのか、呼び出される側（誤った処理）にあるのかをたどってください。責任のあるレイヤーで修正し、症状が現れている箇所にパッチを当てないでください。 既存の値には意図があると考え、変更する前に理由を確認してください。 定数、上限、フラグ、パターンを変更する前に、コメントを読み、git blame を確認し、周辺のコードを調べてください。 最初の出力だけでなく、影響を受けるすべての出力を検証してください。 複数のスタックに関わる変更では、すべての出力を検証する必要があります。1 つのチェックが成功しても、すべてのチェックが成功したことにはなりません。 全体を先に見るデバッグ — 目の前の箇所に飛びつかないでください。 失敗を調査するときは、まず前提条件をすべて列挙してください（設定、環境変数、DB 名、エンドポイント、DI 登録、データの前提条件）。次に、コードレイヤーの仮説を立てる前に、根拠に照らしてそれぞれを検証してください。 変更は最小限に — diff テストを適用してください。 バグ修正では、変更する各行がバグに直接関係している必要があります。隣接するコードのスタイル変更や改善は行わないでください。機能強化タスクでは、改善を実装し、その内容を明示してください。 コーディング前に曖昧さを明らかにし、黙って選択しないでください。 依頼に複数の解釈がある場合は、それぞれの作業量の見積もりを示して質問してください。すべてのレコードを対象とする方法、ファイルベースの方法、より複雑な方法を勝手に選ばないでください。

批判的思考の姿勢 — 批判的思考と逐次的思考を適用してください。すべての主張には、たどって確認できる証拠が必要です。行動に移すのは確信度が 80％を超える場合に限ります。 幻覚の防止： 推測を事実として示さないでください。すべての主張に出典を示し、不確実な点は率直に認め、出力に誤りがないか自分で確認し、独立した情報源で照合し、自身の確信を批判的に評価してください。根拠のない確信こそ、あらゆる幻覚の根本原因です。

証拠に基づく推論 — 推測は禁止です。すべての主張に証拠が必要です。

1. すべての主張について、file:line、grep の結果、またはフレームワークのドキュメントを引用してください
2. 確信度を明示してください：80％超ならそのまま進め、60～80％なら先に検証し、60％未満なら推奨しないでください
3. アーキテクチャの変更には、サービス間の検証が必要です
4. 「十分な証拠がありません」は有効であり、想定される出力です

次の項目が完了するまで作業は禁止： - [ ] 証拠のファイルパス（file:line） - [ ] grep 検索の実施 - [ ] 類似パターンを 3 件以上確認 - [ ] 確信度の明示

根拠なしでの使用を禁止する表現： "明らかに"、"私はこう思います"、"～のはずです"、"おそらく"、"これが原因です" 未完了の場合 → 次を出力してください："Insufficient evidence. Verified: [...]. Not verified: [...]"

• 必須・重要・必ず注意 すべての主張について、file:line の証拠を引用してください。実行するのは確信度が80％を超える場合に限り、60％未満の場合は推奨しないでください。

必ず注意 批判的思考を適用してください。すべての主張に追跡可能な証拠が必要であり、実行するのは確信度が80％を超える場合に限ります。ハルシネーション防止：推測を事実として提示しないでください。

必ず注意 AI の誤りを防止してください。全体を優先してデバッグし、適切なレイヤーで修正し、コーディング前に曖昧さを明らかにし、コンテキスト圧縮後にファイルを読み直してください。

最後に確認すること

• 必須・重要・必ず注意 作業を始める前に、タスク管理を使って作業を小さな todo タスクに分割してください
• 必須・重要・必ず注意 新しいコードを作成する前に、コードベースで類似パターンを3つ以上検索してください
• 必須・重要・必ず注意 すべての主張について、file:line の証拠を引用してください（実行するのは確信度が80％を超える場合）
• 必須・重要・必ず注意 作業の品質を確認するため、最後のレビュー用 todo タスクを追加してください 必須・重要・必ず注意 作業を始める前に、以下のファイルを読んでください。

[TASK-PLANNING] 実行前にタスクの範囲を分析し、タスク管理を使って体系的に小さな todo タスクとサブタスクに分割してください。

フックなしプロンプトプロトコルミラー（自動同期）

ソース：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] ワークフロー実行プロトコル — 必須・重要・必ず遵守。いかなる理由があっても省略しないでください。

汎用的な移植性の境界： 再利用可能なスキルとプロトコルのテキストはプロジェクトに依存しないものとし、プロジェクト固有の規約は docs/project-config.json と docs/project-reference/ から確認してください。共有 AI-SDD は shared/sdd-artifact-contract.md を適用してください。docs/project-config.json と docs/project-reference/docs-index-reference.md を読み、そこに記載されているプロジェクト参照ドキュメントを開いてください。この共有コンテキストとローカルドキュメントが利用可能であれば、サポートされている任意の AI ツールで実行できます。

1. 検出： プロンプトをワークフローカタログと照合する
2. 分析： 最も適合するワークフローを探し、カスタムのステップ構成の方が適切かどうかも評価する
3. 質問（必須形式）： ユーザーが明示的にワークフロー／スキルを呼び出し、ローカルプロトコルで明示的な呼び出しが確認として扱われる場合を除き、次の構成でユーザーに直接質問する：
   • 質問：「どのワークフローを有効にしますか？」
   • オプション1：「[最適なワークフロー] を有効にする（推奨）」
   • オプション2：「カスタムワークフローを有効にする：[ステップ1 → ステップ2 → ...]」（1行の理由を含める）
4. 有効化（確認後）： 標準ワークフローの場合は $workflow-start <workflowId> を呼び出し、カスタムのステップは手動で順番に実行する
5. タスクの作成： すべてのワークフローステップについて、タスク管理を使ってタスクを作成する
6. 実行： 各ステップを順番に実行する [CRITICAL-THINKING-MINDSET] 批判的思考と順序立てた思考を適用してください。すべての主張には追跡可能な証拠が必要であり、実行するのは確信度が80％を超える場合に限ります。 ハルシネーション防止の原則： 推測を事実として提示しないでください。すべての主張について出典を引用し、不確実さは率直に認め、出力に誤りがないか自己確認し、独立して相互参照し、自分の確信度にも懐疑的でいてください。証拠のない確信こそが、あらゆるハルシネーションの根本です。 AI 注意原則（初頭効果・親近効果）： 長いプロンプト／プロトコルでは、最も重要なルールを3つ、冒頭と末尾の両方に配置してください。これにより、長いコンテキストウィンドウでも指示の遵守を維持できます。 目標駆動の実行： 最初に成功基準を定義し、検証済みになるまで繰り返し、観察可能なチェックに合格した場合にのみ終了してください。 テストで意図を検証する： テストでは、現在の挙動をなぞるだけでなく、ビジネスルール／不変条件を守り、保護対象の意図が崩れた場合に失敗するようにしてください。

[LESSON-LEARNED-REMINDER] [BLOCKING] タスク計画と継続的改善 — 必須。省略しないでください。

作業を始める前に、作業を小さなタスクに分けて（タスク追跡を行って）ください。最後のタスクとして「AI のミスと教訓を分析する」を追加してください。

教訓を抽出する — 症状への対処ではなく、根本原因のみ：

1. 症状ではなく、失敗モード（推論や前提の誤り）に名前を付けます。「誤った列挙値を使った」ではなく、「ソースを読まずに API が存在すると仮定した」。
2. 汎用性を確認します。この失敗モードは、3 つ以上の状況やコードベースに当てはまりますか？当てはまらない場合は、もう 1 段階抽象化してください。
3. 普遍的なルールとして記述します。プロジェクト固有の名前、パス、クラスを取り除き、どのコードベースでも役立つ内容にしてください。
4. まとめます。同じ失敗モードに起因する複数のミスは、1 つの教訓にまとめてください。
5. 再発確認：「このリマインダーがなくても、今後のセッションで再発しますか？」いいえの場合は、$learn を省略します。
6. 自動修正確認：「$code-review／$code-simplifier／$security／$lint で検出できますか？」はいの場合は、代わりにレビューのスキルを改善してください。
7. **両方の確認を通過した場合：**ユーザーに $learn の実行を依頼してください。 [TASK-PLANNING] [MANDATORY] ワークフローやスキルの手順を実行する前に、計画したすべての手順についてタスク追跡を作成または更新してください。その後、各手順の開始時と完了時に、タスク追跡の内容を同期してください。