analyzing-release-readiness

リリース準備状況レビュー

AgentSpace のルーティング（SigV4 のみ）： ツール一覧に list_agent_spaces があり、このセッションでマルチスペースオーケストレーションスキルがまだ呼び出されていない場合は、最初にそのスキルを呼び出し、使用する agent_space_id を特定してください。その後、以下のすべてのツール呼び出しで agent_space_id を渡してください。ベアラートークン認証の場合は不要です。トークンはすでに 1 つのスペースにスコープされています。

AWS DevOps Agent を使ってリリース準備状況レビューを実行します。コード変更のリスク、正確性、ロールバック時に発生する可能性のある問題を分析し、実行可能な指摘事項を含む構造化レポートを返します。

ルール：

• PR/MR の URLが指定されている場合：URL からすべてのフィールドを抽出してください。ローカルのワークスペースや Git の状態を調べてはいけません。
• PR/MR の詳細を取得するために、gh CLI、glab CLI、その他の外部ツールを絶対に使用しないでください。 必要なすべてのフィールド（リポジトリ、prNumber/mergeRequestIid、ホスト名）は、URL またはユーザーの入力から直接解析する必要があります。DevOps Agent が自ら内容を取得するため、識別子を渡すだけで十分です。
• ユーザーが PR/MR のリンクなしでリポジトリまたはパッケージに言及した場合に限り、ローカルワークスペースのフローを使用してください。

実行パラメーターの収集

ユーザーのリクエストからすべてを自動的に推測してください。導き出せるパラメーターを質問してはいけません。

入力ソースの判断ツリー：

Has the user provided a pull request/merge request link or ID?
├── Yes: github.com PR URL               → use "GitHub PR" flow below
├── Yes: gitlab.com MR URL               → use "GitLab MR" flow below
└── No link provided — repo name only    → use "Local GitHub/GitLab repo" flow below

---

GitHub PR（github.com の URL または PR の参照）

• 入力を解析してフィールドを抽出してください。入力から特定できない場合を除き、Web から取得しようとしてはいけません。
• repository（必須）：PR の URL から取得した owner/repo
• 次のうち少なくとも 1 つが必要です：headSha（コミット SHA）、headBranch（ブランチ名）、prNumber（PR 番号。8 ではなく "8" のような文字列）
• hostname：URL から取得します（例：github.com またはセルフホストのホスト名）
• これらのフィールドを、content.githubPrContent の下にオブジェクトの配列として create_release_readiness_review に渡してください（PR が 1 件の場合も同様です）。

例：

{
  "content": {
    "githubPrContent": [
      {
        "repository": "owner/repo",
        "prNumber": "8",
        "hostname": "github.com"
      }
    ]
  }
}

重要な形式ルール：githubPrContent は単一のオブジェクトではなく、必ず配列にしてください。prNumber は必ず整数ではなく文字列にしてください。

---

GitLab MR（gitlab.com の URL）

• 入力を解析してフィールドを抽出してください。入力から特定できない場合を除き、Web から取得しようとしてはいけません。
• repository（必須）：MR の URL から取得した owner/repo
• 次のうち少なくとも 1 つが必要です：headSha（コミット SHA）、headBranch（ブランチ名）、mergeRequestIid（MR 番号。1 ではなく "1" のような文字列）
• hostname：URL から取得します（例：gitlab.com またはセルフホストのホスト名）
• これらのフィールドを、content.gitlabMrContent の下にオブジェクトの配列として create_release_readiness_review に渡してください（MR が 1 件の場合も同様です）。

例：

{
  "content": {
    "gitlabMrContent": [
      {
        "repository": "namespace/repo",
        "mergeRequestIid": "1",
        "hostname": "gitlab.com"
      }
    ]
  }
}

重要な形式ルール：gitlabMrContent は単一のオブジェクトではなく、必ず配列にしてください。mergeRequestIid は必ず整数ではなく文字列にしてください。どちらかに違反すると、ジャーナルレコードが作成されないままタスクが直ちに失敗します。

---

ローカルの GitHub/GitLab リポジトリ（PR/MR の URL が指定されていない場合 — ローカルワークスペースのみ）

必須：ユーザーが PR/MR のリンクなしでリポジトリまたはブランチに言及した場合、以下のすべての手順を順番どおりに実行する必要があります。リモート URL と SHA を直接取得して手順を省略してはいけません。レビューエージェントが参照するには、プッシュ済みのブランチが必要です。プッシュ手順を省略すると、分析に失敗するか、結果が不完全になります。

