Claude Code の Agent Teams で技術ブログ22記事を一括レビューした話——準備から実践まで

以前、「Claude Code の Agent Teams を組織論の視点で考える」という記事を書きました。ビュートゾルフの自律分散型組織をヒントに、Agent Teams をどう設計すべきかを考察した内容です。

ただ正直なところ、あの記事を書いた時点では「理論としてはこうなるはず」という仮説の段階でした。実際に自分のプロジェクトで本格的に使ったわけではなかったんです。

今回、自社ブログの CI/CD カテゴリにある22記事を Agent Teams で一括レビュー・更新する機会がありました。準備から実践まで一通りやってみて、うまくいったことも、正直ここで詰まったということもあったので、その過程をそのまま残しておきます。

この記事のポイント

先にこの記事で伝えたいことをまとめると、こうなります。

Agent Teams は「使い始める前の準備」で成果の8割が決まる。

逆に言えば、準備さえしっかりしていれば、複数エージェントが並列で動いてもちゃんと成果が出ます。ただし、想定通りにいかない場面も普通に起きるので、そこへの対処も含めて設計しておく必要があります。

この記事では、その「準備」と「実践」の両方を、実際のセッションログをもとに詳しく書いていきます。

なぜ Agent Teams で記事メンテナンスをやろうと思ったのか

技術ブログの「放置問題」

自社ブログには Jenkins 関連の記事が20件以上あります。CI/CD の入門から応用まで、それなりにまとまった量です。

ただ、技術記事は鮮度が命です。たとえば Jenkins の Blue Ocean というプラグインは2022年に公式で非推奨になっているのに、ブログではまだ「Blue Ocean を使いましょう」と推奨していたりする。こういう古い情報がそのまま残っていると、読者にとって害になります。

記事が5件くらいなら自分で一つずつ見ればいい。でも22件となると話が変わります。全部の記事を開いて、現在の公式ドキュメントと突き合わせて、問題のある箇所を洗い出して、修正して、ビルドが通るか確認する。これを1人でやると、丸一日かかってもおかしくない作業量です。

ここで思い出したのが、以前書いた記事のことでした。

自分で書いた理論を、自分で試す

Agent Teams の記事では、こんなことを書いていました。

• CLAUDE.md は組織の MVV（ミッション・ビジョン・バリュー）にあたる
• テストスイートは「行動指針の具体化」として機能する
• エージェントには最小限のルールと最大限の裁量を与える

理論は書いた。でも、実践していない。これは少しまずいなと思いました。自分の言葉に責任を持つためにも、まずは自分のリポジトリで試してみようと。

これも何かの縁だと思い、CI/CD 記事の一括メンテナンスを Agent Teams でやることにしました。

準備編——Agent Teams が動く「土壌」をつくる

準備でやったことの全体像

Agent Teams を使う前に、まずリポジトリ側の環境を整える必要がありました。やったことは大きく4つです。

graph TD
    A[CLAUDE.md に<br>Agent Teams ガイドライン追加] --> E[Agent Teams<br>運用可能な状態]
    B[AGENT_TEAMS.md<br>実践ガイド作成] --> E
    C[統合検証スクリプト<br>作成] --> E
    D[package.json に<br>validate コマンド追加] --> E

順番に説明します。

1. CLAUDE.md に Agent Teams 運用ガイドラインを追加する

以前の記事で「CLAUDE.md は MVV（ミッション・ビジョン・バリュー）にあたる」と書きました。これを実際にやってみたのが、この作業です。

もともと CLAUDE.md にはプロジェクトの概要やコマンド一覧、コンテンツ管理のルールなどが書いてありました。ここに Agent Teams 専用のセクションを追加します。

追加した内容の構成はこうなっています。

MVV（ミッション・ビジョン・バリュー）の明記

「高品質な二言語技術ブログの維持・発展」という使命を明文化しました。Agent Teams のエージェントは、この使命に沿って自律的に判断することになります。人間が毎回「こうしてほしい」と細かく指示しなくても、判断軸が共有されていれば大きくは外れません。

行動指針は「原則」レベルに留める

意外とここが肝です。ルールを細かく書きすぎると、エージェントの柔軟性が失われます。ビュートゾルフの「最小限のルール、最大限の裁量」という考え方を意識して、以下の4つだけにしました。

