[Phase 6] Polish & Cross-Cutting – ログ / エラーハンドリング / パフォーマンス / ドキュメント仕上げ

[shinyay]

---

全てで 6つのフェーズに分割して作業を実施

• Pahse 1: プロジェクトスキャフォールド
• Pahse 2: 基盤実装（config / mcp_client / prompts / agent / cli / main）
• Pahse 3: MVP – User Story 1 (リソースグループ一覧)
• Pahse 4: User Story 2 – ストレージアカウント一覧
• Pahse 5: User Story 3 – Log Analytics エラー要約
• Pahse 6: Polish & Cross-Cutting

---

概要

User Story 1〜3 (リソースグループ一覧 / ストレージアカウント一覧 / Log Analytics エラー要約) が一通り動く状態を前提に、
この Issue では以下の「仕上げ & 横断的な品質向上」を行います:

• Quickstart の充実と、実装とドキュメントの同期
• ログとエラーハンドリングの整理（ユーザー向けメッセージの統一）
• 権限不足やタイムアウトなどのエッジケーステストの追加
• 代表的な問い合わせに対する簡易パフォーマンステスト
• プロンプト・システムインストラクションの見直し（安全性・一貫性）
• Quickstart ベースのエンドツーエンド検証とドキュメント反映

目的:
本エージェントを「人に渡せる品質」に持っていき、AI Toolkit や Copilot coding agent から評価・トレースしやすい状態にすることです。

---

コンテキスト

• プロダクト仕様: specs/001-azure-resource-guide-agent/spec.md
• 仕様チェックリスト: specs/001-azure-resource-guide-agent/checklists/requirements.md
• 実装プラン: specs/001-azure-resource-guide-agent/plan.md
• データモデル: specs/001-azure-resource-guide-agent/data-model.md
• Quickstart: specs/001-azure-resource-guide-agent/quickstart.md
• タスク一覧: specs/001-azure-resource-guide-agent/tasks.md

Phase 6 は、tasks.md の Phase 6: Polish & Cross-Cutting Concerns に対応します（T033〜T038）。

---

スコープ（対応する tasks）

この Issue の対象タスクは以下です（Phase 6 のみ）:

• T033 [P] Add detailed usage and examples to specs/001-azure-resource-guide-agent/quickstart.md
• T034 Improve logging and error reporting across src/azure_mcp_agent/agent.py and src/azure_mcp_agent/cli.py
• T035 [P] Add additional edge-case tests for permission errors and timeouts in tests/azure_mcp_agent/test_agent_basic.py
• T036 [P] Add basic performance checks for typical queries in tests/azure_mcp_agent/test_log_analytics.py
• T037 Refine prompts and safety constraints in src/azure_mcp_agent/prompts.py based on early feedback
• T038 Run end-to-end validation using specs/001-azure-resource-guide-agent/quickstart.md and adjust docs as needed

前提条件

• Phase 1〜5（T001〜T032）が完了済み、または少なくとも User Story 1〜3 が動く状態になっていること。
• 既に pytest ベースのテストスイートが存在し、CI で実行できること。

スコープ外

• 新しいユーザーストーリー/機能の追加
• Azure MCP Server 側のツール追加・変更（クライアント側の扱いに限定）
• 本番向けの SLO/SLA 定義や監視基盤（Application Insights 等）との統合

---

やってほしい具体的なこと

1. Quickstart の充実 (T033)

ファイル: specs/001-azure-resource-guide-agent/quickstart.md

やること

• 現状の Quickstart を、実際の CLI 挙動に合わせて更新する:
  • セットアップ手順（Python venv, pip install -e ., 環境変数など）
  • Azure MCP Server の起動例 (npx -y @azure/mcp@latest server start)
  • User Story 1〜3 それぞれの「サンプル問い合わせと期待される応答」の例
    • 例:
      • このサブスクリプションのリソースグループ一覧を出して
      • <RG名> のストレージアカウントを一覧して
      • 直近 1 時間のエラーを Log Analytics で確認して
