refactoring

Codex 互換性に関する注意：

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

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

Codex では、実行時にプロジェクト文書を注入する代わりに、静的なプロジェクト参照を読み込みます。 コーディング、計画、デバッグ、テスト、レビューを行う際は、以下の経路に従ってプロジェクト文書を明示的に開いてください。

必ず読むもの：

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

コンテキストがない、または古い場合の経路： docs/project-config.json、ドキュメントのインデックス、lessons.md、CLAUDE.md、AGENTS.md、またはタスクに必要な参照文書が存在しないか古い場合は、プロジェクト固有の通常作業を始める前に、$project-init または限定的なセットアップ経路（$project-config、$docs-init、$scan-all、$scan --target=<key>、$claude-md-init）を自動的に実行してください。Codex のミラーまたは AGENTS.md が存在しないか古い場合は、ユーザーに $sync-codex の実行を依頼してください。自動実行はしないでください。

状況に応じて読む文書：

• プロジェクトの構造／アーキテクチャ／技術スタック／デプロイ／セットアップ（バックエンド、フロントエンド、インフラのいずれの層でも）：project-structure-reference.md
• バックエンド／CQRS／API／ドメイン／エンティティの変更：backend-patterns-reference.md、domain-entities-reference.md
• フロントエンド／UI／スタイリング／デザインシステム：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 仕様書の作成、docs/specs/ のパス指定、または TC 形式：feature-spec-reference.md、spec-system-reference.md、spec-principles.md
• 振る舞い／公開契約の変更、または仕様書・テスト・コード間の同期：workflow-spec-test-code-cycle-reference.md と上記の仕様書関連文書
• 派生仕様インデックス／ERD／再実装ガイド：spec-system-reference.md および docs/specs/ 内の元となる Feature Specs
• 統合テストの実装／レビュー：integration-test-reference.md
• E2E テストの実装／レビュー：e2e-test-reference.md
• コードレビュー／監査：code-review-rules.md と、変更対象のファイルに応じたドメイン文書

すべての文書を無差別に読まないでください。まず docs-index-reference.md を確認し、そこからタスクに関連するファイルだけを開いてください。

クイックサマリー

目標： 抽出、移動、簡素化のパターンを使って、動作を変更せずにコードを再構成します。

ワークフロー：

1. 分析 — 対象を特定し、Grep で依存関係をマッピングして、影響を評価し、テストカバレッジを確認します
2. 計画 — リファクタリングの種類、変更内容、リスクを記録します
3. 実行 — リファクタリングを適用します（メソッド／クラスの抽出、エンティティ／拡張への移動、条件分岐の簡素化）
4. 検証 — テストを実行し、動作に変更がないことを確認して、コンパイルをチェックします

主なルール：

• まずテストカバレッジを確保してからリファクタリングします — 既存のテストがないコードは絶対にリファクタリングしません — 理由：リファクタリングで動作が維持されたことを証明できるのはテストだけです
• 小さな変更を段階的に行います。リファクタリングと機能開発を絶対に混在させません
• ロジックは適切なレイヤーのうち最も低い層に配置します（エンティティ > サービス > コンポーネント）

第一原則 — 変更しやすさ

すべてのコーディング上の判断の成功指標は、_将来の変更コスト_です。 DRY、SRP、抽象化、デザインパターン、命名、レイヤリング、テスト — すべての 手法は、次の変更をより低コストにするという1つの目標のために存在します。

コード、リファクタリング、テスト、抽象化を評価するときは、次のように問いかけてください。 これは次の変更をより低コストにしますか、それとも高コストにしますか？

• 変更コストを上げる「ベストプラクティス」は退けてください（時期尚早な抽象化、 推測に基づく汎用性、漏れのある間接化、見返りのない形式主義）。
• 調査結果では、本当の敵を明示してください。結合、隠れた状態、重複した 知識、不明確な意図、早すぎる段階で露出した取り消し不能な決定です。
• 変更しやすいシンプルな設計は、変更しにくい高度な設計に勝ります。

以下の特定のルール、パターン、チェックリストを適用する前に、この観点を適用してください — 下位のルールによって変更コストが上がる場合は、この原則を優先します。

---

調査の心構え（絶対厳守）

懐疑的な姿勢を保ってください。批判的思考と逐次的思考を適用してください。すべての主張には追跡可能な証拠と信頼度が必要です（アイデアは80%を超える必要があります）。

• 「未使用」のコードを変更する前に、すべてのサービスを対象に grep で確認してください — デッドコードだと決めつけないでください — 理由：動的呼び出し、リフレクション、サービスをまたぐ呼び出しは、軽く読むだけでは見つかりません
• すべてのリファクタリングの提案には file:line の根拠を含めてください
• コードパスを安全に変更できると証明できない場合は、「未検証、調査が必要」と明記してください
• 前提に疑問を持ってください：「これは本当にデッドコードか？」→ 動的呼び出しやリフレクションを含め、すべての使用箇所を追跡します
• 網羅性を確認してください：「5つのサービスをすべて調べたか？」→ サービスをまたぐ検証が必須です
• 証拠なしに「リファクタリングすべき」と述べてはいけません — 証拠を示して改善を実証してください

⚠️ 必須：信頼度と証拠のゲート

必須・重要・要注意： あらゆる主張に対して、証拠の一覧と file:line の根拠を添えて Confidence: X% を明記してください。 95%以上なら自由に推奨できます | **80～94%**なら留保事項を添えます | 60～79%なら不明点を列挙します | 60%未満なら停止して、さらに証拠を集めます。 破壊的変更（クラスの削除、インターフェースの変更）には、サービス全体を完全に追跡したうえで95%以上の信頼度が必要です。

コードのリファクタリング

動作を変更せずにコード品質を向上させる構造変更に注力する、コード再構成のエキスパートエージェントです。

リファクタリングカタログ

抽出パターン

パターン	使用する場面	例
メソッドの抽出	メソッドが長い、コードが重複している	ロジックをプライベートメソッドに移動する
クラスの抽出	クラスに複数の責務がある	Helper、Service、Strategy クラスを作成する
インターフェースの抽出	テスト／DI 用の抽象化が必要	I{ClassName} インターフェースを作成する
式の抽出	インライン式が複雑	エンティティの静的式に移動する
バリデーターの抽出	検証ロジックが繰り返される	バリデーターの拡張メソッドを作成する

移動パターン

パターン	使用する場面	例
メソッドの移動	メソッドが別のクラスに属する場合	Handler から Helper／Entity に移動する
拡張メソッドへの移動	再利用可能なリポジトリロジックの場合	{Entity}RepositoryExtensions を作成する
DTO への移動	ハンドラーにマッピングロジックがある場合	プロジェクトの DTO 基底クラスの .MapToEntity() を使用する（docs/project-reference/backend-patterns-reference.md を参照）
Entity への移動	ハンドラーにビジネスロジックがある場合	インスタンスメソッドまたは静的式を追加する

簡素化パターン

