Claude CodeにTeamCity CLIのスキルを入れてビルドの調査と再実行を任せる

TeamCityの失敗ビルドは、teamcity CLIとそのスキルをClaude Codeに入れると、ターミナルの中だけで調べて直せます。ブラウザでビルドログを開く手間がなくなり、「直近の失敗を見て原因を教えて」と頼めば、一覧の取得、ログの読み取り、失敗テストの確認、変更履歴の突き合わせまで順に実行されます。

必要なのは3つです。TeamCity CLI本体、認証、そしてClaudeにコマンドの使い方を教えるスキルです。このページでは、その入れ方と、調査から再実行までの頼み方、勝手にビルドを走らせないための権限の絞り方を扱います。

TeamCity CLIのスキルは何を教えてくれるのか

TeamCity CLIは、JetBrainsが公開しているTeamCityの公式コマンドラインクライアントです。ビルドの開始、ログの追跡、キューの確認に加え、ビルドエージェントへのシェル接続やジョブ設定の編集、生のREST呼び出しまで1つのコマンドで扱えます。

スキルは、そのCLIの使い方をエージェント向けに書いたMarkdownです。名前はteamcity-cliで、説明文は「TeamCityのビルドURLを渡されたとき、またはTeamCityのCI/CDを扱うときに使う」という趣旨になっています。Claudeはこの記述を見て、TeamCityの話題になったときにだけスキルを読み込みます。

中身で役に立つのは、コマンド一覧よりも「踏みやすい点」の注意書きです。

• 複合ビルド(composite build)のログは空なので、子ビルドまで掘る
• ビルドチェーンは下から失敗するため、いちばん深い失敗した依存が原因
• ログは--rawで取り、一時ファイルに落としてから読む
• 件数指定は--countではなく--limit(-n)

Claudeが自己流のフラグを推測して失敗する場面を、先に潰してくれる内容です。

TeamCityの用語がCLIでは少し変わります。ビルドは「run」、ビルド構成は「job」と呼びます。Claudeへの依頼文でビルドと書いても通じますが、CLAUDE.mdにはCLI側の呼び方を書いておくと食い違いが減ります。

導入手順 — CLI、認証、スキルの順に入れる

スキルが実行するのは、あくまで手元のteamcityコマンドです。スキルだけ入れてもCLI本体は入らないので、順番は次のとおりです。

CLI本体のインストール

macOSならHomebrewが手軽です。Linuxとインストールスクリプトでも入ります。

# macOS(Homebrew)
brew install jetbrains/utils/teamcity
 
# Linux(macOSでも使えます)
curl -fsSL https://jb.gg/tc/install | bash
 
# npm
npm install -g @jetbrains/teamcity-cli

WindowsはwingetのパッケージIDJetBrains.TeamCityCLIで入ります。このほかdeb、rpm、Scoop、Chocolatey、ソースからのビルドにも対応しています。対応するTeamCityサーバーは2020.1以降で、機能によってはより新しいバージョンが必要です。

スキルを入れる2つの経路

スキルの入れ方は2通りあります。

# 経路1: CLIが同梱するスキルを、検出したエージェントへ入れる
teamcity skill install
teamcity skill install --project   # 現在のプロジェクトだけに入れる
teamcity skill update              # CLIに同梱のバージョンへ更新
teamcity skill remove              # 削除

経路2は、Claude Codeのプラグインとして入れる方法です。Claude Codeのセッション内で次を実行します。

/plugin marketplace add JetBrains/teamcity-skills
/plugin install teamcity@teamcity

プラグインの場合もCLIは先に自分で入れておく必要があります。JetBrains/teamcity-skillsのリポジトリにはteamcity-cliのほか、最初の成功ビルドまでを導くteamcity-first-green-build、IntelliJ系IDEから使うteamcity-intellij、GitHub ActionsやBambooのパイプラインを移行するmigrate-to-teamcityが入っています。

認証 — ブラウザ承認か、トークンか

最初の一度だけ、サーバーを登録します。

teamcity auth login
teamcity auth status

