azure-devops

Azure DevOps スキル

ボード、リポジトリ、パイプライン、アーティファクトを網羅する Azure DevOps 連携機能です。

次の場合に自動で有効になります： ユーザーが Azure DevOps、ADO、作業項目、ボード、リポジトリ、パイプライン、アーティファクト、または Azure DevOps の URL に言及した場合。

目的

このスキルでは、次の処理を行う専用の Python CLI ツールを通じて、Azure DevOps の自動化に関する包括的なガイダンスを提供します。

作業項目（ボード）

• HTML 形式の説明を含む作業項目の作成
• 作業項目の更新（状態、割り当て、フィールド）
• 確認を伴う作業項目の削除
• 親子関係のリンク
• WIQL クエリの実行
• 作業項目の種類とフィールドの確認

リポジトリ

• 詳細情報を含むリポジトリ一覧の取得
• レビュアーと作業項目を指定したプルリクエストの作成
• ブランチの検証
• クローン URL へのアクセス

パイプライン

• パイプラインの一覧表示と実行
• ビルドの監視とログの確認
• デプロイの管理

アーティファクト

• パッケージフィードの管理
• パッケージの公開とダウンロード
• バージョン管理

クイックスタート

1. まず認証する

必ず認証の確認から始めてください：

python .claude/scenarios/az-devops-tools/auth_check.py --auto-fix

Azure CLI がインストールされていること、ログイン済みであること、組織とプロジェクトが設定されていること、アクセス権があることを確認します。

参照：[@authentication.md]

2. よくある操作

作業項目を作成する

python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "User Story" \
  --title "Implement feature" \
  --description @story.md

作業項目をクエリする

python .claude/scenarios/az-devops-tools/list_work_items.py --query mine

プルリクエストを作成する

python .claude/scenarios/az-devops-tools/create_pr.py \
  --source feature/branch \
  --target main \
  --title "Add feature"

詳細ガイド

特定の操作について詳しくは、以下を参照してください。

• [@authentication.md] - 認証方法（PAT、OAuth、環境変数）
• [@work-items.md] - 作業項目の CRUD 操作、フィールドの更新、状態遷移
• [@queries.md] - WIQL クエリのパターン、フィルタリング、並べ替え
• [@html-formatting.md] - 作業項目の説明やコメントでの HTML 形式
• [@repos.md] - リポジトリ操作、プルリクエストのワークフロー
• [@pipelines.md] - パイプラインのトリガー、ビルドの監視、デプロイ
• [@artifacts.md] - パッケージ管理、アーティファクトの公開
• [@HOW_TO_CREATE_YOUR_OWN.md] - 同様の連携ツールを作成するためのテンプレート

利用可能なツール

ツール	目的	使用する場面
auth_check.py	認証を確認する	操作を行う前
create_work_item.py	作業項目を作成する	ユーザーストーリー、タスク、バグなどを追加する
update_work_item.py	作業項目を更新する	状態、担当者、フィールドを変更する
delete_work_item.py	作業項目を削除する	作業項目を削除する（確認あり）
get_work_item.py	作業項目の詳細を取得する	作業項目の情報をすべて表示する
list_work_items.py	作業項目をクエリする	作業項目を検索、フィルタリング、一覧表示する
link_parent.py	親子関係をリンクする	エピック → 機能 → ストーリーの階層を作成する
query_wiql.py	WIQL クエリを実行する	WIQL による複雑なフィルタリングを行う
format_html.py	HTML に変換する	リッチな説明を整形する
list_types.py	種類やフィールドを確認する	利用可能なオプションを調べる
list_repos.py	リポジトリを一覧表示する	プロジェクト内のすべてのリポジトリを表示する
create_pr.py	プルリクエストを作成する	レビュー用にコードを提出する

よくあるパターン

パターン 1：親を指定して作業項目を作成する

# Create parent work item
python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "Epic" \
  --title "Q1 Planning Initiative" \
  --description @epic_desc.md

# Output: Created work item #12345

# Create child and link to parent
python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "Feature" \
  --title "Authentication System" \
  --description @feature_desc.md \
  --parent-id 12345

# Output: Created work item #12346 and linked to parent #12345

