256 lines
10 KiB
Markdown
256 lines
10 KiB
Markdown
# アドバイザリレポートの作成 - 前提を疑う
|
||
|
||
## コアコンセプト
|
||
立場を変えることで、2つの視点から支援を提供する：
|
||
1. **作業プロセス**：無意識の前提を発見し、作業の問題点を客観的に見つける
|
||
2. **技術的課題**：複雑な問題を構造的に分析し、解決策を評価する
|
||
|
||
## 実行方法
|
||
- `/advisory` - 基本的な前提チェック
|
||
- `/advisory deep` - 詳細な論理検証を含む
|
||
|
||
---
|
||
|
||
## 実行指示
|
||
|
||
### 1. 立場と目的の転換
|
||
作業者からレビュアー/監査役へ立場を変更する。
|
||
「作業を進める」から「問題を発見する」へ目的を転換する。
|
||
優先度を速さから正確性・完全性へシフトする。
|
||
|
||
**既存TODO管理：**
|
||
現在のTODOリストを以下の形式で記録してから、アドバイザリー用の新しいTODOリストを作成する：
|
||
```
|
||
【待避したTODO】
|
||
- [タスク1]: [状態]
|
||
- [タスク2]: [状態]
|
||
```
|
||
（ステップ12で復元時に参照）
|
||
|
||
### 2. 原則の確認と動作モードの理解
|
||
FOUNDATION_MODEが有効でなければ有効にする。
|
||
作業の検証だけでなく、アドバイザリ自身もこの原則に従う。
|
||
mode_listツールで利用可能なモードを確認し、mode_statusとmode_showで現在アクティブなモードを確認する（アドバイザリーは従わなくてよい）。
|
||
|
||
### 3. コミュニケーションの事実確認
|
||
ユーザーが実際に言ったことを原文のまま確認する。
|
||
アシスタントがどう返答したか、実際の応答を確認する。
|
||
やり取りの時系列を追跡し、指示の変化を記録する。
|
||
質問に対して回答したか、スルーした箇所はないか確認する。
|
||
|
||
### 4. 認識のズレを発見
|
||
ユーザーの本当の意図は何だったか分析する。
|
||
アシスタントはそれをどう理解したか検証する。
|
||
どこで・なぜ認識のズレが生じたか特定する。
|
||
「噛み合っていない」箇所を明確に発見する。
|
||
|
||
### 5. 状況まとめ（中間チェックポイント）
|
||
状況のまとめを文章化する。
|
||
まとめた文章を確認し、理解できていないこと、追加で調査すべき観点を発見する。
|
||
|
||
**進捗通知：**
|
||
> 【中間チェックポイント1 - 状況確認】
|
||
> ✅ 完了した調査：ステップ1-4
|
||
> 📝 状況まとめ：[簡潔な要約]
|
||
> 🔍 追加調査項目：[ある場合は件数と概要]
|
||
>
|
||
> → 判定：[次のステップ6へ進みます/ステップ3に戻って再調査します]
|
||
|
||
判定に基づき、次のステップに進むか、ステップ3に戻って再調査する。
|
||
|
||
### 6. 独立した視点で資料を探して読み込む
|
||
ドキュメントの一覧を作成。
|
||
作業を行う上で重要な資料が存在しないか、十分に参照されているかを調べる。往々にして問題はコンテキストの不足から発生するため、「探す」ことは重要な作業である。
|
||
作業者が明文化されていない情報に基づいて作業していないかを検証する。
|
||
批判的な視点で読み、何が欠けているか、矛盾はないかを探す。
|
||
|
||
### 7. 現在のコンテキストを外部視点で調査
|
||
作業手順は妥当か、目的に対して適切か確認する。
|
||
TODOリストに書かれていない重要事項を探す。
|
||
作業者が見落としている全体像を把握する。
|
||
本来の目的から逸れていないか検証する。
|
||
|
||
### 8. 検証まとめ（中間チェックポイント）
|
||
検証のまとめを文章化する。
|
||
作成した文章について批判的に検討し、論理の飛躍、情報の不足の可能性を洗い出す。
|
||
|
||
**進捗通知：**
|
||
> 【中間チェックポイント2 - 検証結果】
|
||
> ✅ 完了した調査：ステップ6-7
|
||
> 📊 検証結果：[良好/問題あり - 簡潔な要約]
|
||
> ⚠️ 論理の飛躍・情報不足：[ある場合は件数と概要]
|
||
>
|
||
> → 判定：[次のステップへ進みます/ステップ6に戻って再調査します]
|
||
|
||
判定に基づき、次のステップに進むか、ステップ6に戻って再調査する。
|
||
|
||
### 9. 論理的検証（deepモード時のみ）
|
||
`/advisory deep` 実行時は、技術的な誤解・理解不足・ミスを体系的に発見するため、Toulminモデルによる論理検証を実施する。詳細は「deepモード詳細」セクションを参照。
|
||
最後に「状況まとめ」「検証まとめ」自体を批判的に検証する。
|
||
|
||
**進捗通知（deepモード時）：**
|
||
> 【論理検証完了】
|
||
> 🔬 Toulminモデル8項目：[合格数/8]
|
||
> 📝 メタレベル検証：[まとめ自体の問題点]
|
||
>
|
||
> → 判定：[次のステップへ進みます/該当ステップに戻って再実行します]
|
||
|
||
### 9.5. 技術的課題の分析（deepモード時）
|
||
技術的な課題が存在する場合、構造的に分析して解決策を評価する：
|
||
|
||
**課題の特定**
|
||
- 何を実現しようとしているか（目標）
|
||
- どこで詰まっているか（障壁）
|
||
- 既知の制約・前提条件は何か
|
||
- エラーメッセージや症状の記録
|
||
|
||
**5 Whysによる根本原因分析**
|
||
1. なぜこの課題が発生しているか？
|
||
2. それはなぜか？（原因の原因）
|
||
3. さらになぜか？（より深い原因）
|
||
4. さらになぜか？（さらに深く）
|
||
5. 根本原因は何か？
|
||
|
||
**課題の分類**
|
||
- 仕様の誤解・理解不足
|
||
- 実装のミス・バグ
|
||
- 環境・設定の問題
|
||
- 外部依存・ライブラリの問題
|
||
- アーキテクチャ・設計の課題
|
||
|
||
**解決策の評価（複数案がある場合）**
|
||
各解決アプローチについて：
|
||
- アプローチの概要
|
||
- メリット（利点・強み）
|
||
- デメリット（欠点・弱み）
|
||
- リスク（潜在的な問題）
|
||
- 実装工数・複雑度
|
||
|
||
**推奨アプローチの選定**
|
||
- 最も適切な解決策とその理由
|
||
- トレードオフの明示
|
||
- 代替案の提示
|
||
|
||
### 10. レポート作成
|
||
> 【アドバイザリーからの報告書】
|
||
>
|
||
> ## 作業プロセスの評価
|
||
> 検出された問題：
|
||
> - 原則違反
|
||
> - ユーザー意図との乖離
|
||
> - 動作モードの不適切・未適用（mode_status/mode_showで確認）
|
||
> - 未読ファイル
|
||
> - 疑わしい実装
|
||
>
|
||
> 推奨事項：
|
||
> [具体的な改善提案]
|
||
>
|
||
> ## 技術的課題の分析（deepモード時、課題がある場合）
|
||
> **根本原因**：
|
||
> [5 Whysの結果]
|
||
>
|
||
> **課題の分類**：
|
||
> [仕様誤解/実装ミス/環境問題/設計課題]
|
||
>
|
||
> **推奨する解決策**：
|
||
> [具体的なアプローチとその理由]
|
||
>
|
||
> **トレードオフと代替案**：
|
||
> [考慮すべきリスクと他の選択肢]
|
||
|
||
### 11. アドバイザリとしての作業終了
|
||
レポートを提出し、作業者モードに戻る。
|
||
|
||
### 12. 作業者として対応
|
||
レポートを読んで問題を認識する。
|
||
技術的な課題があれば詳細検証の依頼を提案する。
|
||
発見された問題についてユーザーに報告する。
|
||
ステップ1で待避した元のTODOリストを必要に応じて復元する。
|
||
作業再開の許可をユーザーから得る。
|
||
|
||
---
|
||
|
||
## 調査項目詳細
|
||
|
||
### 作業手順の妥当性
|
||
- 目的の理解 → 調査 → 実装の順序で進めているか
|
||
- 必要なドキュメントを読んでから作業しているか
|
||
- テスト → 実装 → ドキュメント更新の流れか
|
||
- ユーザーの確認を待ってから進めているか
|
||
|
||
### 原則との整合性
|
||
- FOUNDATION_MODEの5つの原則に違反していないか
|
||
- 特に「効率とは速さではなく確実性」を理解しているか
|
||
- 「結果と過程」の原則に従っているか
|
||
|
||
### 知識と理解の検証
|
||
- 仕様の根拠があるか
|
||
- 名前からの推測で進めていないか
|
||
- ハルシネーションしていないか
|
||
- 公式ドキュメントを読んだか
|
||
|
||
---
|
||
|
||
## よくあるミスパターン
|
||
|
||
### 品質の妥協
|
||
- `any`型：正しい型定義を避けている
|
||
- `it.skip`：テストを無効化している
|
||
- `--no-verify`：検証を回避している
|
||
- lint警告の無視：「警告だから」という理由
|
||
|
||
### プロセスの問題
|
||
- ドキュメント未読での実装
|
||
- エラーメッセージを読まない対処
|
||
- 「後で直す」「たぶん動く」という前提
|
||
- 完了の勝手な宣言
|
||
|
||
### コミュニケーションの問題
|
||
- ユーザーの質問に答えていない
|
||
- 確認を待たずに進めている
|
||
- 意図を勝手に解釈している
|
||
- エラーや問題を報告していない
|
||
- 適切な動作モードが有効になっていない（mode_statusで確認）
|
||
- モードの実行仕様を適用していない（mode_showで確認）
|
||
|
||
---
|
||
|
||
## deepモード詳細
|
||
|
||
`/advisory deep` 実行時、または詳しい調査を求められた場合は、ステップ9で以下の構造的検証を実施：
|
||
|
||
### Toulminモデルによる8つの質問
|
||
|
||
技術的な誤解、理解不足、ミスを体系的に発見するための論理検証：
|
||
|
||
1. **推論は明確な前提から始まっているか？**
|
||
前提を明示的に述べているか
|
||
|
||
2. **前提は証拠や事実で裏付けられているか？**
|
||
ドキュメント、テスト結果、実行結果など
|
||
|
||
3. **前提と結論の間に論理的なつながりがあるか？**
|
||
飛躍していないか
|
||
|
||
4. **その論理的つながりは妥当か？**
|
||
他の解釈の可能性は？
|
||
|
||
5. **推論は論理的誤謬を避けているか？**
|
||
早まった一般化、誤った二分法など
|
||
|
||
6. **結論は前提から論理的に導かれているか？**
|
||
前提から必然的に導かれるか
|
||
|
||
7. **推論は既存の知識や原則と整合しているか？**
|
||
ドキュメントや技術的ベストプラクティスと矛盾しないか
|
||
|
||
8. **推論の結論は妥当で合理的か？**
|
||
現実的で実装可能か
|
||
|
||
---
|
||
|
||
## アドバイザリーの心構え
|
||
|
||
アドバイザリーは作業者の敵ではなく、より良い成果のための協力者である。
|
||
批判は建設的であるべきで、問題の指摘だけでなく改善策も提示する。良い手順について評価することも重要である。
|
||
最終的な目的はユーザーの満足と、高品質な成果物の実現である。 |