analytics note
tech AI generated (Claude)

複数リポジトリで AI 開発ルールをズレなく維持する ─ analytics-note-harness の設計

複数の GitHub リポジトリで CLAUDE.md や AI エージェントルールをコピペ管理するとズレが生じます。harness リポジトリで正本を一元管理し、sync スクリプトで downstream に配布するアーキテクチャを解説します。

#Claude Code #AI #開発環境 #GitHubActions #マルチリポジトリ #DevOps

はじめに

AI エージェント（Claude Code、Codex 等）を複数のリポジトリで活用するようになると、必ず直面する問題があります。それは**「CLAUDE.md や .claude/rules/ の内容が各リポジトリでバラバラにズレていく」**という問題です。

あるリポジトリでセキュリティルールを更新しても、他のリポジトリに反映されない。フック設定を改善しても、各リポジトリを個別に手作業で更新しなければならない。こうした「コピペ運用の限界」を解決するのが、ハーネス（AI エージェントの開発ルール・品質管理を一元管理するフレームワーク）リポジトリによる一元管理です。

本記事では、analytics-note が構築した analytics-note-harness の設計思想と実装パターンを解説します。

複数リポジトリの AI ルール管理が必要になる背景

複数リポジトリで AI ルールをコピペ管理すると、以下の問題が発生します。

analytics-note/          # Hub リポジトリ
  .claude/rules/security.md   ← v2.1（最新）

flowagent/               # Product リポジトリ
  .claude/rules/security.md   ← v1.8（古い）

analytics-note-harness/  # Lab リポジトリ
  .claude/rules/security.md   ← v2.0（中間）
  • どれが正本か分からなくなる
  • セキュリティルール更新が一部リポジトリにしか反映されない
  • 新しいリポジトリを作るたびに手動コピーが必要

解決策: harness リポジトリの設計

analytics-note-harness は、AI 開発運用ハーネスの正本リポジトリです。

analytics-note-harness/
├─ base/                    # 全リポジトリ共通の骨格
│  ├─ .claude/
│  │  ├─ rules/             # 共通ルール（security, git-workflow 等）
│  │  ├─ hooks/             # 共通フック
│  │  ├─ scripts/           # フック用スクリプト
│  │  └─ skills/            # 共通スキル
│  └─ templates/
│     ├─ AGENTS.base.md
│     ├─ CLAUDE.base.md
│     └─ .cursorrules.base
├─ profiles/                # リポジトリ種別ごとの差分
│  ├─ hub/                  # Hub repo 向け overlay
│  ├─ product/              # Product repo 向け overlay
│  └─ lab/                  # Lab repo 向け overlay
└─ scripts/
   ├─ sync-harness.sh       # 特定リポジトリへ同期
   └─ sync-portfolio-local.sh  # 既知の全リポジトリへ一括反映

3層アーキテクチャ

ハーネスの設定は3層で合成されます。

base（共通骨格）
  └─ profiles/<type>/overlay（用途別差分）
       └─ .harness/overlay（各 repo 固有差分）
            └─ 最終的な CLAUDE.md / AGENTS.md を合成