パターン	使用する場面	例
変数のインライン化	一度しか使われない一時変数	中間変数を削除する
メソッドのインライン化	メソッド本体が明白な場合	呼び出しを本体に置き換える
条件分岐の置き換え	複雑な if／switch	Strategy パターンまたは式を使う
パラメーターオブジェクトの導入	メソッドのパラメーターが多い場合	Command／Query DTO を作成する

ワークフロー

フェーズ 1：分析

1. 対象の特定：リファクタリングするコードを見つけます
2. 依存関係の把握：Grep を使ってすべての使用箇所を見つけます
3. 影響の評価：影響を受けるファイルとテストを一覧にします
4. テストの確認：テストカバレッジがあることを確認します
5. 外部メモリ：分析結果を .ai/workspace/analysis/{refactoring-name}.analysis.md に書き込みます。計画を立てる前に再読してください。

フェーズ 2：計画

リファクタリング計画を記録します：

## Refactoring Plan

**Target**: [file:line_number]
**Type**: [Extract Method | Move to Extension | etc.]
**Reason**: [Why this refactoring improves code]

### Changes

1. [ ] Create/modify [file]
2. [ ] Update usages in [files]
3. [ ] Run tests

### Risks

- [Potential issues]

フェーズ 3：実行

以下の原則はスタックに依存しません。データを所有する最下層へロジックを移動します（ここでは、ハンドラー／ユースケース内の条件を、エンティティが所有する述語に置き換えます）。コードは特定のスタックにおける実装例です。形をお使いの言語に合わせてください。

例（説明用 — お使いの言語に合わせてください）：

// BEFORE: Logic in handler
protected override async Task<Result> HandleAsync(Command req, CancellationToken ct)
{
    var isValid = entity.Status == Status.Active &&
                  entity.User?.IsActive == true &&
                  !entity.IsDeleted;
    if (!isValid) throw new Exception();
}

// AFTER: Extracted to entity static expression
// In Entity.cs
public static Expression<Func<Entity, bool>> IsActiveExpr()
    => e => e.Status == Status.Active &&
            e.User != null && e.User.IsActive &&
            !e.IsDeleted;

// In Handler
var entity = await repository.FirstOrDefaultAsync(Entity.IsActiveExpr(), ct)
    .EnsureFound("Entity not active");

フェーズ 4：検証

1. 影響を受けるテストを実行します
2. 振る舞いに変更がないことを確認します
3. コードがコンパイルできることを確認します
4. 一貫性を確認します

レイヤーへの移動を伴うリファクタリング（具体例）

以下の 3 つのリファクタリングは、共通の原則に基づいています。オーケストレーション層（ハンドラー／ユースケース）から、関心事を所有する層へロジックを移動します。再利用されるロジックは共有ヘルパーへ、クエリロジックはデータアクセス拡張へ、マッピングは DTO へ移動します。これらの形は、どのスタックにも当てはめられます（「ヘルパー」とは、一貫した役割を持つ協力オブジェクトです。「拡張」とは、お使いの言語で再利用可能なクエリメソッドを追加するあらゆる方法です。「DTO がマッピングを所有する」とは、オーケストレーターではなくデータ転送型が自身の変換を定義する、というルールです）。お使いのスタックにおける具体的なプリミティブについては、プロジェクトのバックエンドパターンリファレンスを参照してください。

例（説明用 — お使いの言語に合わせてください）：

ハンドラーからヘルパーへ — 再利用されるロジックを共有の協力オブジェクトに移動

// BEFORE: Reused logic in multiple handlers
var order = await repo.FirstOrDefaultAsync(Order.UniqueExpr(userId, customerId), ct)
    ?? await CreateOrderAsync(userId, customerId, ct);

// AFTER: Extracted to Helper
// In OrderHelper.cs
public async Task<Order> GetOrCreateOrderAsync(string userId, string customerId, CancellationToken ct)
{
    return await repo.FirstOrDefaultAsync(Order.UniqueExpr(userId, customerId), ct)
        ?? await CreateOrderAsync(userId, customerId, ct);
}

ハンドラーからリポジトリ拡張へ — クエリロジックをデータアクセス層に移動

// BEFORE: Query logic in handler
var orders = await repo.GetAllAsync(
    e => e.CustomerId == customerId && e.Status == Status.Active && e.WarehouseIds.Contains(warehouseId), ct);

// AFTER: Extracted to extension
// In OrderRepositoryExtensions.cs
public static async Task<List<Order>> GetActiveByWarehouseAsync(
    this I{Service}RootRepository<Order> repo, string customerId, string warehouseId, CancellationToken ct)
{
    return await repo.GetAllAsync(
        Order.OfCustomerExpr(customerId)
            .AndAlso(Order.IsActiveExpr())
            .AndAlso(e => e.WarehouseIds.Contains(warehouseId)), ct);
}

マッピングを DTO へ — データ転送型が自身の変換を所有

// BEFORE: Mapping in handler
var config = new AuthConfig
{
    ClientId = req.Dto.ClientId,
    Secret = encryptService.Encrypt(req.Dto.Secret)
};

// AFTER: DTO owns mapping
// In AuthConfigDto.cs : DtoBase<AuthConfig> // project DTO base class (see docs/project-reference/backend-patterns-reference.md)
public override AuthConfig MapToObject() => new AuthConfig
{
    ClientId = ClientId,
    Secret = Secret  // Handler applies encryption
};

// In Handler
var config = req.Dto.MapToObject()
    .With(c => c.Secret = encryptService.Encrypt(c.Secret));

インデックス影響チェック

[IMPORTANT] データベースパフォーマンスプロトコル（必須）：

1. ページング必須 — すべてのリスト／コレクションクエリで、必ずページングを使用してください。すべてのレコードをメモリに読み込んではいけません。確認事項：Skip/Take またはカーソルベースのページングを使わない、無制限の GetAll()、ToList()、Find() がないこと。
2. インデックス必須 — すべてのクエリのフィルターフィールド、外部キー、ソート列に、データベースインデックスを必ず設定してください。確認事項：エンティティ式がインデックスのフィールド順と一致していること、データベースコレクションにインデックス管理メソッドがあること、マイグレーションに WHERE／JOIN／ORDER BY 列のインデックスが含まれていること。

式を抽出したり、クエリを移動したりする場合は、インデックスの適用状況を確認してください。

• 新しい式のフィールドに DbContext のインデックスが設定されていますか？
• 移動したクエリでは、引き続きインデックス付きフィールドを使用していますか？
• リファクタリングしたフィルターで、インデックスの選択性順序が維持されていますか？
• リストクエリでページングを使用していますか（無制限の GetAll/ToList がないこと）？

安全性チェックリスト

リファクタリングを行う前に：

• すべてのサービス全体で、静的・動的・リフレクションによるすべての使用箇所を検索しましたか？
• テストカバレッジがありますか？
• todo リストに記録しましたか？
• 変更は段階的ですか？
• 動作に変更がないことを確認しましたか？
• 信頼度を明示しましたか — 根拠の一覧とともに Confidence: X% を記載しましたか？

チェックリストに未完了の項目が1つでもある場合 → 停止してください。「進めるための十分な根拠がありません」と伝えてください。

コード責務のリファクタリング（優先度チェック）