1. 既存機能を壊さない（テストスイートで確認）
2. コンテンツの整合性を維持する（検証ツールで確認）
3. 大規模な変更は段階的に進める
4. 判断に迷ったら人間（コーチ役）に確認する

テストスイートの位置づけを明記

ここが準備のなかで一番重要だったかもしれません。テストスイートを「上司の代わり」として位置づけたんです。

npm run lint                                    # コード品質の検証
npx tsx scripts/check-affiliate-integrity.ts    # アフィリエイトリンクの整合性
npm run build                                   # ビルドが通るかの確認

エージェントが作業を終えたら、この3つを実行して自分で確認する。上司が逐一チェックするのではなく、ツールの結果が「鏡」になるという考え方です。

タスクの向き不向きを明記

Agent Teams には Read-Heavy（調査・レビュー系）と Write-Heavy（同一ファイルの同時編集系）があり、前者のほうが得意だということも書いておきました。この情報があるかないかで、Claude がタスクを割り振るときの判断精度が変わります。

2. AGENT_TEAMS.md を新規作成する

CLAUDE.md は「原則と方針」、AGENT_TEAMS.md は「具体的な手順書」という位置づけです。

中身としては、環境変数の設定方法、具体的なタスク例（日英整合性チェック、SEO 監査など）、検証のワークフロー、トラブルシューティングなどを記載しました。

エージェントが迷ったときに参照できる「手引き」のようなものです。

3. 統合検証スクリプトの作成

個別のチェックコマンドをまとめて一発で実行できるスクリプトを作りました。Bash 版と PowerShell 版の両方を用意しています。

これは自分が Windows 環境で開発しているためです。エージェントがどちらの環境で実行しても動くようにしておきたかった。

4. package.json に validate コマンドを追加

{
  "validate": "npm run lint && npx tsx scripts/check-affiliate-integrity.ts && npm run build:dev",
  "validate:affiliates": "npx tsx scripts/check-affiliate-integrity.ts"
}

npm run validate の一言で全検証が走るようにしました。エージェントに「作業が終わったら npm run validate を実行してください」と伝えるだけで済むので、指示がシンプルになります。

準備を終えてみて

コミットの差分は 6 files changed, 562 insertions(+)。結構なボリュームです。

でも振り返ると、この準備にかけた時間は無駄ではなかったと断言できます。後述する実践編で、エージェントたちがかなり自律的に動いてくれたのは、この土台があったからです。

自転車に乗る感覚と同じで、最初の「漕ぎ出し」が一番重いんですが、一度整備してしまえば次からは楽になります。

実践編——22記事の一括レビューと修正

Agent Teams の起動と役割分担

準備が終わったので、いよいよ Agent Teams を実際に動かします。

まず Claude に「CI/CD カテゴリの記事は古い情報が残っている可能性がある。最新の情報にアップデートしたい」と伝えました。すると Claude が以下のようなチーム構成を提案してきました。

レビューフェーズ（4エージェント）

エージェント名	担当
metadata-analyzer	全22記事のメタデータ抽出
reviewer-1	記事グループ1（1〜7件目）のレビュー
reviewer-2	記事グループ2（8〜14件目）のレビュー
reviewer-3	記事グループ3（15〜22件目）のレビュー

22記事を3つのグループに分けて、それぞれ専任のレビュアーをつける。並列で動くので、1人で22件見るよりもずっと速い。

ここで注目したいのは、この役割分担を Claude 自身が提案してきたという点です。CLAUDE.md に「Read-Heavy なタスクは Agent Teams 向き」と書いておいたことが効いているのだと思います。人間が逐一「エージェント A は1〜7件、B は8〜14件……」と指示しなくても、方針さえ共有できていれば Claude が自分で考えて分担してくれます。

レビュー結果——見つかった問題

3人のレビュアーからの報告が揃いました。結果をまとめるとこうなります。

高優先度（5件）

• Jenkins Blue Ocean の非推奨化に未対応（3記事）
  • API 記事が非推奨 API を前提に書かれている
  • ビルド成果物の記事で Blue Ocean を推奨している
  • ログ確認方法の記事で Blue Ocean を主要な方法として紹介している