各リポジトリで直接編集してよいのは .harness/overlay/** と .claude/rules/local-* だけ。共通部分の変更は必ずハーネスリポジトリを経由します。

sync の仕組み

harness.manifest.yaml

各ダウンストリームリポジトリには harness.manifest.yaml を配置します。

# harness.manifest.yaml
profile: hub   # hub / product / lab のいずれか

sync-harness.sh の動作

# 特定リポジトリへ同期
bash scripts/sync-harness.sh /path/to/target-repo

# profile を明示して同期
bash scripts/sync-harness.sh /path/to/target-repo hub

# dry-run で差分確認
bash scripts/sync-harness.sh /path/to/target-repo --dry-run

sync スクリプトは以下を自動実行します。

  1. harness.manifest.yaml から profile を読む
  2. base/.claude/** をターゲットリポジトリへ同期
  3. AGENTS.md / CLAUDE.md / .cursorrules / Copilot 指示を base + profiles/<profile>/overlay + .harness/overlay から合成・再生成
  4. 不足している local-* ルールをブートストラップ
  5. .harness/upstream/** に中央正本の snapshot を同期（drift 検出用）

全リポジトリへの一括反映

# 既知の Hub / FlowAgent / Lab の local worktree へ順に反映
bash scripts/sync-portfolio-local.sh

# 対象を限定して dry-run
bash scripts/sync-portfolio-local.sh hub flowagent --dry-run

GitHub Actions による自動 downstream sync

main への push をトリガーに、ダウンストリームリポジトリへ自動的に sync commit / PR を作成する workflow です。

# .github/workflows/downstream-sync.yml
name: downstream-sync

on:
  push:
    branches: [main]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: sync to downstream repos
        env:
          PORTFOLIO_SYNC_TOKEN: ${{ secrets.PORTFOLIO_SYNC_TOKEN }}
        run: |
          bash scripts/sync-portfolio-github.sh \
            --branch harness-sync/$(git rev-parse --short HEAD)

PORTFOLIO_SYNC_TOKEN は Hub / Product repo への push と PR 作成が可能な fine-grained token です。

予約ブランチの保護

downstream への sync は main / develop / release/* への直接 push を回避します。ハーネス側が main に merge されても、downstream の main を上書きしません。sync は必ず harness-sync/<branch> という名前で PR として作成されます。

drift 検出: verify-harness-sync

ダウンストリームリポジトリが中央正本からズレていないかを CI で自動検証します。

# base/.github/scripts/verify-harness-sync.sh
# .harness/upstream/** に保存された snapshot と現在のファイルを比較し、
# 差分があれば CI を fail させる

各ダウンストリームリポジトリには .harness/upstream/** に正本 snapshot が含まれているため、harness リポジトリへのアクセスなしに self-contained で drift を検出できます。

# .github/workflows/verify-harness-sync.yml（各 downstream repo に配置）
name: verify-harness-sync
on: [push, pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: bash .github/scripts/verify-harness-sync.sh

変更フロー

共通ルールを変更するときの正しい手順は次のとおりです。

1. analytics-note-harness で変更（base/ または profiles/）

2. smoke-test で整合確認
   bash scripts/smoke-test-sync.sh

3. dry-run で反映対象確認
   bash scripts/sync-portfolio-local.sh --dry-run

4. local repo へ反映
   bash scripts/sync-portfolio-local.sh

5. push → GitHub Actions が downstream PR を自動作成

6. 各 downstream で verify-harness-sync.yml が drift を検知

例外的に各リポジトリ側で応急修正した場合も、同じ作業セッションのうちにハーネスリポジトリへ逆流させます。

各リポジトリで直接管理するもの

ハーネスで管理するのは共通層だけです。リポジトリ固有の事情は各リポジトリ側で持ちます。

場所内容
harness.manifest.yamlどの profile を使うかの指定
.harness/overlay/**top-level 入口ファイルの repo 固有差分
.claude/rules/local-*.mdそのリポジトリ固有のルール
.claude/skills/local/**そのリポジトリ固有のスキル

この設計で解決できること

課題解決
各リポジトリのルールがバラバラになるharness の base で一元管理
新リポジトリへの手動コピーsync-harness.sh で自動 bootstrap
更新漏れGitHub Actions + verify-harness-sync で CI が fail
リポジトリ固有の差分overlay 層で管理、共通層を汚染しない

まとめ

複数リポジトリで AI エージェントを運用するとき、設定のコピペ管理は遅かれ早かれ破綻します。

analytics-note-harness が採用した設計の核心は次の3点です。

  1. 正本を1箇所に集める ─ base / profiles で共通層と用途差分を分離
  2. sync スクリプトで配布 ─ submodule ではなくコピー方式で downstream が自律動作できる
  3. CI で drift を自動検出 ─ verify-harness-sync で更新漏れを防ぐ

AI ツールの設定ファイルも、アプリケーションコードと同じように「単一の真実の源泉」から管理するアーキテクチャが長期的に機能します。組織内で複数リポジトリを運用するチームは、早い段階でこの仕組みを作っておくと後が楽になります。

関連記事