1. リポジトリのディレクトリへ移動する：リポジトリのルート（例：クローン先のディレクトリ）へ cd してください。必要に応じてユーザーに確認します。

2. ベースブランチを特定する：ユーザーが別のブランチを指定しない限り、main を使用します。リモート追跡ブランチが存在することを確認してください。

   BASE_BRANCH="main"
   if ! git show-ref --verify --quiet refs/remotes/origin/$BASE_BRANCH; then
       git fetch origin $BASE_BRANCH
   fi
   

   取得に失敗した場合（例：「couldn't find remote ref」）、ユーザーにベースブランチを指定するよう依頼し、停止してください。

3. ローカルの変更を確認する：git status --short と git rev-list --count origin/$BASE_BRANCH..HEAD を実行して状態を判定し、次のとおりユーザーに伝えてください。

   • 変更がなく、先行もしていない場合：分析対象の新しい変更がないことをユーザーに伝え、停止してください。

   • コミットされていない変更がある（未プッシュのコミットの有無は問わない）：

     • 未プッシュのコミットが1つ以上ある場合（rev-list count >= 1）、ユーザーに次のように伝えます。

       "コミットされていない変更と、未プッシュのコミットがN件あります。コミットされていない変更をその上にコミットしてから、N+1件のコミットすべてを分析用の新しいブランチにプッシュします。すべての変更は、ベースブランチとの差分として1つにまとめて表示されます。続行してもよろしいですか？"

     • 未プッシュのコミットがない場合（rev-list count = 0）、ユーザーに次のように伝えます。

       "コミットされていない変更をコミットし、リリース準備状況のレビュー用に新しいブランチへプッシュします。続行してもよろしいですか？"

     • ユーザーの承認を得るまで、続行しないでください。 拒否された場合は停止します。

   • ワーキングツリーはクリーンだが、リモートより先行している（rev-list count > 0、コミットされていない変更なし）：

     • 1件を超えるコミット分だけ先行している場合、ユーザーに次のように伝えます。

       "未プッシュのコミットがN件あります。すべてを分析用の新しいブランチにプッシュします。すべての変更は、ベースブランチとの差分として1つにまとめて表示されます。続行してもよろしいですか？"

     • ちょうど1件のコミット分だけ先行している場合、ユーザーに次のように伝えます。

       "最新のコミットをリリース準備状況のレビュー用に新しいブランチへプッシュします。続行してもよろしいですか？"

     • ユーザーの承認を得るまで、続行しないでください。 拒否された場合は停止します。

4. コミットされていない変更をスタッシュする（ワーキングディレクトリがクリーンな場合は、この手順をスキップします）。

   git stash push --include-untracked -m "release-analysis: preserve working changes"
   

5. レビューブランチを作成する（スナップショットコミットが使い捨てブランチにのみ存在するよう、コミットする前に実行します）。

   ORIGINAL_BRANCH=$(git rev-parse --abbrev-ref HEAD)
   BRANCH_NAME="feat/release-readiness-review"
   git checkout -b $BRANCH_NAME 2>/dev/null || { BRANCH_NAME="feat/release-readiness-review-$(date +%Y%m%d-%H%M%S)"; git checkout -b $BRANCH_NAME; }
   

6. スタッシュした変更を適用し、レビューブランチでコミットする（ワーキングディレクトリがクリーンだった場合は、この手順をスキップして手順7に進みます）。

   git stash apply
   

   ステージングする前に、機密ファイルがないか確認します。

   git status --short | grep -iE '\.(env|pem|key|p12|pfx|credentials|secret)'
   

   機密ファイルが検出された場合は、警告してから、続行する前にユーザーの確認を求めます。ユーザーが拒否した場合は中止します。

   git checkout $ORIGINAL_BRANCH && git branch -D $BRANCH_NAME && git stash drop
   

   確認が取れた場合（または機密ファイルが見つからなかった場合）：

   git add -A
   git commit -m "chore: snapshot for release readiness review"
   

7. 未プッシュのコミットをすべてプッシュする（事前にユーザーの承認が必要です）。 手順3でプッシュの承認を得ている場合は、そのまま続行します。それ以外の場合（たとえば、明示的な承認確認なしでこの手順に到達した場合）は、プッシュする前に確認します。

   "ブランチ $BRANCH_NAME を origin にプッシュしようとしています。これは前提となる手順ですが、続行してもよろしいですか？" ユーザーの承認を得るまで、プッシュしないでください。 拒否された場合は中止し、手順11に進みます。

   承認が得られた場合（または手順3ですでに承認されている場合）：

   git push -u origin HEAD
   

