ワークフロー 診断
診断が先。修正はその後。
最初に読む
コードを変更する前に、最もシグナルの高いコンテキストを読む：
.ai-workflow/GOAL.md（存在する場合）.ai-workflow/PLAN.md（存在する場合）.ai-workflow/ACCEPTANCE.md（存在する場合）.ai-workflow/IMPLEMENTATION_LOG.md（存在する場合）AGENTS.mdCONTEXT.md（存在する場合）- 関連ドキュメント、ADR、アーキテクチャ契約
- 具体的な障害コードパス、テスト、ログ、またはランタイムの証拠
中核的な振る舞い
- 修正を提案する前に、安定したフィードバックループを構築する。
- 推測よりも証拠を優先する。
- 最初に思いついた筋書きを追うのではなく、仮説をランク付けする。
- 診断と大規模な日和見リファクタリングを分離する。
- 根本原因が明らかになったら、明示的な証拠とともに計画立案または実装に引き継ぐ。
ワークフロー
1. 障害を定義する
以下を書き留める：
- 何が失敗しているか
- 期待される動作
- 実際の動作
- 障害が決定的か、不安定か、データ依存か、環境依存か
- フィードバックを観測できる最小の範囲
2. フィードバックループを確立する
以下を優先する：
- 失敗する自動テスト
- 再現可能なコマンド
- 狭いローカルシナリオ
- ターゲットを絞ったログまたはメトリックトレース
安定したループがまだ不可能な場合は、その旨を明示的に述べ、利用可能な最善の代理証拠を記録する。
3. 仮説をランク付けする
最も可能性の高い原因を順にリストアップする。
各仮説は以下を結びつけること：
- 症状
- 疑われるレイヤーまたはコンポーネント
- それを確認または反証する証拠
4. 検査と計装
仮説を区別するために必要な最小限の計装を使用する：
- ターゲットを絞ったログ
- アサーション
- 一時的なプローブ
- テストの調整
- 状態のスナップショット
コードが醜いという理由だけで、すぐにアーキテクチャを書き換えない。
5. 診断結果を記録する
アクティブなワークフロータスクを実行中の場合、.ai-workflow/IMPLEMENTATION_LOG.md を診断先行パスで更新する。以下を含める：
- フィードバックループ
- 検討した仮説
- 収集した証拠
- 確認または却下された原因
- 次の修正の焦点
アクティブな .ai-workflow タスクがない場合は、応答で診断結果を提供し、実装前に作成または更新することを推奨する。
6. クリーンに引き継ぐ
修正が必要な場合：
- 修復にスコープのある実装計画が必要な場合は
workflow-plan-acceptanceを使用 - アクティブなタスクにすでに承認された計画がある場合は
workflow-implementを使用
バックエンド固有のルール
バックエンドコードが関係する場合、アーキテクチャ境界に対して仮説をテストする：
- コントローラー
- アプリケーション/サービス
- オーケストレーター/ドメインサービス
- リポジトリ
- 永続化
- インフラストラクチャアダプター/プロバイダー/バックグラウンド/ストリーミング
バグが実際に以下によって引き起こされているかどうかを明示的に確認する：
- 責任の混在
- サービスロジックへのHTTP懸念の漏洩
- リポジトリが所有するビジネスロジック
- エンティティ/DTO/ドメインモデルの混乱
- 一元化された例外処理やバリデーションハンドリングの欠如
- トレーサビリティや監査ディメンションの欠如
最終応答フォーマット
最後に、以下のトップレベルセクションを厳密に含む応答を日本語で返す：
## ワークフロー結果
- スキル: `workflow-diagnose`
- ステータス: `completed`
- 成果物: `IMPLEMENTATION_LOG.md` または診断結論
## 診断サマリー
- 問題現象: ...
- フィードバックループ: ...
- 主要仮説: ...
- 確認済み原因: ...
- 除外項目: ...
## 次のステップ
- ...