• US1〜3 それぞれについて、少なくとも 1 つの「実際の出力例」（ダミーの RG 名 / ストレージ名 / エラー内容で OK）を載せる。
• README がある場合は、Quickstart へのリンクを追記し、「まずこれを読めば全体像が分かる」状態にする。

---

2. ログ & エラーハンドリングの改善 (T034)

ファイル: src/azure_mcp_agent/agent.py, src/azure_mcp_agent/cli.py

目的

• ユーザーに見せるメッセージは常に日本語で分かりやすく、
  内部では Python の logging モジュールを使って診断しやすいログを出す。

やること

• logging を使ったロガーを定義し、最低限以下をログ出力:
  • MCP ツール呼び出しの開始/終了（どのツールを使ったか、成功/失敗）
  • 重要なエラー（権限不足、タイムアウト、Azure 側の一時障害など）
• ただしログには以下を含めない:
  • 秘密情報（トークン、接続文字列、個人情報など）
  • フルのスタックトレース（必要に応じて DEBUG レベルでのみ出す）
• ユーザー向けエラーメッセージは:
  • 日本語で、「何が起きたか」「何をすればよいか」が分かる文章に統一
  • 例: 「サブスクリプションにアクセスする権限が不足しているようです。管理者にロールを確認してもらってください。」
• CLI 側では、致命的な例外がそのままトレースバックとしてユーザーに流れないようにし、
  一箇所でキャッチして日本語メッセージを表示する。

---

3. 権限エラー / タイムアウトなどの追加テスト (T035)

ファイル: tests/azure_mcp_agent/test_agent_basic.py

目的

• 仕様で挙げているエッジケース（権限不足 / リソース未存在 / Azure 側の一時障害など）を
  pytest で自動検証できるようにする。

やること

• MCP クライアントをモックして、代表的な失敗パターンを再現:
  • 権限不足（例外 or エラーコード）
  • ネットワークタイムアウト
  • リソース/リソースグループ未存在
• 各ユーザーストーリー（US1〜US3）向けに、少なくとも 1 ケースずつ「エラー系テスト」を追加:
  • Agent レベルの戻り値が、仕様通りの日本語メッセージになっていることを確認。
• テスト名や docstring には、どのエッジケースを検証しているかを明記する。

---

4. 基本的なパフォーマンステストの追加 (T036)

ファイル: tests/azure_mcp_agent/test_log_analytics.py（必要なら追加ファイルでも可）

目的

• 「典型的な問い合わせ」で極端な性能劣化が起きていないことを、
  簡易的なパフォーマンステストで検知できるようにする。

やること

• 対象:
  • US1: リソースグループ一覧
  • US2: ストレージアカウント一覧
  • US3: Log Analytics エラー要約（モックベース）
• 方針:
  • 実 Azure ではなく、MCP クライアントをモックして「大量のダミー結果」を返すことで、
    エージェント側の整形・要約ロジックだけを計測する。
  • 必要に応じて pytest-benchmark 等のプラグインを使い、「一定時間内に終わること」を検証してもよい。
• 最低限:
  • 上記 3 ケースについて、「N 回繰り返し実行してもタイムアウトしない / 明らかに遅くならない」程度のチェックを行う。

---

5. プロンプト / システムインストラクションの見直し (T037)

ファイル: src/azure_mcp_agent/prompts.py

目的

• Agent Builder で定義したインストラクションを整理し、
  全ユーザーストーリーで一貫した動作と安全性（読み取り専用 / 日本語応答）を確保する。

やること

• システムプロンプトに、以下を明文化:
  • すべての Azure 操作は読み取り専用であること（CUD は行わない）
  • 応答は日本語で行い、リソース名や ID は原文表記を維持すること
  • Azure MCP Server のツールを積極的に利用し、「最新の状態」を確認すること
  • リソース名やワークスペース名があいまいな場合は、ユーザーに確認・絞り込みを行うこと
  • Log Analytics エラー要約では、3〜5 ステップのトラブルシュートガイドを返すこと