8. リポジトリ識別子とホスト名を特定する：git remote get-url origin | sed 's|://[^@]*@|://|' を実行して、owner/repo とホスト名を取得します。

   • GitHub の URL（github.com またはセルフホスト）→ githubPrContent を使用し、URL からホスト名を取得します
   • GitLab の URL（gitlab.com またはセルフホスト）→ gitlabMrContent を使用し、URL からホスト名を取得します

9. コンテンツを作成する：headBranch に $BRANCH_NAME、repository に取得した owner/repo、hostname に手順8で取得した値を設定します。オブジェクトを配列で囲みます。

   • GitHub：{"githubPrContent": [{"repository": "owner/repo", "headBranch": "feat/release-readiness-review", "hostname": "github.com"}]}
   • GitLab：{"gitlabMrContent": [{"repository": "namespace/repo", "headBranch": "feat/release-readiness-review", "hostname": "gitlab.com"}]}

10. ユーザーに知らせる：作成してプッシュしたブランチを伝えてから、以下のコアワークフローに進みます。

11. 分析の完了後：クリーンアップを行い、作業状態を復元します。

    git checkout $ORIGINAL_BRANCH
    git push origin --delete $BRANCH_NAME 2>/dev/null || true
    git branch -D $BRANCH_NAME 2>/dev/null || true
    

    手順4を実行した場合（コミットされていない変更をスタッシュした場合）は、次も実行します。

    git stash pop
    

重要：PR/MR は作成しないでください。ブランチをプッシュするだけです。リリース準備状況レビューエージェントがブランチを直接読み取ります。

コアワークフロー

厳密な順序：以下の手順には番号が付いています。次の手順に進む前に、各手順を完了する必要があります。特に、手順 1（自動テストのプロンプト）は、上記の「実行パラメーターの収集」フローが完全に完了するまで実行してはいけません。すべての Git 操作が完了し（ローカルフローの場合は）ブランチがプッシュされ、コンテンツオブジェクトが作成され、ブランチについてユーザーに伝えた後にのみ、手順 1 に進んでください。

1. skip_automated_testing を決定する（コンテンツの準備ができてからのみ質問）

skip_automated_testing パラメーターは、エージェントが自動テスト（自動検証テスト）を実行するか、静的解析のみを実行するかを制御します。

値	動作
true	自動テストをスキップし、静的解析のみを実行します（高速 — コードレビュー、リスク評価、依存関係のチェック）
false	自動テストを含む完全な解析を実行します（時間がかかります — テスト環境を起動し、コードをビルドして、自動検証テストを実行します）

選択肢を提示し、回答を待ちます。

「簡易的な静的解析（コードレビュー、リスク評価、依存関係のチェック）と、自動テストも含む完全な解析のどちらをご希望ですか？自動テストではテスト環境を起動し、コードをビルドして、自動検証テストを実行します。より徹底した解析になりますが、時間がかかります。」

ユーザーが回答するまで先に進んではいけません。

• ユーザーが「はい」／「テストを含める」／「完全な解析」／「テストを実行」と答えた場合 → skip_automated_testing=false を使用します
• ユーザーが「いいえ」／「静的解析のみ」／「テストをスキップ」／「簡易」または辞退した場合 → skip_automated_testing=true を使用します
• 回答が曖昧な場合（例：「進めて」「いいですよ」「続行」）→ どちらの選択肢を希望するか、ユーザーに確認してください。

2. ツールの利用可否を確認する

次のツールが利用可能であることを確認します：aws_devops_agent__create_release_readiness_review、aws_devops_agent__get_task、aws_devops_agent__list_journal_records、aws_devops_agent__get_release_readiness_report。これらのツールは遅延ロードされるものではありません。ツール一覧に表示されない場合、利用できません。ToolSearch で検索してはいけません。いずれかが不足している場合、このセクションの残りの手順をスキップし、代わりに下記の「フォールバック（aws-mcp）」の手順を使用してください。ユーザーに次のように伝えます：「リモートサーバーを利用できません — 直接 aws-mcp サーバーにフォールバックします。」

3. ジョブを開始する

aws_devops_agent__create_release_readiness_review(
    content={...},
    skip_automated_testing=true/false
)
→ {"taskId": "...", "executionId": "...", "status": "started"}

応答から taskId と executionId を記録します。

4. ステータスをポーリングする