⚠️ 必ず確認してください： Entity/Model > Service > Component のレイヤー規則について、CLAUDE.md の「Code Responsibility Hierarchy」を読んでください。リファクタリング時には、ロジックが適切な最下層のレイヤーにあることを確認してください。

コンポーネント HTML と SCSS の標準

⚠️ 必ず確認してください： BEM クラスの要件と host／wrapper のスタイリングパターンについて、CLAUDE.md の「Component HTML Template Standard (BEM Classes)」と docs/project-reference/scss-styling-guide.md を読んでください。コンポーネントのリファクタリング時には、すべての HTML 要素に適切な BEM クラスが付与されていることを確認してください。

アンチパターン

• 一括リファクタリング：小規模で段階的な変更を行ってください
• テストなしのリファクタリング：まずカバレッジを確保してください
• 機能追加とリファクタリングの混在：どちらか一方を行ってください
• 公開 API の破壊：後方互換性を維持してください
• 誤ったレイヤーのロジック：コードの重複につながります。適切な最下層のレイヤーに移動してください

リファクタリングしたファイルに対して python .claude/scripts/code_graph connections <file> --json を実行し、更新が必要なすべての利用箇所を見つけてください。

グラフインテリジェンス（graph.db がある場合に推奨）

.code-graph/graph.db がある場合は、構造に関するクエリを使って分析を強化してください。

• 再構成の影響 — 呼び出し元を追跡： python .claude/scripts/code_graph query callers_of <function> --json
• 再構成の影響 — インポート元を確認： python .claude/scripts/code_graph query importers_of <module> --json
• 一括分析： python .claude/scripts/code_graph batch-query file1 file2 --json

グラフクエリのパターンについては、上記の SYNC:graph-assisted-investigation ブロックを参照してください。

リファクタリングの影響をグラフで追跡

グラフ DB を利用できる場合、リファクタリングの前に追跡し、すべての利用箇所を確認してください。

• python .claude/scripts/code_graph trace <file-to-refactor> --direction downstream --json — このコードに依存する、すべての下流の利用箇所
• python .claude/scripts/code_graph trace <file-to-refactor> --direction both --json — 呼び出し元と利用箇所の全体像
• リファクタリング計画で対応していない利用箇所があれば、必ず明示してください。気づかないうちに壊れる可能性があります。

関連項目

• code-simplifier
• code-review

---

ワークフローの推奨

必須・重要・必ず実行 — 例外なし： すでにワークフローを進めているのでない場合は、必ずユーザーに直接尋ねてください。タスクの複雑さを判断したり、「簡単だから省略してよい」と決めたりしてはいけません。ワークフローを使うかどうかを決めるのは、あなたではなくユーザーです。

1. workflow-refactor ワークフローを有効にする（推奨） — scout → investigate → plan → plan-execute → review → production-readiness-review → test → docs
2. $refactoring を直接実行する — このスキルを単独で実行

---

AI エージェント完全性ゲート（交渉不可）

完了 ≠ 正確性。 作業を完了したと報告する前に、必ずその根拠を示してください。

1. 削除したすべての名前を grep で確認します。 抽出、名前変更、削除の対象が N ファイルに及ぶ場合、すべてのファイル形式を対象に grep を実行し、参照が残っていないことを確認します。
2. 変更する前に理由を確認します。 既存の値は、そうではないと証明されるまでは意図的なものです。理由を追跡できない限り、「修正」してはいけません。
3. すべての出力を検証します。 1 つのビルドが成功しても、すべてのビルドが成功したことにはなりません。影響を受けるスタックをすべて確認します。
4. パターンに適合するか評価します。 近くのコードをコピーする場合、前提条件が一致することを確認します。同じスコープ、ライフタイム、基底クラス、制約である必要があります。
5. 新しい成果物は、組み込まれて初めて完成です。 何かを作成した場合、それが登録され、インポートされ、すべての利用者からアクセス可能であることを証明します。

[IMPORTANT] コンテキストの喪失を防ぐため、作業を始める前にタスク管理を使って、ファイルごとの読み取りタスクも含め、すべての作業を小さなタスクに分割してください。簡単なタスクの場合、AI は必ず、スキップしてよいかユーザーに尋ねてください。

• docs/project-reference/domain-entities-reference.md — ドメインエンティティのカタログ、関係、サービス間の同期（タスクにビジネスエンティティやモデルが関係する場合に読みます）

グラフを活用した調査 — .code-graph/graph.db が存在する場合は必須です。

厳格なゲート： 調査を完了する前に、主要ファイルに対してグラフコマンドを少なくとも 1 つ実行しなければなりません。

手順： Grep でファイルを特定 → trace --direction both でシステム全体のフローを確認 → Grep で詳細を検証

タスク	最低限必要なグラフ操作
調査／探索	2～3 個のエントリーファイルに対して trace --direction both を実行
修正／デバッグ	不具合のある関数に対して callers_of と tests_for を実行
機能／拡張	変更対象のファイルに対して connections を実行
コードレビュー	変更した関数に対して tests_for を実行
影響範囲	trace --direction downstream を実行

CLI： python .claude/scripts/code_graph {command} --json。最初に --node-mode file を使用してノイズを 10～30 分の 1 に減らし、その後、詳細を確認するために --node-mode function を使用します。

ネストされたタスクの展開契約 — ワークフローのステップを呼び出す場合、[Workflow] ... の行は親コンテナにすぎません。子スキルも、可視のフェーズタスクを作成します。

1. 最初に現在のタスクリストを取得します。一致するアクティブな親ワークフロー行がある場合は、nested=true を設定して parentTaskId を記録します。それ以外の場合は、単独で実行します。
2. フェーズ作業を始める前に、宣言された各フェーズにつき 1 つのタスクを作成します。ネストしている場合、サブジェクトには [N.M] $skill-name — phase の形式で接頭辞を付けます。
3. ネストしている場合は、TaskUpdate(parentTaskId, addBlockedBy: [childIds]) で親にリンクします。
4. オーケストレーターは、子スキルまたはサブエージェントを呼び出す前に、子スキルのフェーズ一覧を事前に展開し、ワークフロー行をリンクする必要があります。
5. 作業を始める前に、子タスクのうち正確に 1 つを in_progress にし、根拠を記録した直後に completed にします。
6. すべての子タスクが完了するか、理由を明記して明示的にキャンセルされた後にのみ、親タスクを完了します。

開始条件： 現在のタスクリストを取得し、子フェーズを作成し、ネストしている場合は親をリンクし、最初の子タスクを in_progress にすること。 プロジェクト参照ドキュメントのゲート — タスク追跡の初期設定後、対象ファイルやソースファイルの読み取り、grep、編集、分析を行う前に実行します。プロジェクトのドキュメントは、汎用的なフレームワークの前提より優先されます。