対話式の流れでは、サーバーURLを入力するとブラウザが開き、OAuthのPKCEフローで承認します。トークンのコピーは要りません。ただしこのフローはTeamCity 2026.1以降のサーバーが対象です。それより古いサーバーでは、アクセストークンのページへ案内され、発行したトークンを貼り付ける形になります。

ブラウザを使えない環境では、トークンを直接渡せます。

teamcity auth login --server https://teamcity.example.com --no-browser
teamcity auth login --server https://teamcity.example.com --token <token>

トークンはmacOSならKeychain、LinuxならGNOME Keyring、WindowsならCredential Managerに保存されます。キーリングが使えないときは、~/.config/tc/config.ymlに平文で保存されます。--insecure-storageを付けると平文保存を明示的に選べますが、ファイルの権限管理は自己責任です。

認証の方法は他にもあります。ゲストアクセスが有効なサーバーならteamcity auth login --guestで読み取り専用に入れます。CIなどでは環境変数TEAMCITY_URLとTEAMCITY_TOKENも使えます。

失敗ビルドの調査をClaudeに頼む

認証が済んだら、Claude Codeを起動して依頼します。スキルが読み込まれるので、細かいコマンドを教える必要はありません。

TeamCityのMyProject_Buildで直近に失敗したビルドを調べて、原因を教えて。
ログは--failed --rawで取って、失敗したテストと、そのビルドを起こした変更も見て。
修正はまだしないで。

スキルが示す調査の標準手順は次の順です。依頼文に書かなくても、この順で進む想定になっています。

ログは長くなりがちなので、スキルは一時ファイルへ落としてから読む方式を勧めています。たとえばteamcity run log <run-id> --failed --raw > /tmp/build-failure.logです。会話にログ全文が流れ込まず、文脈の消費を抑えられます。

ビルドチェーンの失敗は下から読む

スナップショット依存で連なったビルドは、1つの失敗が上流へ波及します。見えている失敗は「Snapshot dependency build failed」で、本当の原因ではないことがあります。

そのときは次のコマンドで依存の木を出します。

teamcity run tree <run-id>

ステータス付きで木が出るので、いちばん深い失敗ビルドが原因です。最上位のビルドを再実行しても、根元の子ビルドが壊れたままなら直りません。依頼文に「チェーンになっていたら、いちばん深い失敗から読んで」と一言添えておくと、Claudeが上位ビルドのログ(複合ビルドは空です)で立ち止まる事態を防げます。

再実行と修正の確認 — 一時的な失敗かを先に分ける

調査の次は再実行ですが、闇雲に再実行させない方が安全です。スキルは失敗を2つに分類しています。

• 一時的な失敗: インフラのタイムアウト、エージェントの切断、エージェント側のメモリ不足、同じコードが再試行で通るflaky test。対処はteamcity run restart <id>で再実行
• 恒久的な失敗: コンパイルエラー、コード変更と相関のあるテスト失敗、設定ミス。対処はコードや設定の修正

分類が付かない失敗は、恒久的なものとして扱うのが既定です。つまり再実行を試す前に、まず原因の仮説を立てさせます。依頼文にも、再実行の前に分類を報告するよう書いておくと、Claudeが理由なく再実行を繰り返す場面を減らせます。restartを権限設定のaskに置いておけば、実行前に必ず確認が入ります。

コードを直した場合は、コミットする前にTeamCity上で確かめられます。

teamcity run start MyProject_Build --local-changes --watch

--local-changesは手元の未コミット差分を載せた個人ビルドを走らせ、--watchで終わるまで付き添います。緑になってからコミットして送る流れです。

ここには例外があります。--local-changesには、Kotlin DSL(.teamcity/)とリポジトリ内のパイプラインYAMLの変更が含まれません。DSLの修正は先にpushしてからビルドを走らせます。DSLの構文はteamcity project settings validateで、パイプラインYAMLはteamcity pipeline validateで、それぞれ手元で検証できます。pipeline pushは検証をしないので、先にvalidateを挟みます。