• 外部 API の破損（2記事）
  • パイプライン応用記事で参照している日時取得 API がサービス終了
  • パイプライン基礎記事で使っている画像 API が接続不能

中優先度（3件）

• Python ライブラリの互換性情報が不足（1記事）
• 旧ドキュメントサイト（wiki.jenkins.io）へのリンクが残っている（1記事）
• Jenkins 紹介記事に Blue Ocean 非推奨の情報がない（1記事）

良好（14件）

残りの14記事は現時点で問題なし。直近で更新済みの記事が複数あり、それらは最新の状態でした。

正直、Blue Ocean の非推奨化が3記事に波及しているとは思っていませんでした。1記事だけなら自分で気づいていたかもしれませんが、レビュアーが並列で全件チェックしたからこそ、影響範囲が正確に把握できたのだと思います。

修正フェーズ——ここからが本番

レビュー結果をもとに、修正フェーズに入ります。今度は3つの修正チームを編成しました。

graph LR
    subgraph 修正チーム
        F1[blue-ocean-fixer<br>Blue Ocean 非推奨対応<br>3記事]
        F2[api-fixer<br>外部 API 修正<br>2記事]
        F3[medium-priority-fixer<br>中優先度修正<br>3記事]
    end
    F1 --> V[検証]
    F2 --> V
    F3 --> V

blue-ocean-fixer の作業（成功）

3記事の Blue Ocean 関連セクションを修正しました。API 記事には非推奨の警告を追加し、代替手段を提案。ビルド成果物の記事からは Blue Ocean セクションを削除して Classic UI を強調。ログ確認方法の記事は Blue Ocean の記述を削除し、Console Output と Classic UI Pipeline Steps を推奨する形に書き換えました。

api-fixer の作業（成功）

サービスが終了した日時取得 API を worldtimeapi.org に置き換え、接続不能になった画像 API を placekitten.com に置き換えました。ビルド確認もこのエージェントが自分でやっています。

medium-priority-fixer の作業（失敗）

ここ、罠です。

medium-priority-fixer がいつまで経っても応答を返してこなかったんです。しばらく待ってから「何か困ってる？」と聞いてみましたが、反応なし。

うまくいかなかったこと——エージェントの「無応答」問題

何が起きたか

medium-priority-fixer というエージェントに中優先度の3記事修正を任せたところ、応答がありませんでした。

「応答がない」というのは、エラーが返ってくるわけでもなく、ただ沈黙するという状態です。タイムアウトのメッセージも出ない。何が起きているのかが外からはわからない。

最初の対処（失敗）

新しいエージェント（medium-priority-fixer-2）を立ち上げてタスクを引き継ぎました。しかし、これも同じく無応答。

このとき、2回目の失敗で「同じやり方を繰り返しても駄目だ」と判断しました。

方針転換——タスクを分割する

3記事を1人に任せるのではなく、1記事ずつ別のエージェントに任せる方針に切り替えました。

エージェント	担当記事	修正内容
fixer-disable-job	ジョブ無効化の記事	Python ライブラリ互換性情報の追加
fixer-stop-build	ビルド停止の記事	旧ドキュメントリンクの更新
fixer-what-is-jenkins	Jenkins 紹介記事	Blue Ocean 保守モード注記の追加

結果、3つとも問題なく完了しました。

この失敗から学んだこと

なぜ medium-priority-fixer が無応答になったのか、正確な原因は今もわかりません。Agent Teams はまだ実験的な機能なので、こういった不安定さは残っています。

ただ、ここで重要なのは「エージェントが失敗する可能性を前提に設計しておく」ことです。

今回の場合、タスクを3つに分割できたのは、もともとの修正内容が記事ごとに独立していたからです。もし1つの大きな修正タスク（たとえば全記事の frontmatter を一括変換するような作業）だったら、こう簡単には分割できなかったでしょう。

これは以前の記事で書いた「Read-Heavy なタスクを優先する」という原則にも通じます。修正作業であっても、記事ごとに独立している＝疎結合であれば、分割して再実行できる。密結合な書き込みタスクだと、失敗時のリカバリが難しくなります。

最終検証と成果

検証結果

全8記事の修正が完了した後、準備段階で仕込んでおいた検証コマンドを実行しました。

