devops-requirements

DevOps 要件の抽出

Azure DevOps の作業項目から実行可能な要件を抽出し、構造化された要件概要にまとめます。

入力／出力

• 入力： 作業項目 ID または Azure DevOps の URL
• 出力： 要件概要（Markdown — コンテキスト内または成果物ディレクトリに保存）

使用するタイミング

このスキルは、DevOps の作業項目から構造化された情報を抽出する必要がある場合に使用します。

• 作業項目の説明、設計フィールド、受け入れ条件を取得する
• 親子関係を確認し、添付ファイルをダウンロードする
• 作業項目の内容から要件概要をまとめる

このスキルは情報を抽出して構造化するものであり、レポート、データソース、その他の成果物は作成しません。作業項目から何かを作成する場合は、適切な作成スキルを入口として使用してください。作成スキルで作業項目のデータが必要になった際に、このスキルが呼び出されます。

ステップ 1：作業項目を取得する

dxs devops workitem <ID> --full --expand All

--full は長いフィールドが切り詰められるのを防ぎます。--expand All は関係（親、子、添付ファイル）を含めます。

抽出する主なフィールド：

フィールド	内容
title	レポート名と目的
description	概要レベルの要件。期待される出力のスクリーンショットが埋め込まれていることもあります
design	詳細な仕様 — SQL クエリ、列リスト、ビジネスルール。フィールド／データ要件の最も豊富な情報源であることがよくあります
relations.parent	プロジェクト全体の背景情報（背景を把握する必要があれば取得）
relations.children	実装サブタスク — 追加の仕様が含まれている場合があります
relations.attachments	既存のレポート、出力サンプルの PDF、BRD
tags	スプリント／優先度の背景情報

description と design のフィールドは、HTML から Markdown に自動変換されます。長い design フィールドでは、SQL の SELECT 文と列リストを探してください。これらは、スキーマの検出に必要な OData フィールドに直接対応します。

ステップ 2：関係を確認する

作業項目の関係をユーザーに提示します。

This work item has:
- Parent: #218666
- Children: #218813
- Attachments: 4 files (ValleyWarehouseReceiptInvoice.rdlx-json, Order 96269-20250041 - Receiving report.pdf, ...)

Would you like me to fetch any of the child items for additional context?

選択した子項目をまとめて取得するには、次を実行します。

dxs devops workitems <ID1>,<ID2> --description --discussions

--description は説明全体を含め、--discussions はコメント／履歴を含めます。1 リクエストにつき最大 200 項目です。

子項目すべてを自動的にたどらないでください。どの項目が関連するか、ユーザーに確認してください。「Wavelength Component」タイプの子項目には実装の詳細が含まれていることがよくありますが、「Bug」や「Task」タイプの子項目はレポート設計に関係しない場合があります。

アドホッククエリ：dxs devops wiql（dxs ≥ 0.4.18）

必要な作業項目が、すでに把握している ID からたどれない場合 — 「このエリアパス内の Active 項目すべて」、「自分に割り当てられている項目」、「#218666 配下の階層全体」など — ID を推測したり devops search でページをたどったりせず、WIQL を直接実行します。

# Flat: one row per work item. Columns named in SELECT are fetched for each match.
dxs devops wiql "SELECT [System.Id],[System.Title],[System.State] FROM WorkItems \
  WHERE [System.State] = 'Active' ORDER BY [System.ChangedDate] DESC" --limit 25

# Tree / one-hop: one row per source→target link, target fields merged in.
dxs devops wiql "SELECT [System.Id],[System.Title] FROM WorkItemLinks \
  WHERE [Source].[System.Id] = 218666 \
    AND [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward' \
  MODE (Recursive)" --project FootPrint

-Q/--query-file は長いクエリをファイルから読み込みます。--ids-only は、dxs devops workitems に渡す ID だけが必要な場合にフィールドの取得を省略します。metadata.total_count（クエリに一致した件数）と metadata.count（--limit 適用後に返された件数。デフォルトは 200）を比較し、truncated を確認してください — 上限に達した結果は全件ではありません。また、返された項目についても「どの項目が関連するか、ユーザーに確認する」という同じルールが適用されます。

ステップ 3：ユーザーと対象範囲を確認する

添付ファイルのダウンロードや要件概要の作成を始める前に、何を重視するかをユーザーに確認してください。 作業項目には、時間の経過とともに添付ファイル、コメント、設計メモが蓄積されることがよくあります。その中には、古くなったもの、誤って添付されたもの、別のレポート用のものが含まれている場合があります。

概要を提示して、次のように確認します。

This work item has:
- Description: [1-sentence summary]
- Design field: [1-sentence summary — e.g., "SQL views for 3 datasets"]
- Attachments: [list filenames]
- Children: [list if any]

Which of these should I focus on for the report requirements?
Are any of the attachments not relevant to this report?