1. 対象範囲を特定します：ファイルの種類、ドメイン領域、操作内容。
2. まず docs/project-config.json を読みます — プロジェクトの機械可読なマップです。 このリポジトリの唯一の信頼できる情報源です（モジュール／パス、フレームワークと検索キーワード、テスト／E2E／統合テストの実行コマンド、デザインシステム、アーキテクチャルール、ワークフローパターン）。調査、計画、コーディングの前に、正確なパス、実行コマンド、規約をこれに基づいて確認してください。フレームワークの既定値を決して仮定しないでください（CLAUDE.md と参照ドキュメントはこれを元に生成されています）。これ、またはドキュメントインデックス、lessons.md、CLAUDE.md、AGENTS.md、必須の参照ドキュメントが存在しないか古い場合は、まず $project-init または該当する限定ルート（$project-config、$docs-init、$scan-all、$scan --target=<key>、$claude-md-init）を自動実行します。Codex のミラーまたは AGENTS.md が古い場合は、ユーザーに $sync-codex の実行を依頼してください（自動実行はしないでください）。
3. トリガーごとに必要なドキュメント：常に docs/project-reference/lessons.md、ドキュメント検索時は docs-index-reference.md、レビュー時は code-review-rules.md、バックエンド／CQRS／API では backend-patterns-reference.md、ドメイン／エンティティでは domain-entities-reference.md、フロントエンド／UI では frontend-patterns-reference.md、スタイル／デザインでは scss-styling-guide.md + design-system/design-system-canonical.md、統合テストでは integration-test-reference.md、E2E では e2e-test-reference.md、機能ドキュメント／仕様では feature-spec-reference.md + spec-system-reference.md + spec-principles.md、動作／パブリックコントラクト／仕様／テストコードの同期では workflow-spec-test-code-cycle-reference.md、派生仕様インデックス／ERD／再実装ガイドでは spec-system-reference.md + docs/specs/ 配下の元となる Feature Specs、アーキテクチャ／新しい領域では project-structure-reference.md。
4. 必須ドキュメントをすべて読み、その後、対象作業を始める前に次の形式で記載します：Reference docs read: ... | Not applicable: ...。

準備完了の条件： 対象範囲を評価し、docs/project-config.json を参照し、必須ドキュメントを確認／読了するかセットアップルートを完了し、lessons.md を確認し、出典を明記していること。

批判的思考の姿勢 — 批判的思考と順序立てた思考を適用します。行動に移すには、すべての主張に追跡可能な証拠があり、確信度が80%を超えている必要があります。 ハルシネーション対策： 推測を事実として示してはいけません。すべての主張に出典を示し、不確実性は率直に認め、出力に誤りがないか自ら確認し、独立して相互参照し、自分の確信にも懐疑的でいてください。根拠のない確信は、あらゆるハルシネーションの根源です。

まずコードを理解する — 厳格なゲート：既存コードを読むまで、作成、計画、修正を行ってはいけません。

1. 類似パターンを3つ以上検索します（grep／glob）— file:line 形式で証拠を示します
2. 対象領域の既存ファイルを読み、構造、基底クラス、規約を理解します
3. .code-graph/graph.db が存在する場合は、python .claude/scripts/code_graph trace <file> --direction both --json を実行します
4. connections または callers_of で依存関係をマッピングし、対象に依存するものを把握します
5. 重要なタスク（3ファイル以上）では、調査内容を .ai/workspace/analysis/ に記録します
6. 実装前に分析ファイルを読み直します。記憶だけを頼りに作業してはいけません。 — 理由：長いコンテキストではファイルからの乖離が起きます。ファイルが信頼できる情報源です
7. 既存のパターンで対応できる場合、新しいパターンを決して作りません。正確に踏襲するか、逸脱を記録します。 — 理由：パターンの不統一はコードベースを断片化し、将来の読者全員の作業を遅らせます

以下が完了するまで作業不可： - [ ] 対象ファイルを読んだ - [ ] 3つ以上のパターンを grep した - [ ] グラフをトレースした（graph.db が存在する場合） - [ ] 前提を証拠で検証した エビデンスに基づく推論 — 推測は禁止です。あらゆる主張に証拠が必要です。

1. すべての主張について、file:line、grep の検索結果、またはフレームワークのドキュメントを引用してください
2. 信頼度を明示してください：80%超なら自由に実行、60～80%なら先に検証、60%未満なら推奨しない
3. アーキテクチャの変更には、サービスをまたいだ検証が必要です
4. 「証拠が十分ではありません」は妥当であり、期待される回答です

以下が完了するまで作業はブロックされます： - [ ] 証拠のファイルパス（file:line）- [ ] grep 検索を実施済み - [ ] 類似パターンを3つ以上発見済み - [ ] 信頼度を明示済み

証拠なしでの使用は禁止： 「明らかに」、「私はこう思います」、「〜すべきです」、「おそらく」、「これは〜が原因です」 未完了の場合 → 次を出力してください："証拠が不十分です。検証済み：[...]。未検証：[...]。"

デザインパターンの品質 — あらゆるコード変更で優先して確認する項目：

1. OOP による DRY： 目的、命名パターン、またはライフサイクルが同じクラス／モジュールを特定します。プロジェクトの言語／フレームワークに関する知識を用いて、慣用的な抽象化（基底クラス、ミックスイン、トレイト、プロトコル、デコレーター）を判断します。類似パターンが3つ以上ある場合は、共通の抽象化に切り出します。
2. 適切な責務： ロジックは最も低いレイヤーに配置します（エンティティ > ドメインサービス > アプリケーションサービス > コントローラー）。コントローラーにビジネスロジックを置いてはいけません。
3. SOLID： 単一責任（変更理由は1つ）。オープン・クローズド（変更せずに拡張）。リスコフの置換（サブタイプは置換可能）。インターフェース分離（小さなインターフェース）。依存性逆転（抽象に依存）。
4. 切り出し／移動／名前変更の後： 対象範囲全体を grep し、参照漏れを確認します。見逃しは一切許容しません。
5. YAGNI の基準： 同じパターンが3つ以上存在しない限り、パターンを推奨してはいけません。将来の仮定に基づいて切り出してはいけません。

指摘すべきアンチパターン： ゴッドオブジェクト、コピーペーストによる継承、循環依存、抽象化の漏れ。

デザイン品質の逐次的な確認 — すべての懸念を一度に確認するのではなく、品質の各観点を1つずつ確認します（逐次的なパス）。— 理由：注意を分散させると、1つの観点に集中するパスなら発見できる違反を見逃します。

1. 該当する観点を特定する — コードの言語、ドメイン、パターンに基づいて、DRY、SOLID 原則（SRP／OCP／LSP／ISP／DIP）、OOP の慣用表現、凝集度／結合度、GRASP、デメテルの法則、CQRS の不変条件など、どの品質観点が該当するかを判断します。観点の一覧は固定ではありません。コードが実際に何をするかから導き出してください。
2. 各観点に集中したパスを1回ずつ実施する — 各観点について、順番に1つずつ集中して確認します。パスをまたいで懸念事項を混在させてはいけません。
3. しきい値：類似パターンが3つ以上あれば切り出しは必須 — 任意の提案ではありません。対応が必要な、必須の構造修正として指摘してください。
4. 同種の違反が2つ以上あれば構造上の問題 — 個別事例の羅列ではなく、アーキテクチャ上の解決が必要な「パターンの問題」として報告してください。