npm run lint          # → 既存のlintエラーのみ（今回の修正とは無関係）
npm run validate:affiliates  # → 既存の問題のみ
npm run build:dev     # → ビルド成功

今回の修正によって新たなエラーは発生していません。ビルドも問題なく通りました。

準備段階で npm run validate を整備しておいたおかげで、この確認がスムーズにできました。もし検証コマンドがバラバラのままだったら、何を実行すればいいのかをいちいち思い出す必要があったはずです。

成果のまとめ

項目	数値
レビュー対象	22記事
修正した記事	8記事
投入したエージェント	レビュー4体 + 修正5体（失敗した2体含む）

修正内容の内訳は以下のとおりです。

• Blue Ocean 非推奨対応（3記事）：非推奨警告追加、代替手段への書き換え
• 外部 API 破損の修正（2記事）：動作する API への置き換え
• ドキュメントリンク更新（1記事）：旧サイトから現行サイトへ
• 互換性情報追加（1記事）：Python ライブラリの対応状況を明記
• Blue Ocean 保守モード注記追加（1記事）：現在の状況を反映

振り返り——理論と実践のあいだ

以前の記事で書いた仮説は正しかったか

以前の記事で提唱した考え方と、今回の実践結果を照らし合わせてみます。

「CLAUDE.md は MVV にあたる」→ 正しかった

CLAUDE.md に方針を書いておいたことで、エージェントの自律的な判断精度が明らかに上がりました。特にタスクの分担を Claude 自身が提案してくれたのは、MVV が機能している証拠だと感じます。

「テストスイートは行動指針の具体化」→ 正しかった

npm run validate があることで、エージェントが作業後に自己検証できました。上司がチェックするのではなく、ツールが品質を担保するという仕組みは、Agent Teams との相性がとても良いです。

「Read-Heavy なタスクが得意」→ 正しかった

22記事の並列レビューはスムーズでした。一方で、修正（Write）フェーズではエージェントの無応答が発生しています。タスクの性質による向き不向きは、確かに存在します。

「最小限のルール、最大限の裁量」→ おおむね正しいが、補足が必要

原則だけ示して細かい手順を書かなかったことで、エージェントが柔軟に動いてくれました。ただし「失敗したときのリカバリ手順」は、もう少し具体的に書いておいてもよかったかもしれません。

もう少し改善できそうなこと

エージェントの健全性チェック

今回、無応答エージェントの検知が遅れました。「一定時間応答がなければ自動で代替エージェントを立てる」みたいな仕組みがあると、もっとスムーズに進められたはずです。これは Agent Teams 自体の機能改善に期待したいところでもありますし、CLAUDE.md 側でリトライ方針を書いておくことでも多少は対応できそうです。

修正タスクの粒度設計

最初から「1エージェント1記事」にしておけば、medium-priority-fixer の問題は起きなかった可能性があります。タスクの粒度は「失敗しても再実行しやすいサイズ」を意識すべきだという学びがありました。

まとめ

改めて、この記事で一番伝えたかったことを繰り返します。

Agent Teams は「使い始める前の準備」で成果の8割が決まる。

CLAUDE.md に方針を書く。テストスイートを整備する。検証コマンドを一本にまとめる。こうした地味な準備が、エージェントの自律性を支えます。

一方で、エージェントは万能ではありません。無応答になることもあるし、想定外の挙動をすることもある。だからこそ「タスクを疎結合に設計する」「失敗しても再実行できるサイズにする」という設計思想が大事です。

Agent Teams はまだ実験的な機能ですが、使い方次第で確実に生産性を上げてくれるツールだと実感しました。以前の記事で書いた組織論の話は、決して机上の空論ではなかったなと。パズルのピースがもう一つはまったような気持ちです。

次は、もう少し規模の大きなタスク——たとえばブログ全体のアクセシビリティ監査など——で Agent Teams を試してみたいと考えています。

参考書籍

AI エージェントについてさらに深く学びたい方へ、以下の書籍をご紹介します。開発から運用、実践的な活用方法まで、この記事で扱ったテーマをより深く理解する助けになります。

[📦 商品リンク: moshimo-card-tpujl]

[📦 商品リンク: moshimo-card-19J42]

[📦 商品リンク: moshimo-card-tP9XC]