• ツール説明文（tool description）にも上記方針を反映し、
  LLM にとって「どのツールをいつ使うべきか」が分かりやすい状態にする。
• 不要になったプロンプト断片や重複ルールがあれば整理・削除する。

---

6. Quickstart を使った E2E 検証 & ドキュメント反映 (T038)

ファイル: specs/001-azure-resource-guide-agent/quickstart.md 他

目的

• Quickstart に書かれた手順を実際に上から順に実行し、
  エンドツーエンドの動作を確認しつつ、必要な修正をドキュメントに反映する。

やること

• ローカル環境で以下を実施:
  1. ブランチ 001-azure-resource-guide-agent をチェックアウト
  2. venv 作成と依存インストール
  3. Azure MCP Server 起動
  4. python -m azure_mcp_agent または python src/azure_mcp_agent/main.py を実行
  5. Quickstart に書かれた 3 つの問い合わせ（US1〜3）を実行
• 上記のどこかで詰まる / 手順が足りない / 挙動が Quickstart 記載と違う場合は、
  • 可能であればコード側を修正
  • それでも埋めきれない部分は Quickstart に注意書きとして追記
• 将来的に AI Toolkit の評価・トレースからも使えるよう、
  「代表的な E2E シナリオ」を Quickstart に明示的に列挙しておく。

---

受け入れ条件 (Acceptance Criteria)

1. Quickstart が実装と同期している

   • Quickstart の手順通りに実行すれば、US1〜3 の代表的な問い合わせがすべて成功する。
   • 少なくとも 1 パターンずつ、US1〜3 の「問い合わせ例＋出力例」が Quickstart に記載されている。

2. ログ & エラーハンドリングが整理されている

   • agent.py / cli.py で Python の logging を用いたログ出力が行われている。
   • ユーザーに見えるエラーはすべて日本語で、仕様に沿ったメッセージになっている（スタックトレースは表示されない）。

3. エッジケーステストが追加されている

   • tests/azure_mcp_agent/test_agent_basic.py に、権限不足 / タイムアウト / リソース未存在などのテストが追加されている。
   • それらのテストが CI で緑になっている。

4. 基本的なパフォーマンステストが存在する

   • tests/azure_mcp_agent/test_log_analytics.py などに、「典型的な問い合わせに対する簡易パフォーマンステスト」が追加されている。
   • 外部サービスへのネットワーク依存を避け、モックを使ったロジック単位の計測になっている。

5. プロンプトが仕様と一貫している

   • prompts.py のシステムインストラクションとツール定義に、読み取り専用・日本語応答・あいまい入力の扱い・トラブルシュートガイドなどの仕様が反映されている。
   • US1〜3 のいずれにおいても、プロンプトの方針と実際の挙動が乖離していない。

6. E2E 検証が完了している

   • Quickstart のシナリオを使ったエンドツーエンド検証（US1〜3）が少なくとも 1 回は行われ、その結果が Quickstart / コメント等に反映されている。
   • 全テスト (pytest) が成功し、追加したパフォーマンス・エッジケーステストも含めて緑の状態になっている。

---

Copilot coding agent への追加指示（任意）

この Issue を @copilot にアサインする場合、以下のようなコメントを追記するとスムーズです:

• Phase 1〜5 までのコードとテストを前提に、tasks.md の Phase 6 (T033〜T038) を完了してください。
• まず Quickstart を実際の挙動に合わせて更新し (T033)、その後にロギング・テスト・プロンプト・E2E 検証 (T034〜T038) を行ってください。
• ログとエラーメッセージは「ユーザーフレンドリーな日本語」で統一し、スタックトレースや秘密情報は出さないようにしてください。
• パフォーマンステストやエッジケーステストでは、外部サービスへの依存を避けるために MCP クライアントをモックしてください。
• 最後に pytest と Quickstart に書かれた E2E シナリオを実行し、この Issue の Acceptance Criteria をすべて満たしていることを確認してください。