ソース／テストの乖離チェック。 コーディング、修正、デバッグ、調査、テスト、レビューを行う場合、ソースの動作が変わったら、影響を受ける単体／統合／E2E テストを調べ、意図した動作に合わせてテストを変更すべきか、ソースの変更が意図しないバグであり修正すべきかを、証拠に基づいて判断します。マイグレーションコードのテストは作成しないでください。スキーマ／データのマイグレーションは一度限りの実行パスであり、コアアプリケーションロジックではありません。 AI のミス防止 — すべてのタスクで避けるべき失敗パターン：

コンテキストが変わったらファイルを読み直してください。 コンテキストの圧縮、中断後の再開、長時間にわたる作業によって、記憶が古くなることがあります。作業に取りかかる前に、現在のファイルを確認してください。 生成した内容を根拠となるソースと照合してください。 AI は API、名前、主張、ドキュメントの事実を幻覚することがあります。文書化または参照する前に、該当するソースを確認してください。 削除または名前変更の前に、下流の参照を確認してください。 成果物を削除すると、ドキュメント、生成されたミラー、設定、呼び出し元の参照が古くなる可能性があります。まず参照先を洗い出してください。 編集後は影響範囲全体を追跡してください。 定義を変更しても、派生出力や利用側への影響を見落とすことがあります。完了を宣言する前に、影響を受ける連鎖をたどってください。 最初の出力だけでなく、影響を受ける出力をすべて検証してください。 1 つのチェックが成功しても、すべてのチェックが成功したとは限りません。変更によって影響を受ける可能性のあるすべての出力面を検証してください。 既存の値は意図的なものとみなし、変更または不具合として指摘する前に、必ず理由を確認してください。 定数、上限、フラグ、しきい値、文言、パターンを変更または報告する前に、近くのコンテキストと履歴、CALLER 側の順序、および同じ規約を使う 2 か所以上の兄弟呼び出し箇所を確認してください。理由を示さず WHAT だけを記したドキュメントは、根拠となるガードがない証拠ではなく、根拠の説明が不足しています。 行動する前に曖昧さを明示してください。黙って解釈を選ばないでください。 複数の妥当な解釈がある場合は、明示的に質問するか、リスクを添えて前提を述べてください。 インフラが管理する中間状態ではなく、システムが責任を持つ結果を検証してください。 非同期処理を検証するときは、最終的なビジネス状態をアサートしてください。共有インフラ内で同時実行中のどのプロセスからも書き込める、配信や再試行の管理情報をアサートしてはいけません。このようなチェックは単独実行では通過しても、同じインフラをほかの処理と共有した途端に不安定になります。 共有ガイダンスは、対象となる役割に関係するものにしてください。 普遍的なガイダンスは、それを受け取るすべてのスキルやエージェントに役立つものでなければなりません。コード固有の要件は、コード固有のプロトコルにのみ記載してください。

重要・必ず注意 変更を加える前に、既存のパターンを 3 つ以上検索し、コードを読んでください。graph.db が存在する場合は、グラフトレースを実行してください。

重要・必ず注意 すべての主張に file:line の根拠を明記してください。行動するのは確信度が 80% 超の場合に限り、60% 未満の場合は推奨しないでください。

重要・必ず注意 OOP による DRY、適切な責務レイヤー、SOLID を確認してください。移動後は、参照先がなくなった参照を grep で検索してください。

重要・必ず注意 graph.db が存在する場合は、重要なファイルに対して少なくとも 1 つのグラフコマンドを実行してください。パターン：grep → trace → verify。

必ず注意 重要かつ順を追った思考を適用してください。すべての主張に、適切な追跡可能な根拠が必要です（リポジトリ／コードに関する主張には file:line、調査、製品、コンテンツ、ドキュメントに関する主張にはソース URL または成果物のセクション）。行動するのは確信度が 80% 超の場合に限り、60% 未満の場合は推奨しないでください。幻覚防止：推測を事実として示さず、不確実な点は率直に認め、独立した情報源と照合し、自分の確信度にも懐疑的でいてください。

必ず注意 AI のミス防止を適用してください。生成した内容を根拠と照合し、削除または名前変更の前に下流の参照を追跡し、影響を受ける出力をすべて検証し、コンテキスト喪失後はファイルを読み直し、行動する前に曖昧さを明示してください。

• 必須 調査、計画、コーディングを始める前に、docs/project-config.json（モジュール／パス、実行コマンド、規約、アーキテクチャ／ワークフロールールを記載したプロジェクトマップ）と、必須のプロジェクト参照ドキュメントを読んでください。また、Reference docs read: ... と明記してください。

• 必須 必ず lessons.md を含めてください。プロジェクト設定と規約は、汎用的なフレームワークのデフォルトより優先されます。

• 必須 プロジェクト設定、ルートの指示ファイル、または必須の参照ドキュメントが欠落しているか古くなっている場合は、通常のプロジェクト固有作業に入る前に、$project-init または適切な下位レベルの手順を自動的に実行してください。

• 必須 親ワークフローの項目で、子フェーズの追跡を代替しないでください。ネストしている場合は、フェーズを展開し、親にリンクしてください。

• 必須 オーケストレーターは呼び出し前に子スキルのフェーズを展開してください。[N.M] $skill-name — phase のプレフィックスを使用し、in_progress は常に 1 つだけにしてください。

プロジェクトプロトコルオーバーレイ — このスキルを実行する前に、このスキルに適用されるプロジェクトオーバーレイルールを解決してください。プロジェクトのスキルプロトコルインデックス（デフォルトでは docs/project-reference/skill-protocols-reference.md。docs/project-config.json の referenceDocs エントリでパスが上書きされます）の Target 列とこのスキル名を照合し、最も具体的に一致する階層のみを適用します（完全一致 > glob > *）。この優先順位が定めるのはオーバーレイ同士の関係のみであり、このスキルとの優先順位ではありません。 一致した本文のみを読み、<protocols-dir>/<Name>.md として解決してください。行の Body リンクは表示テキストであり、読み込みパスではありません。一致した本文が存在しない、または不正な形式の場合は、その旨を報告してスキップしてください。インデックスの Description から本文を再構成してはなりません。インデックスがない場合、または一致する項目がない場合は、オーバーレイなしで、何も告げずに続行してください。契約の全文は .claude/skills/project-skill-protocol/references/registry.md を参照してください。

オーバーレイは追加のみです。このスキル独自のプロトコルにルールを追加するものであり、すでに記載されているルールを置き換えたり、上書き、無効化、再解釈したりしてはなりません。すべてのオーバーレイを取り除いたとき、このスキルの動作が文書化された内容と完全に一致する必要があります。オーバーレイは簡潔な補足であり、権限を拡大するものではありません。ワークフローのゲート、Git の規律、レビューゲート、ユーザー確認ゲートを免除することはできません。オーバーレイとスキルの間に実際の矛盾がある場合、または同じ具体性のオーバーレイ同士が直接矛盾する場合は、両方をユーザーに提示してください。決して黙って解決してはなりません。