これが重要な理由： 作業項目には、関連はあっても別のレポート用の添付ファイル、現在の要件と一致しない出力サンプルの PDF、または後から置き換えられた設計メモが含まれている場合があります。レイアウトの参考として誤った添付ファイルを使うと、設計全体が誤った方向に進む可能性があります。添付ファイルを正式な情報源として扱う前に、必ずユーザーに確認してください。

ステップ 4：添付ファイルのダウンロード

添付ファイルを一覧表示します：

dxs devops attachments <ID>

インデックス（より高速）またはファイル名でダウンロードします：

dxs devops attachments <ID> --download 1 --out <artifact_dir>/requirements/report.rdlx-json
dxs devops attachments <ID> --download "Valley Cold HC BRD.pdf" --out <artifact_dir>/requirements/brd.pdf

ダウンロードする添付ファイル（ユーザーが関連性を確認した後）：

拡張子	操作	理由
.rdlx-json	ダウンロードして読み込む	既存のレポートです。レイアウト、DataSets、フィールドのマッピングを抽出します
.rdl	ダウンロードして読み込む	SSRS ソースです。移行に必要な SQL クエリとフィールドのマッピングを抽出します
.pdf	ダウンロードのみ	現在のレポートと一致するとは限りません。レイアウトの参照として使用する前にユーザーに確認してください
.docx、.xlsx	BRD／仕様書の場合はダウンロード	詳細なフィールド一覧やビジネスルールが含まれている可能性があります
.png、.jpg	スキップ	通常、説明内ですでに確認できるスクリーンショットが埋め込まれています

ダウンロードした .rdlx-json ファイルの場合は、dxs report inspect を使って構造をすばやく把握します：

dxs report inspect <artifact_dir>/requirements/report.rdlx-json

.rdl ファイル（SSRS XML）の場合は、SQL を含む <CommandText> 要素を検索します。SELECT の列と FROM／JOIN のテーブルは、OData のエンティティとフィールドに対応します。

PDF の読み込みに失敗した場合（例：poppler が見つからない場合）：要件ブリーフにファイルを「ダウンロード済みだが読み取り不可」と記載し、作業項目の description フィールドと design フィールドをもとに進めます。通常、これらのフィールドに最も実用的な情報が含まれています。サンプル出力の .pdf については、代替手段として、期待するレイアウトを口頭で説明するようユーザーに依頼してください。それでも PDF は必ずアーティファクトディレクトリにダウンロードしてください。ユーザーが手動で確認できます。

ステップ 5：要件ブリーフの作成

作業項目のデータと添付ファイルを収集した後、要件ブリーフを作成します。これは下流のスキル（例：schema-explorer、datasource-creator、report-creator）に渡されます。

テンプレート：

## Requirements Brief

**Report:** [title from work item]
**Purpose:** [1-2 sentence summary from description]
**Work Item:** #[ID] ([state])

### Data Requirements
- **Primary entity:** [derived from SQL FROM clause or description]
- **Key fields:** [from SQL SELECT or design field]
- **Filters/parameters:** [from SQL WHERE or description]
- **Related entities:** [from SQL JOINs or $expand needs]

### Filtering & Exclusion Rules
- [Extract EVERY filtering rule from the design notes, SQL WHERE clauses, and business requirements]
- [For each rule, note the original SQL/description AND the proposed OData equivalent]
- [Flag rules involving collection checks (subqueries) — these likely need lambda operators: `any()`/`all()`]
- [Flag rules involving string patterns (LIKE) — these likely need `startswith`/`endswith`/`contains`]
- [Example: "Exclude -10 locations in zones 04-06" → `not (endswith(Name,'-10') and (startswith(Name,'04') or ...))` ]

### Layout Expectations
- **Page size:** [from existing report or description]
- **Orientation:** [portrait/landscape]
- **Key sections:** [header, detail grid, footer, etc.]
- **Special elements:** [barcodes, logos, multi-column layout]

### Entity Keywords for Schema Search
[List of OData entity search terms derived from SQL table names or description nouns]

### Reference Materials
- [List downloaded attachments and what each provides]

アーティファクトが有効な場合は、ブリーフを <artifact_dir>/requirements/requirements-brief.md に保存します。

避けるべきパターン

• 作業項目の内容をそのままコンテキストに出力しない — description フィールドと design フィールドを要約し、実用的な部分（フィールド一覧、SQL、レイアウト仕様）のみを抽出してください
• 作業項目ツリー全体を自動取得しない — 親項目や子項目は無関係な可能性があります。ユーザーに確認してください
• design フィールドを省略しない — 多くの場合、OData フィールドに対応する正確な SQL クエリなど、最も詳細な仕様が含まれています
• 既存の .rdlx-json 添付ファイルを無視しない — 具体的なフィールドのマッピングとレイアウトが含まれており、スキーマの調査やプロトタイプ作成を効率化できます