スキルの手順書には、テストを消したりスキップしたりして緑にしない、という注意も書かれています。依頼文でも同じ縛りを繰り返しておくと、確実性が上がります。

勝手にビルドを走らせないための設定

ビルドの開始、キャンセル、エージェントへのシェル接続は、読み取りと性質が違います。Claude Codeの権限設定で、調査系は許可し、変更系は確認を挟みます。.claude/settings.jsonの例です(公式の書式に沿った一例です)。

{
  "permissions": {
    "allow": [
      "Bash(teamcity auth status)",
      "Bash(teamcity run list *)",
      "Bash(teamcity run view *)",
      "Bash(teamcity run log *)",
      "Bash(teamcity run tests *)",
      "Bash(teamcity run changes *)",
      "Bash(teamcity run tree *)"
    ],
    "ask": [
      "Bash(teamcity run start *)",
      "Bash(teamcity run restart *)"
    ],
    "deny": [
      "Bash(teamcity agent *)",
      "Bash(teamcity run cancel *)",
      "Bash(teamcity api *)"
    ]
  }
}

権限の書式では、*をサブコマンドの後ろに置きます。Bash(teamcity run list *)はteamcity run listとその引数に一致し、teamcity run startには一致しません。denyはallowより優先され、allowで例外を作ることはできません。そのため、teamcity api *のように何でも通る入口は、調べ物に使いたい場合を除いて拒否側に置くのが無難です。

CLI側にも歯止めがあります。環境変数TEAMCITY_RO=1を設定すると、書き込み操作と、agent exec、agent termのリモートシェルが拒否されます。サーバーごとにro: trueを設定する方法もあります。ただしREADMEは、これをセキュリティ境界として使わないよう注意しています。境界はTeamCityサーバー側の権限、つまり読み取り専用のトークンで作るものです。

CLAUDE.mdに書いておくこと

スキルは汎用なので、プロジェクト固有の事情はCLAUDE.mdに書きます。たとえば次の断片です。

## TeamCity
- 主要ジョブのIDは MyProject_Build(ビルドは run、ビルド構成は job と呼ぶ)
- ログは `teamcity run log <id> --failed --raw` で取り、一時ファイルに保存して読む
- 件数指定は --limit(-n)。--count は使わない
- 失敗はまず一時的か恒久的かを分類して報告する。報告前に run restart しない
- 再実行と修正の確認は、私の承認後に run start --watch で行う
- agent exec と agent term は使わない

リポジトリとTeamCityプロジェクトの対応づけには、teamcity linkでteamcity.tomlを作る方法があります。複数のVCSルートを持つジョブでは、--revision ROOT=SHAを繰り返し指定して、ルートごとにリビジョンを固定できます。

つまずきやすい点

• 複合ビルドのログが空に見えるのは仕様です。子ビルドをrun list --status failureで探すか、run treeで掘ります
• 「利用可能なエージェントがない」型の失敗は、コードではなくサーバー設定の問題です
• 複数のTeamCityサーバーを使い分けるなら、コマンドごとにTEAMCITY_URLを指定して、保存済みの認証情報を使います

MCPやCIサービスの接続とどう使い分けるか

TeamCityはCLIのほかにMCPサーバーも提供しており、AIエージェント統合のドキュメントでは両方が紹介されています。目安は実行環境です。Claude Codeのように手元でコマンドを実行でき、ファイルを読み書きできるエージェントは、CLIとスキルが自然な選択です。ブラウザ上のチャットのようにCLIを直接呼べない環境では、MCPが向きます。

同じ考え方は他のCIサービスにも当てはまります。MCPで繋ぐ型の例は、Bitrise MCPをClaude Codeにつないでビルド起動と失敗調査を任せるにあります。ビルドツール側の出力を絞って完了を判定する発想は、MavenビルドをClaude Codeで回す手順と共通です。

どちらの形でも、核になるのは「調べる操作は広く許可し、ビルドを起こす操作は人が承認する」という線引きです。TeamCityではそれを、Claude Codeのpermissions、TEAMCITY_RO、サーバー側のトークン権限の3層で作れます。