必ず注意： 実行前に、このスキルに適用されるプロジェクトプロトコルオーバーレイを解決してください。最も具体的に一致する階層のみを適用します（完全一致 > glob > *。この優先順位はオーバーレイ同士の関係を定めるものであり、このスキルとの優先順位ではありません）。一致した本文のみを <protocols-dir>/<Name>.md から読みます。本文がない、または不正な形式の場合は報告し、決して再構成しません。オーバーレイは追加のみであり（このスキル独自のルールを置き換えません）、簡潔な補足であって、権限を拡大するものではありません。同じ具体性の項目間に矛盾がある場合は、ユーザーに提示してください。

締めくくりのリマインダー

適用中のプロトコル（このスキルが持つ SYNC／共有ブロックの簡潔な要約）：

• グラフを利用した調査： graph.db が存在する場合、重要なファイルについてグラフコマンドを必ず1つ以上実行します。
• ネストされたタスクの作成： ネストされたタスクでは、子フェーズを展開し、親タスクにリンクします。
• プロジェクトリファレンスドキュメント： 必須のプロジェクトリファレンスドキュメントを必ず読み、対象の作業を始める前に引用します。
• 批判的思考： 批判的かつ順序立てて考え、根拠を追跡し、行動前に80%を超える確信を得ます。
• まずコードを理解する： 変更前に、必ず3つ以上のパターンを検索してコードを読みます。
• 根拠： すべての主張に file:line を引用します。確信度が60%未満の内容は決して推奨しません。
• デザインパターンの品質： OOP で DRY を保ち、責務を最下層に置き、SOLID を守ります。移動後は参照切れがないか grep で確認します。
• ソースとテストの乖離： ソースの動作を変更した場合、根拠に基づいて影響を受けるテストも整合させます。
• AI の誤り防止： 生成内容を根拠と照合し、下流の参照を追跡し、影響を受ける出力をすべて確認し、コンテキスト喪失後は読み直し、曖昧さを明示します。

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

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

---

締めくくりのリマインダー — 変更しやすさが成功の指標です。 すべての発見、テスト、リファクタリング、抽象化について、次の1つの問いに答えてください。これによって、次の変更はより安くなるか、それとも高くなるか？ 将来の変更コストを減らせないなら、採用しないでください。真の敵は、結合、隠れた状態、重複した知識、意図の不明瞭さです。これらの問題を明確に指摘してください。

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

ソース：.claude/.ck.json ＋ .claude/skills/shared/sync-inline-versions.md（:full ブロック）＋ .claude/scripts/lib/hookless-prompt-protocol.cjs

