はじめに

TEI/XMLで構造化された歴史史料をWeb上で閲覧できるビューアを、Nuxt 2 + Vue 2 + Vuetifyで開発しています。このプロジェクトに報告された6件のGitHub Issueに対して、Claude Codeのworktree機能とagentを活用して並行対応した記録を紹介します。

対応したIssue一覧

グループIssue数内容優先度
A3件テキストビューワの入れ子要素の表示不具合高
B1件凡例ページのインデント未反映中
C1件分析ページのリンク切れ高
D1件キーワード検索のクラッシュ高

アプローチ：worktree × 並行agent

Claude Codeには、git worktreeを使って独立した作業環境で複数のagentを並行実行する機能があります。今回は上記4グループに対して、4つのagentを同時に起動しました。

各agentがworktreeで独立して作業するため、互いに干渉せず並行して修正を進められます。

Agent 1: fix/nested-tags     → グループA（3件、同一の根本原因）
Agent 2: fix/legend-indent   → グループB
Agent 3: fix/analytics-links → グループC
Agent 4: fix/keyword-search  → グループD

各Issueの修正内容

グループD：検索プラグインのクラッシュ

原因: 検索プラグイン内で、環境変数から読み込む設定値がundefinedのため、検索実行時にTypeErrorでクラッシュしていました。

修正: 1行のnullガード追加で解決しました。最もシンプルな修正でしたが、agentが原因を正確に特定してくれました。

グループA：入れ子要素の表示不具合

3件のIssueは一見別々の問題に見えましたが、すべて共通の根本原因を持っていました。

原因: TEI XMLの前処理スクリプトが、入れ子構造の要素を正しく変換していませんでした。具体的には、テキスト範囲を示すアンカーペアを要素に変換する処理で、入れ子になった内側の要素がフィルタリングで除外されていたため、テキストやクリック可能な注釈が失われていました。

修正: 前処理スクリプトに3つの変更を加えました。

  1. 内側の要素から順に処理: 範囲サイズ昇順でソートし、内側から外側へ処理するよう変更
  2. 混合コンテンツの組み立てバグ修正: BeautifulSoupのNavigableStringを使用し、タグと文字列が混在する場合のデータ消失を防止
  3. ネスト深度の属性を再設定: 変換後に祖先要素の数を数えて属性値を設定（ビューア側で色を変えて表示するために必要）

agentの初回修正はビューア側（Vue.jsコンポーネント）の変更でしたが、実際にはデータ変換パイプライン（Pythonスクリプト）の修正が本質的な解決でした。agentの結果を検証した上で、手動で根本原因を追跡し直しました。

グループB：凡例ページのインデント

原因: 2つの問題が重なっていました。

  1. Vue.jsコンポーネントがDOM操作でスタイル属性を変換していたが、outerHTML → JSON変換で反映されなかった
  2. TEIソースリポジトリの最新版でCSSプロパティ名が変更されており、ローカルの古いデータでは動くがCI環境では動かなかった

修正: JSON変換後にスタイルを解決するよう変更し、新旧両方のCSSプロパティに対応しました。

この問題は、ローカルとCI環境のデータ差異という根本原因の発見まで時間がかかりました。

グループC：分析ページのリンク切れ

原因: リンク先のページファイルが存在しませんでした。

修正: agentが2つの新規ページを作成しました。ただし多言語対応（i18nキーの登録）やレイアウトの統一が不十分だったため、手動で追加修正を行いました。

確立したワークフロー

今回の対応を通じて、以下のワークフローを確立しました。

  1. ブランチ作成: fix/issue-descriptionブランチをdevから切る
  2. データソース更新: 外部リポジトリのデータをgit pullで最新にする
  3. ローカル確認: ブランチをcheckout → npm run dev → ブラウザで動作確認
  4. devマージ＆push: 確認OKならdevにマージしてpush（CIで自動デプロイ）
  5. 検証環境で確認: デプロイされた環境で動作確認
  6. Issueに確認依頼: assigneeを追加し、確認方法をコメント
  7. クローズ: 第三者の確認後にクローズ

GitHub Projectsによる進捗管理

GitHub Projects V2を導入し、Todo → In Progress → レビュー待ち → Doneの4ステータスでIssueのフェーズを管理するようにしました。

得られた教訓

1. ローカルとCI環境のデータ差異に注意

外部リポジトリのデータがCIでは最新版を使うのに対し、ローカルが古いままだったことで、「ローカルでは動くがデプロイ環境では動かない」という問題が発生しました。作業前にデータソースを最新にすることをワークフローに組み込みました。

2. Issueのクローズは第三者確認後に

当初、agentが修正と同時にIssueをクローズしてしまいましたが、修正者本人ではなく第三者が確認してからクローズすべきです。これは品質管理の基本ですが、AIツールに任せると見落としがちなポイントです。

3. worktreeによる並行作業は効果的

4つのagentが独立したworktreeで同時に作業することで、効率的に修正を進められました。ただし、agentの修正が不十分な場合は手動での追加修正が必要になるため、agentの結果は必ず検証が必要です。

4. 根本原因の特定が重要

グループAの3件は一見別々の問題に見えましたが、すべてデータ変換パイプラインの同一箇所に起因していました。agentはビューア側の修正を提案しましたが、実際にはデータ変換の修正が本質的な解決でした。AIの提案を鵜呑みにせず、根本原因を追跡する姿勢が重要です。

5. CIの挙動も確認する

デプロイが正しく行われたかの確認も重要です。今回、CIジョブがキャンセルされていたために修正がデプロイされていないケースがありました。

まとめ

Claude Codeのworktreeとagent機能を活用することで、6件のIssueを効率的に並行対応できました。一方で、agentの出力の検証、ローカル・CI間のデータ整合性の確認、第三者レビューのプロセスなど、人間による確認が不可欠な部分も明らかになりました。

なお、本記事で紹介した方法は2026年3月時点でのアプローチです。Claude Codeにはco-worksをはじめとする新機能が続々と追加されており、並行作業やレビューのあり方も変わりつつあります。ツールの進化に合わせて、ワークフロー自体も継続的に見直していく必要があります。