■ 1. Home Repoとは
- Home Repoの定義:
- スキル、AGENTS.md、共有ドキュメントを1つにまとめたリポジトリ
- エージェントはHome Repoで起動する
- AGENTS.mdには他の各リポジトリへのナビゲーションポインタを置く
- エージェントはポインタを頼りに、必要に応じて他リポジトリを開くかクローンする
■ 2. 解決する問題
- 複数リポジトリにまたがるプロジェクトの課題:
- 1つのリポジトリで起動したエージェントはそのリポジトリしか見えない
- 各リポジトリにスキルやエージェント設定のコピーが散在する
- リポジトリ横断の機能を計画する際に全体像を把握できない
- Home Repoがもたらすもの:
- ステアリングファイルとツール類を置く単一の場所
- すべてのエージェントを実行する単一の場所
- 1つのセッションから複数リポジトリへの一括変更
■ 3. セットアップ用プロンプト
- 使い方:
- リポジトリ群を含むフォルダで新しいセッションを開始し、プロンプトを貼り付ける
- エージェントがリポジトリとスキルを自ら探し、決定事項をラウンド形式でユーザーにグリルする
- ユーザーが計画を承認するまで何も変更しない
- 作業ルール:
- 事実はファイルシステム、git、ghで自ら調べ、広範な検索にはサブエージェントを使う
- ユーザーには決定事項だけを持ち込む
- 質問は番号付きで推奨回答を添え、「yes」で承認できる形にする
- 未決の質問に依存する質問は後のラウンドに回す
- .envなどの秘密情報ファイルは読まない
- Step 1 リポジトリの棚卸し:
- ホームディレクトリ配下の全gitリポジトリを依存フォルダを除いて探す
- 各リポジトリのパス、リモート、公開/非公開、最終コミット日を記録する
- 対象リポジトリの選定を問う（直近コミットのあるものを推奨）
- 配置場所と新規/既存の別を問う（他と並ぶ新規の非公開リポジトリを推奨）
- 個人用かチーム共有かを問う
- ハーネスが起動時に読むファイルがAGENTS.md、CLAUDE.md、両方のいずれかを問う
- Step 2 共有素材の棚卸し:
- 対象リポジトリとユーザーレベルのスキルフォルダから素材を列挙する
- 対象はスキル、AGENTS.md、CLAUDE.md、コーディング規約、用語集、ADRなどエージェント向け文書
- shared: リポジトリ横断で通用するもの
- duplicate: 複数箇所にある同一項目で、差分を取り最新版を特定する
- repo-specific: 1つのリポジトリのコード、コマンド、ドメインに固有のもの
- installed: 公開スキルリポジトリやマーケットプレイス由来のもの
- Step 3 計画の合意:
- 全項目の現在地と移動先を表で示す
- sharedとduplicateは最新版1部をHome Repoへ移し、repo-specificとinstalledは現状維持
- Home RepoのAGENTS.mdは短い導入と「Other Repos」セクションで構成する
- ポインタは名前、概要、ローカルパス、欠けている場合のクローン元を1行で記す
- 必要に応じて「先にそのAGENTS.mdを読む」などのヒントを添える
- 約20リポジトリを超えたら領域ごとのファイルにまとめ、そのファイルを指す
- Step 4 計画の適用:
- Home RepoとAGENTS.mdを作成し、別ファイルを読むハーネスならAGENTS.mdへの1行ポインタを置く
- 共有項目をスキルフォルダ単位で丸ごとコピーする
- 各子リポジトリでは新しいローカルブランチ上で移動済みのコピーを削除する
- Home Repoでコミットし、プッシュはユーザーの判断に委ねる
- 各行の結果、作成したブランチ、スキップした項目と理由を報告する
■ 4. Home Repoの中身
- Home Repoに置くもの:
- リポジトリ横断で使うスキル、ポインタ入りAGENTS.md、ステアリングファイル
- コーディング規約、用語集、システム全体に関わる決定などの共有ドキュメント
- Markdownの小さなwikiやツール類
- 最初に共有すべき文書:
- コーディング規約
- 1つの普遍的な規約はプロジェクトをまたいで通用する
- 各リポジトリに残すもの:
- そのリポジトリ固有のAGENTS.md、ビルド/テストコマンド、固有ドキュメント
- コードはそのまま残り、履歴、リモート、Issueトラッカーも各リポジトリが保持する
- ~/.claude/skillsではなくリポジトリにする理由:
- 理想は全員が同じスキルをプロジェクト内で使う状態
- ユーザーフォルダはそれまでの暫定措置に過ぎない
- Home Repoはプロジェクトなので、スキルをgitで版管理しチームで共有できる
- AGENTS.mdかCLAUDE.mdか:
- ハーネスがセッション開始時に読むファイルにポインタを置く
- Claude CodeはCLAUDE.mdを読む
■ 5. ナビゲーションポインタ
- ポインタの形式:
- 1リポジトリにつき1行で、リポジトリ名と所在を記す
- 例として「skillsはmattpocock/skillsを~/repos/skillsにクローンする」
- 例としてPayments APIには変更前にそのAGENTS.mdを読むというヒントを添える
- 例としてAI Heroには古い可能性があるためgit pullで最新を見るという注記を添える
- クローンか既存コピーか:
- ポインタのパスにリポジトリがあればそこで作業する
- なければそのパスにクローンする
- Home Repo内にクローンしてgitignoreする構成もある
■ 6. リポジトリ横断の作業
- セッションの起点:
- 単一リポジトリ内ではなくHome Repoで開始する
- リポジトリ横断の機能をグリルする場所でもある
- worktreeとの関係:
- 各リポジトリは1回だけクローンする
- 機能ごとにそのクローン内にworktreeを作り、複数エージェントが同一リポジトリで同時に作業する
- Issueの扱い:
- エージェントは全リポジトリのIssueトラッカーにアクセスでき、まとめて理解できる
- 各Issueを適切な場所にエージェントが起票する形で問題ない
- チームでの共有:
- チームではHome Repoこそが共有対象となる
- 全員がその中でエージェントを実行する
■ 7. 規模と代替手段
- 扱えるリポジトリ数:
- 約20リポジトリなら問題なく機能する
- 約400になると1リポジトリ1ポインタではエージェントの判断が多すぎる
- その場合はプログレッシブディスクロージャーを使い、事業領域ごとのファイルを指す
- 例としてBilling、Storefront、Internal toolsごとのファイルにリポジトリを列挙する
- 数千リポジトリ規模ではスキルの利用者が多すぎ、スキルマーケットプレイスの方が理にかなう
- git submodules:
- 使ってもよく、5〜10リポジトリならsubmodules的な構成で問題ない
- 単純なポインタでもsubmodulesなしで同じ役割を果たせる
- モノレポとの関係:
- モノレポが可能ならモノレポが適している
- 公開/非公開リポジトリが混在する場合やチームがモノレポを採用しない場合、Home Repoが代替となる
■ 8. ツールとCI
- CLIなどのツールの要否:
- 不要で、AGENTS.mdのポインタと既存ツールだけで始められる
- 後々、外部サービスとエージェントをつなぐCLIなどのツールを置く場所としてHome Repoが適する
- そのツールが必要とする環境変数も同じリポジトリで管理する
- CIでの利用:
- ソフトウェアファクトリーではHome Repoをサンドボックスに置き、必要に応じて他リポジトリをクローンする
- ファクトリーを動かすコードはHome Repoか、そのポインタ先のリポジトリに置く