Skip to content

azure boards markdown bug analysis_ja

Jump to bottom
Kazushi Kamegawa edited this page Oct 5, 2026 · 1 revision

Azure Boards の Markdown による Bug 分析と Wiki 逆リンク

English

概要

azure-devops-boards スキルが、Bug の分析結果（根本原因と修正方針）を Bug フォームに実際に表示されるフィールドに記録し、長文フィールドを HTML へのフォールバック付きで Markdown として書き込み、Azure DevOps Wiki に登録したすべての Work Item からそのページへリンクを張るようにします。

追跡

種別 Issue
親 Issue #79
サブイシュー Issue #80
サブイシュー Issue #81
サブイシュー Issue #82

背景

azure-devops-boards スキルは、AI の分析結果（根本原因、修正方針）を Bug の本文に残さないことがあります。スキルは System.Description に書き込みますが、Agile/Scrum/CMMI の Bug フォームはこのフィールドを表示しません（Bug の本文は Repro Steps、Microsoft.VSTS.TCM.ReproSteps です）。また、Azure Boards では複数行フィールドごとに Markdown で保存できるようになったにもかかわらず（フィールドを切り替えない限り、リッチテキスト/HTML が既定で優先されます）、スキルはすべての長文の値を HTML に変換しています。さらに、Azure DevOps Wiki に登録した Work Item には、そのページへ戻るリンクがありません。

決定事項

項目 決定
Bug 本文のフィールド Repro Steps（Microsoft.VSTS.TCM.ReproSteps）
Wiki への逆リンク 本文の ## Wiki セクションと Hyperlink リレーションの両方

設計

  1. 長文フィールドの形式（Markdown 優先）: Markdown のソースを書き込み、同じ JSON Patch に {"op":"add","path":"/multilineFieldsFormat/<FieldRef>","value":"Markdown"} を追加します（Azure DevOps MCP では create / update_batch で format に Markdown を指定します）。MCP サーバーと同様に < と > を &lt; / &gt; にエンコードします。読み戻しで multilineFieldsFormat.<FieldRef> が Markdown（大文字小文字を区別しない）であることを確認します。サーバーが拒否または無視した場合（例: Azure DevOps Server）は、既存の Markdown から HTML への変換にフォールバックします。HTML 形式のフィールドに生の Markdown を残してはいけません。HTML で保存されているフィールドを更新するときは、形式を切り替えてフィールド全体を書き直します。
  2. Bug 分析の本文: Repro Steps には、## Repro steps、## Expected vs actual、## Root cause、## Fix approach をこの順に置き、Wiki 登録後は ## Wiki も置きます。セクションを省略せず「Not yet analyzed」と書きます。分析結果または承認済みの修正方針が変わったときは書き直し、読み戻しでセクションを確認します。
  3. あらゆる Work Item 種別（Feature 相当、Bug、Task、その他）の Wiki 逆リンク: Wiki スキルの読み戻しからページの remoteUrl を取得し、本文フィールドの ## Wiki セクションを追加または置換し、Hyperlink リレーションを追加し（重複はスキップ）、読み戻しで確認します。
  4. Work Item エージェント、Wiki スキルの引き継ぎ（remoteUrl を返す）、.github のミラー、CHANGELOG（英語/日本語）を更新し、azure-devops-toolkit を 0.3.1 に上げます。

例に出てくる組織とプロジェクトの参照には {org}/{project} のプレースホルダーを使います。

実装フェーズ

  1. Boards の SKILL.md と Windows ネイティブのリファレンス（PowerShell 7 と Linux/macOS の例）。
  2. Work Item エージェントと Wiki スキルの引き継ぎ。
  3. .github のミラー、CHANGELOG、バージョン更新、マーケットプレイスの検証。

検証

  • multilineFieldsFormat のパスを azure-devops-mcp のソースと照合します。
  • PowerShell の例を静的に構文解析します。
  • scripts/validate_marketplaces.py を実行します。
  • 既存の Wiki バリデーターのテストを実行します。
  • .github のミラーとプラグイン側のコピーの差分を確認します。
  • ファイル間の一貫性をレビューします。
  • テスト用の組織が使える場合は、実環境で確認します。

Clone this wiki locally