パターン 2：作業項目をクエリして更新する

# Find your active work items
python .claude/scenarios/az-devops-tools/list_work_items.py \
  --query mine \
  --format ids-only

# Update work item state
python .claude/scenarios/az-devops-tools/update_work_item.py \
  --id 12345 \
  --state "Active" \
  --comment "Starting work on this"

パターン 3：機能ブランチからプルリクエストを作成する

# List repositories
python .claude/scenarios/az-devops-tools/list_repos.py

# Create pull request
python .claude/scenarios/az-devops-tools/create_pr.py \
  --source feature/auth \
  --target main \
  --title "Add authentication" \
  --description @pr_desc.md \
  --reviewers "[email protected],[email protected]" \
  --work-items "12345,12346"

パターン 4：利用可能な種類を確認する

# List all work item types in your project
python .claude/scenarios/az-devops-tools/list_types.py

# Show fields for specific type
python .claude/scenarios/az-devops-tools/list_types.py \
  --type "User Story" \
  --fields

重要なポイント

HTML 形式が必須

Azure DevOps の作業項目の説明には、Markdown やプレーンテキストではなく HTML を使用します。

ツールが自動的に処理します：

• create_work_item.py はデフォルトで Markdown を HTML に変換します
• --no-html を使用すると変換を無効にできます
• または、format_html.py を直接使用して独自の形式にできます

参照：[@html-formatting.md]

2 段階で親をリンクする

CLI で作業項目の作成時に親を指定することはできません（Azure の制限です）。

ツールでは 2 つの方法を利用できます：

オプション A： --parent-id フラグを使用します（推奨）：

python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "Task" \
  --title "My Task" \
  --parent-id 12345

オプション B： 別途リンクします：

# Step 1: Create
TASK_ID=$(python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "Task" \
  --title "My Task" \
  --json | jq -r '.id')

# Step 2: Link
python .claude/scenarios/az-devops-tools/link_parent.py \
  --child $TASK_ID \
  --parent 12345

エリアパスと作業項目の種類

• エリアパスの形式：ProjectName\TeamName\SubArea
• 作業項目の種類はプロジェクトによって異なります（標準の種類とカスタムの種類）
• list_types.py を使用して、プロジェクトで利用可能な種類を確認します

エラーからの復旧

エラー	使用するツール	例
認証に失敗しました	auth_check.py --auto-fix	自動ログインして設定する
無効な作業項目の種類	list_types.py	利用可能な種類を確認する
フィールドの検証エラー	list_types.py --type "Type" --fields	有効なフィールドを確認する
親のリンクに失敗しました	ID が存在することを確認し、階層ルールを確認します	Epic → Feature → Story → Task
ブランチが存在しません	git branch -a で確認します	先にブランチをプッシュします

ツールの実装

すべてのツールは ~/.amplihack/.claude/scenarios/az-devops-tools/ にあります。

• 単独で実行できる Python プログラム
• インポート可能なモジュール（ほかのスクリプトから利用できます）
• 包括的なエラー処理
• テストは tests/ ディレクトリにあります

こちらを参照してください：ツールの README

基本方針

これらのツールは amplihack の原則に従っています。

• 徹底したシンプルさ：各ツールは 1 つのことを適切に実行します
• ごまかしなし：すべての関数が動作し、スタブや TODO はありません
• 再利用可能：インポートして組み合わせられます
• フェイルファスト：実行可能な対処方法を示す明確なエラー
• 自己完結型：標準ライブラリと azure CLI ラッパーのみを使用します

クイックリファレンス

# Setup (first time)
python .claude/scenarios/az-devops-tools/auth_check.py --auto-fix

# Create work item
python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "User Story" \
  --title "Title" \
  --description @desc.md

# Update work item
python .claude/scenarios/az-devops-tools/update_work_item.py \
  --id 12345 \
  --state "Active"

# Query work items
python .claude/scenarios/az-devops-tools/list_work_items.py --query mine

# Create pull request
python .claude/scenarios/az-devops-tools/create_pr.py \
  --source feature/branch \
  --target main \
  --title "Add feature"

# Discover types
python .claude/scenarios/az-devops-tools/list_types.py