ステータスが IN_PROGRESS または終端状態（COMPLETED、FAILED、CANCELED、TIMED_OUT）に移行するまで、30 秒ごとに aws_devops_agent__get_task(task_id=TASK_ID) を呼び出します。

5. 完了まで監視する

IN_PROGRESS になったら、次のループで進捗をポーリングします。

1. aws_devops_agent__list_journal_records(execution_id=EXEC_ID, order="ASC") を呼び出して、新しい調査結果を取得します。
2. 親しみやすい進捗状況の更新とともに、各レコードをユーザーに提示します。
3. 後続のポーリングで新しいレコードのみを取得するために、応答の next_token を使用します。
4. 各ポーリングの間は 15 秒待機します。
5. aws_devops_agent__get_task(task_id=TASK_ID) を定期的に確認し、終端状態になったら停止します。

6. 結果の提示

ジョブが終端ステータスになったら：

• COMPLETED の場合：

  1. aws_devops_agent__get_release_readiness_report(execution_id=EXEC_ID) を呼び出して、レポート全体を取得します。

  2. レポートの内容を次の Markdown ファイルに書き込みます。

     release-readiness-review-<YYYY-MM-DD-HHmmss>.md
     

  3. レポートが保存されたことと、ファイルパスをユーザーに伝えます。

  4. 自動修正フロー（必須）：レポートを保存した後、実行可能なリスクすべてに対する修正を必ず生成し、提示してください。これはレビュー ワークフローの主要な価値であり、任意のステップではありません。

     • まず、現在のワークスペースで分析対象のリポジトリを見つけます。
       1. ls を実行して、ワークスペースで利用可能なディレクトリを一覧表示します。
       2. リポジトリ名（owner/repo または namespace/repo の最後のセグメント）で照合します。たとえば、testgroupadthiru/repo1updated の場合は、repo1updated という名前のディレクトリを探します。
       3. 一致するものが1つ見つかった場合は、ユーザーに「<match> が見つかりました。これは <namespace/repo> の正しいローカルコピーですか？」と確認します。
       4. 複数見つかった場合は、どれが正しいかユーザーに尋ねます。
       5. 該当するものが見つからない場合は、ユーザーに「<repo-name> に一致するローカルディレクトリが見つかりませんでした。別の名前でローカルにありますか。それとも、提案された修正のみを表示すればよいですか？」と尋ねます。
     • ローカルで見つかった場合：

       • ブランチを確認：git -C <repo-directory> branch --show-current を実行して、想定されるブランチにいることを確認します。想定されたブランチでない場合は、続行する前に正しいブランチに切り替えます。

       • レポートに記載されたリスクを解釈し、該当するコードを調査します。その後、ユーザーに次のように伝えます。

         「レポートで、対応可能な問題が N 件見つかりました。ローカルリポジトリに修正を生成し、新しいブランチ feat/release-readiness-fix にプッシュできます。進めてもよろしいですか？」

       • ユーザーの承認を得るまで、作業を進めてはいけません。 ユーザーが承認しない場合は、停止します。

       • 承認されたら、修正を生成します。その後、次の手順を実行します。

         cd <repo-directory>
         git checkout -b feat/release-readiness-fix 2>/dev/null || { git checkout -b "feat/release-readiness-fix-$(date +%Y%m%d-%H%M%S)"; }
         # Apply the fixes
         git add -A
         git commit -m "fix: Address issues identified by release readiness review"
         

       • プッシュする前に、もう一度ブランチを確認します。git branch --show-current を実行し、feat/release-readiness-fix* が表示されることを確認します。他のブランチにいる場合は、プッシュしてはいけません。

         git push -u origin HEAD
         

         修正した問題、作成したブランチ、修正をプッシュしたことをユーザーに伝えます。

     • ローカルで見つからない場合：レポートにある提案された修正を、すぐに適用できる具体的なコードパッチとして提示します。各リスクの suggestedFix フィールドを使用します。ユーザーがコピーしてそのまま貼り付けられるよう、コードブロックで示します。対応可能なリスクを1件ずつ説明し、問題点、正確な修正内容、対象となるファイルと行を示します。
     • レポートでリスクや問題が見つからなかった場合：分析が完了し、対応が必要な項目は見つからなかったことをユーザーに伝えます。
• FAILED または TIMED_OUT の場合：エラー情報を提示し、次に行うべきことを提案します。
• CANCELED の場合：ジョブがキャンセルされ、レポートは利用できないことをユーザーに伝えます。

ジョブのキャンセル

aws_devops_agent__cancel_release_readiness_review(task_id=TASK_ID)