[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 を読み、そこに記載されたプロジェクトリファレンスドキュメントを開いてください。仕様、テストケース、動作変更、公開コントラクト、または docs/specs/ に関する作業では、ドキュメントインデックスに記載されたローカルの仕様ドキュメント（feature-spec-reference.md、spec-system-reference.md、spec-principles.md、および仕様・テスト・コードの同期が必要な場合は workflow-spec-test-code-cycle-reference.md）を経由してください。いずれかのファイルまたは必須のリファレンスドキュメントが存在しないか、古くなっている場合は、通常のプロジェクト固有の作業を始める前に、$project-init（または $project-config、$docs-init、$scan-all、$scan --target=<key> など、対象を絞った下位レベルの手順）を自動実行してください。この共有コンテキストとローカルドキュメントが利用可能であれば、サポートされている任意の AI ツールで実行できます。

1. 検出： プロンプトが明示的なスラッシュ形式のスキル／ワークフローコマンドで始まる場合は、そのコマンドを直接実行します。それ以外の場合は、ワークフローカタログとスキルリストに照らしてプロンプトを判定します。
2. 分析： 最適な選択肢を決定します。直接実行、スキルの呼び出し、標準ワークフローの起動、またはカスタム手順の組み合わせです。
3. 自動選択： 最適な選択肢を自分で選びます。直接実行、スキル、標準ワークフロー、カスタムワークフローのどれにするか、ユーザーに選択を求めてはいけません。
4. 起動： ワークフローを選択した場合は $start-workflow <workflowId> を呼び出し、スキルを選択した場合はそのスキルを呼び出し、カスタムワークフローの場合はカスタム手順を順に実行し、直接実行の場合はタスクに着手します。
5. タスクの作成： 選択した経路に複数の手順がある場合は、実行前にワークフロー／スキル／カスタム手順のすべてについてタスクを追跡します。
6. 並列化： タスクリストの実行前に、各タスクに PAR（入力が独立しており、書き込み対象が他のすべての PAR タスクと重複しない）または SEQ（依存するブロッキングタスクを明記）を付け、PAR タスクをウェーブに分け、ウェーブ計画を宣言したうえで、各ウェーブのサブエージェントを1つのメッセージで起動します。各ウェーブは全員の完了を待つバリアとし、サブエージェント自身の定義でそれ以上のファンアウトが認められていない限り、ファンアウトは1階層に限ります。独立したタスクをデフォルトで順次実行するのは不備です。ただし、書き込み先が共有されるタスク、他の出力を消費するタスク、単純な単一ファイル作業、スキルまたはワークフローが明示的に順序を固定している場合、ユーザー承認を要する場合は並列化しないでください。
7. 実行： コンテキスト指示にある ワークフローのステップ進行と並列フェーズ の規則に従って進めます。進行はモデル主導です。サブエージェントの完了はインライン呼び出しと同様にステップを進めます。並列フェーズのグループは全員の完了を待つバリアであり、全メンバーの応答が返るまで次に進んではいけません。決して逐次化しないでください。

共有 AI-SDD プロトコルマーカー

ソース：.claude/skills/shared/sync-inline-versions.md

SYNC:ai-sdd-artifact-contract

AI-SDD 成果物契約 — 共有する仕様駆動開発のルールは、移植可能な状態に保ち、ソース側で管理します。

1. 再利用可能な AI-SDD の原則は .claude に置き、リポジトリ固有のパス、コマンド、担当者、製品、形式はプロジェクト設定または参照ドキュメントに記載します。
2. サイクルを維持します：spec -> plan -> tasks -> implement -> verify -> update spec/docs。
3. すべての要件または不変条件を、判断、タスク、TC／テスト、ソースの根拠、ドキュメント／仕様の更新まで追跡します。
4. コードから仕様への抽出は、正規の仕様オーナーが承認するまでは参照専用として扱います。
5. 同期されたコンテキストがあれば、サポート対象の AI ツールで計画、実装、レビュー、検証を行えます。複数のツールを使うかどうかは任意です。
6. まず .claude のソースを更新してから、生成されたミラーを同期します。.agents、.codex、AGENTS.md を手動で編集しないでください。— 理由：ミラーは生成された成果物であり、次回の同期時に手動編集内容が上書きされます
7. docs/project-config.json、ルートの指示ファイル、または必須のプロジェクト参照ドキュメントが欠落しているか古い場合は、通常のプロジェクト固有の作業を行う前に、$project-init または適切な下位レベルの手順を自動実行します。

有効な参照先： アクティブなスキルルート内の shared/sdd-artifact-contract.md。

---

SYNC:ai-sdd-artifact-contract:reminder

• 必須 shared/sdd-artifact-contract.md を適用し、再利用可能な AI-SDD は .claude に、ローカルルールはプロジェクトのドキュメントに保持します。
• 必須 コードから仕様への抽出は、正規の承認を得るまで参照専用です。サポート対象の AI ツールであれば、同期されたコンテキストを使って実行できます。
• 必須 生成されたミラーを同期する前に .claude のソースを更新します。.agents、.codex、AGENTS.md を手動で編集しないでください。
• 必須 プロジェクト設定、ルートの指示ファイル、または必須の参照ドキュメントが欠落しているか古い場合は、プロジェクト固有の作業を $project-init または適切なセットアップ手順に自動的に振り分けます。 [TASK-PLANNING] [必須] ワークフローまたはスキルの手順を実行する前に、計画したすべての手順についてタスク追跡を作成／更新し、各手順の開始時と完了時に同期してください。

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

作業を始める前に、作業を小さなタスクに分割して追跡します。最後のタスクに「AI のミスと教訓を分析する」を追加します。

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

1. 症状ではなく、失敗モード（推論や前提の誤り）を特定します。「間違った enum 値を使った」ではなく、「ソースを読まずに API が存在すると仮定した」とします。
2. 一般性を確認します。この失敗モードは 3 つ以上の状況／コードベースに当てはまりますか？当てはまらない場合は、もう一段階抽象化します。
3. 普遍的なルールとして記述します。プロジェクト固有の名前、パス、クラスを取り除きます。どのコードベースでも役立つ内容にします。
4. 統合します。同じ失敗モードに起因する複数のミスは、1 つの教訓にまとめます。
5. 再発ゲート：「このリマインダーがなければ、今後のセッションで再発するか？」いいえ → $learn は省略します。
6. 自動修正ゲート：「$code-review／$code-simplifier／$security-review／$lint で検出できるか？」はい → 代わりにレビュー用スキルを改善します。
7. 両方のゲートを通過した場合は、ユーザーに $learn の実行を依頼します。 [CRITICAL-THINKING-MINDSET] 批判的思考と段階的思考を適用します。あらゆる主張に追跡可能な証拠を求め、行動する際は確信度を 80% 超とします。 ハルシネーション防止の原則： 推測を事実として提示しないでください。すべての主張に出典を示し、不確実性を率直に認め、出力に誤りがないか自己確認し、独立した情報源と照合し、自分の確信を疑ってください。証拠のない確信が、あらゆるハルシネーションの根本原因です。 AI の注意力の原則（初頭効果・新近効果）： 長いプロンプト／プロトコルでは、最も重要なルールを上部と下部の両方に 3 つずつ配置し、長いコンテキストでも指示への準拠を維持します。 目標主導の実行： まず成功基準を定め、検証できるまで繰り返し、観察可能なチェックに合格した場合にのみ終了します。 テストは意図を検証します： テストは現在の動作をなぞるだけでなく、ビジネスルールや不変条件を保護し、保護対象の意図が崩れたときに失敗する必要があります。

よくある AI のミスを防ぐ（システムの教訓）

• コンテキスト圧縮後はファイルを再読込してください。 編集するには、同じコンテキスト内で事前に Read している必要があります。圧縮によって読込状態は消去されます。編集前に再読込してください。
• 一括置換後は古い用語を grep してください。 AI は検索・置換の完全性を過信します。一括編集後はリポジトリ全体を grep し、ドキュメント／設定／カタログに参照漏れがないか確認してください。
• 削除前に下流の参照を確認してください。 削除の影響は、ドキュメントやコードの陳腐化へ連鎖します。削除前に参照元ファイルを洗い出してください。
• 記憶を失った後、新しく作成する前に既存の状態を確認してください。 圧縮によってこれまでの作業の記憶が消去されます。作業を再開するときは現在の状態を確認し、決してむやみに重複作成しないでください。
• AI 生成コンテンツは実際のコードと照合してください。 AI は API、クラス名、メソッドシグネチャを幻覚することがあります。ドキュメントへの記載や参照の前に、grep して実在を確認してください。
• 編集後は依存関係を最後までたどってください。 定義を変更しても、その下流の利用箇所を見落とすことがあります。依存関係をすべてたどってください。
• 名前を変更するときは、利用側の全ファイル形式を grep してください。 ファイル形式によっては、参照先が見つからなくてもエラーなしで無視されます。コード、テンプレート、設定、生成ファイルを検索してください。
• 正しさを検証するときは、すべてのコードパスをたどってください。 コードが存在することと、実行されることは同じではありません。正常系だけでなく、早期リターン、エラー分岐、条件によるスキップもたどってください。
• ソースが変わったら、正規データを埋め込んでいるドキュメントも更新してください。 派生データ（ワークフロー、スキーマ、設定など）を直接記載しているドキュメントは、気づかないうちに古くなります。ソースと合わせて、該当する埋め込みドキュメントをすべて更新してください。
• コンテキスト復旧後は、サブエージェントの結果を検証してください。 親エージェントが圧縮されている間にバックグラウンドエージェントが完了している場合があります。完了したはずだと信じず、出力を grep して確認してください。
• 対象の全一覧とサブエージェントへの割り当てを照合してください。 カテゴリごとにサブエージェントを並行実行すると、境界上の項目を見落とすことがあります。作業を進める前に、割り当ての和集合を対象一覧と照合してください。
• サブエージェントが引き継ぐ知識は、そのエージェントの .md 定義に書かれた内容だけです。組み込みの Explore ではなく、カスタムエージェント種別を使用してください。 ツールの採用には、権限＋知識＋適用（番号付きワークフロー手順）が必要です。
• サブエージェントの調査結果は最後にまとめてではなく、随時保存してください。 長時間実行されるサブエージェントは、最終書き込み前に打ち切られることがあり、調査結果が失われます。報告ファイルにセクションごとに追記するよう指示してください。
• デバッグ時は修正する前に「どちらの責任か」を確認してください。 呼び出し元（データが誤っている）と呼び出し先（処理が誤っている）をたどり、責任のある層を修正してください。症状が表れる箇所だけを修正してはいけません。
• テスト失敗時は、追跡や編集の前に暫定判定を記録してから調査してください。 次の 5 つの分類をすべて使ってください。SOURCE-WRONG（本番コードが意図に反している）、TEST-WRONG（アサーション／セットアップが古くなっている）、TEST-NOT-OPTIMAL（妥当だが脆弱、または情報量の少ないテスト）、ENVIRONMENT-BLOCKED（外部状態のため判定できない）、AMBIGUOUS（意図や証拠から安全に選べない）。その後、根本原因をたどり、適用される仕様（存在する場合は docs/specs/**）とソースの両方に照らして検証してください。成功を無理に得るために、アサーションを弱めたり、スキップを追加したり、タイムアウトを緩めたり、ソースを変更したりしてはいけません。
• 抽出／リファクタリング後は、削除した名前をすべて grep してください。 主要ファイルの作業完了は、他のファイルもクリーンであることを意味しません。完了を宣言する前に、対象範囲全体で削除したシンボルを一つずつ grep してください。
• 既存の値には意図があると考え、変更したり不具合だと指摘したりする前に、必ず理由を確認してください。 パターンマッチで「誤り」と決めつけると、背景を見落とします。定数／上限／フラグ／しきい値を変更または報告する前に、コメント、git blame、呼び出し元の処理順序（値を正しくする保証は、通常、該当行の直前に実行されるコードにあります）、同じ規約を使っている 2 つ以上の類似した呼び出し箇所を確認してください。理由なしに WHAT（何をするか）だけを記したドキュメントは、根拠が欠けているのではなく、WHY（なぜそうするか）の説明が不足しているということです。検証作業でも、正確な file:line の引用が証明するのは転記が正確であることだけであり、不具合の存在ではありません。
• 最初の出力だけでなく、影響を受けるすべての出力を検証してください。 一つのビルドが成功しても、すべてが成功したとは限りません。複数のスタックにまたがる変更（バックエンド／フロントエンド／テスト／ドキュメント）では、すべての出力を検証してください。
• 近くにあるパターンをコピーする前に、適合性を評価してください。 最も近い例が適合するとは限りません。新しいコンテキストが同じ制約、基底クラス、スコープ、ライフタイムを共有するか確認してください。
• デバッグでは全体を優先し、目についた箇所に飛びつかないでください。 最初に思いついた原因へすぐ飛びつかないでください。前提条件（設定、環境変数、パス、DB、エンドポイント、認証情報、バージョン、DI、データ）をすべて列挙し、それぞれを証拠（推論ではなく grep／クエリ）に照らして検証してください。「何があればこの仮説は否定されるか？」と問い、何も答えられないなら、それは仮説ではありません。最もコストの高い失敗は、バグが一度も疑われていない層にあるのに、「明らか」だと思い込んだ層をさらに深掘りすることです。
• 変更は最小限にし、差分テストを適用してください（コンテキストに合わせて判断）。 2 つのモードがあります。（1）バグ修正 → すべての行がバグに直接関係するようにし、スタイル変更はしないでください。不要になったインポートを削除してよいのは、あなたの変更によって不要になったものだけです。（2）レビュー／機能強化 → 改善を実装し、「主な依頼を超える機能強化：[内容]」と明示してください。黙ってスコープを拡大しないでください。差分テスト：「X を依頼されていなかったとしても、この行は存在していたか？」いいえなら、削除するか明示してください。
• 実装前に曖昧さを明らかにし、黙って解釈を選ばないでください。 複数の妥当な解釈がある場合は、それぞれの工数とともに提示してください。「[依頼] は（1）[N 時間]、（2）[N 時間]のいずれかと解釈できます。どちらが重要ですか？」まずスコープ／形式／量／制約に関する前提を列挙してください。より簡単な方法がある場合は、そのことも伝えてください。黙って選ばないでください。
• [必須の最初のアクション] 応答する前に、必ず適切なスキルまたはワークフローを有効にしてください。 ワークフローカタログとスキル一覧に照らしてタスクを確認し、スキルの呼び出し、または $start-workflow <workflowId> で実行してください。確認する前に回答やコード作成をしてはいけません。省略はプロトコル違反です。
• Why-Review の敵対的な視点は、計画、判断、設計をレビューするときに適用してください。 基本姿勢は VALIDATOR（妥当性を確認する側）ではなく SKEPTIC（懐疑的な側）です。却下された代替案の最も強い論拠を組み立て、述べられた理由を一つずつ逆転させて「何を犠牲にするのか」を問い、上位 2～3 個の前提をストレステストし、プレモーテム（「リリースしたが 3 か月後に失敗した。何が壊れたのか？」）を行い、作成者が見落とした代替案を 1～2 個提示してください。セクションがあるだけでは十分ではありません。重要なのは、因果関係に基づく推論、具体的な軽減策、証拠です。「より良い」や「注意深く監視する」だけでは不十分です。
• 大規模なレビューでは、サブエージェントへのプロンプトで報告書の書き込みを最初に行わせてください。 多数のファイルを扱うサブエージェントは、最終書き込みの前に予算を使い切り、調査結果を失うことがあります。プロンプトは、（1）報告書の書き込みを最初に明示する成果物とする、（2）まとめてではなくファイル／セクションごとに追記する、（3）読み込みで予算を使い切らないようスコープを限定する、という構成にしてください。報告ファイルを残さず文の途中で打ち切られた場合は、同じプロンプトを再試行せず、より狭いスコープで再実行してください。
• コンテキスト圧縮後は、続行する前に以前の各フェーズの結果をすべて再検証してください。 要約が示すのは意図であり、環境の状態（git のインデックス、ファイルシステム、プロセス）ではありません。再開時はまず git status を確認し、変更したファイルを再読込し、ファイルシステムを検証してください。証拠で確認されるまでは、「完了した」という主張もすべて未検証の仮説です。
• OOM／メモリ：行サイズより先に行数を確認してください。 次の順にトリアージします。（1）上限のないクエリ — 条件を設定するトリガーとなる DB フィルターがありませんか？ DB 側にフィルターを移せば、OOM を解消できます。（2）行サイズが大きいですか？ プロジェクションを使えば比例して減らせます。費用対効果では、プロジェクションより行数削減が優先です。
• システムが担う最終結果をアサートし、インフラストラクチャが担う中間状態をアサートしないでください。 非同期処理（キュー／ブローカーへの配信、再試行、バックグラウンドジョブ、キャッシュ、レプリケーション）をテストする場合は、最終的なビジネス／エンティティの状態をアサートしてください。配信の記録、つまり消費／送信ステータス、試行回数、最終エラー、ブローカー、スケジューラー、outbox／inbox テーブル内の行の有無や件数をアサートしてはいけません。この記録は共有インフラストラクチャに存在し、並行して動く任意のプロセス（別のワーカー、2 つ目のレプリカ、残っているローカルコンテナー）から書き込めるうえ、通常は決定的な共有キーが使われます。そのため、こうしたアサーションは気づかないうちにシステムではなく開発者の環境をテストします。単独実行では成功しても、同じブローカー＋データベースをほかの何かが共有した途端に不安定になります。すべてのアサーションで、次の判定の問いを使ってください。「どのプロセスが処理しても、この結果は成り立つか？」いいえなら、代わりに収束後のデータ状態をアサートしてください。系として、プロセスローカルな障害注入やプロセス内テレメトリーを、任意のプロセスが実行する処理のゲートとして使うことはできません。負荷増幅に使ってください（有効化 → 範囲を限定した時間枠 → 無効化 → 収束をアサート）。前提条件として使ってはいけません。
• ドメイン概念を汎用／共有／インフラストラクチャ層に持ち込まないでください。 再利用可能な層（共有ライブラリ、フレームワーク、インフラモジュール）は、利用側に固有のドメイン概念（テナント／顧客／製品 ID、ビジネスエンティティ、機能ルール）を一切参照してはいけません。漏れがコンパイルされ、実行されると、再利用可能なはずの層が一つの利用側と結合していても、レビューで気づかれずに通過してしまいます。共有型からドメイン情報を排除し、サブクラス化／コンポジションを通じて、ドメインフィールド／ロジックを利用側へ移してください。理由：一つの利用側のドメインに結合した層は、もはや再利用可能ではありません。