エラー処理

1. FAILED または TIMED_OUT の場合は、処理を停止してエラーを提示します。ジョブがすぐに失敗した場合（最初の1、2回のポーリング以内）は、aws_devops_agent__list_associations() を呼び出して、対象リポジトリのホスティングサービス（GitHub／GitLab のホスト名）がエージェントスペースに関連付けられているか確認します。
2. 5分以内にジョブが IN_PROGRESS にならない場合は、cancel_release_readiness_review でキャンセルします。
3. スロットリングされた場合（429 または ThrottlingException）は、30秒待ってから、最大3回まで再試行します。
4. 上記の既知のパターンに該当しないエラーの場合は、生のエラー出力をユーザーに提示します。

Fallback (aws-mcp)

aws-devops-agent リモートサーバーを利用できない場合は、AWS CLI を直接使用します。

ユーザーに次のように伝えます：「リモートサーバーを利用できません。aws-mcp サーバーのフォールバックを使用します。」

1. Agent Space を選択する

利用可能な Agent Space を一覧表示します。

aws devops-agent list-agent-spaces --region us-east-1

一覧をユーザーに提示し、使用する Agent Space を尋ねます。ユーザーが選択するまで先に進まないでください。 選択された agentSpaceId を、以降のすべての呼び出しで SPACE_ID として使用します。

2. ジョブを開始する

aws devops-agent create-backlog-task \
  --agent-space-id SPACE_ID \
  --task-type RELEASE_READINESS_REVIEW \
  --title 'Release Readiness Review' \
  --priority MEDIUM \
  --description '{\"agentInput\": {\"content\": <CONTENT_JSON>, \"metadata\": {\"skipAutomatedTesting\": true}}}' \
  --region us-east-1

重要： content の値は単一のオブジェクトでなければならず、リストで囲んではいけません。正しい例："content": {"githubPrContent": [...]}。誤った例："content": [{"githubPrContent": [...]}]。リストで囲むと、バックエンドで Pydantic の検証エラーが発生します。content 内の値はすべて文字列形式にしてください（例：PR 番号は文字列にします）。

デフォルトは "skipAutomatedTesting": true（静的テストのみ）です。ユーザーが自動テストを明示的に選択した場合にのみ、false に設定します。

3. ステータスをポーリングする

aws devops-agent get-backlog-task \
  --agent-space-id SPACE_ID \
  --task-id TASK_ID \
  --region us-east-1

ステータスが IN_PROGRESS または終端状態（COMPLETED、FAILED、CANCELED、TIMED_OUT）に変わるまで、30 秒ごとにポーリングします。

4. 完了まで監視する

IN_PROGRESS になったら、ループで進捗をポーリングします。

aws devops-agent list-journal-records \
  --agent-space-id SPACE_ID \
  --execution-id EXEC_ID \
  --order ASC \
  --region us-east-1

1. 各レコードを、分かりやすい進捗状況とともにユーザーに提示します。
2. 以降のポーリングでは、応答の next_token を使用して新しいレコードのみを取得します。
3. ポーリングの各反復の間に15 秒待機します。
4. get-backlog-task を定期的に確認し、終端状態になったら停止します。

5. 結果を提示する

ジョブが終端状態になったら：

• COMPLETED の場合：

  1. レポートを取得します。

     aws devops-agent list-journal-records \
       --agent-space-id SPACE_ID \
       --execution-id EXEC_ID \
       --record-type release_analysis_report \
       --order ASC \
       --region us-east-1
     

  2. レポートの内容を Markdown ファイルに書き込みます。

     release-readiness-review-<YYYY-MM-DD-HHmmss>.md
     

  3. ファイルパスを含め、レポートが保存されたことをユーザーに伝えます。

  4. 自動修正フロー（必須）： レポートを保存した後、実行可能なすべてのリスクに対する修正を必ず生成し、提示します。これはレビューのワークフローの中心的な価値であり、任意の手順ではありません。上記のコアワークフローの自動修正フローに従い、リポジトリを特定し、ブランチを確認し、修正を生成して、feat/release-readiness-fix にプッシュします。

• FAILED または TIMED_OUT の場合：エラー情報を提示し、次の手順を提案します。
• CANCELED の場合：ジョブがキャンセルされ、レポートを利用できないことをユーザーに伝えます。

キャンセル（フォールバック）

aws devops-agent update-backlog-task \
  --agent-space-id SPACE_ID \
  --task-id TASK_ID \
  --task-status CANCELED \
  --region us-east-1