Home Repo Pattern — 多仓 Agent 的共享方向盘仓库
What it is
Home Repo 是 Matt Pocock 提出的多仓 agent 工作方式:建一个专门的 git 仓库,存放跨项目共享的 skills、AGENTS.md 与共享文档(编码规范、词汇表、影响全局的决策记录),所有 agent 会话都从这个仓库启动。它的 AGENTS.md 里每个其他仓库占一行导航指针(名称、说明、本地路径、缺失时的 clone remote),agent 按需打开或 clone 目标仓库。代码、仓库专属文档、构建命令仍留在各自仓库;各仓库保留自己的 history、remote 与 issue tracker。
Why it matters
- 解决跨项目工作的结构性盲区:agent 从单个仓库启动时只看得到该仓库,每个仓库各自维护一份 skills 与 agent 配置副本,跨仓库功能规划失去全局视图。
- 三个直接收益:方向盘文件与工具集中一处;所有 agent 有一个统一启动点;一次会话可对多仓库做 sweeping changes。
- 与
~/.claude/skills的分工:Pocock 认为理想终态是所有人用同一套 skills 并存在项目里,用户目录只是过渡;Home Repo 是一个项目——skills 随 git 版本化,团队可共享同一份。 - 与 monorepo 的关系:monorepo 可行时优先 monorepo;Home Repo 替代那些做不到的场景——公开/私有仓库混合、团队不愿迁移到 monorepo。
Evidence across sources
来源:Matt Pocock — The Home Repo Pattern(aihero.dev,2026-11-12,含完整 setup prompt)。
- Setup 流程为四步:盘点 home 目录下所有 git 仓库(路径、remote、可见性、最后提交)→ 把共享物料分拣为 shared / duplicate(取最新版)/ repo-specific / installed 四桶 → 与用户逐轮确认搬迁表和目标 AGENTS.md → 应用(子仓库删除副本走新本地分支,push 由人决定)。全程在计划批准前只读;
.env等 secrets 保持不读。 - 规模阈值(单源经验值):约 20 个仓库直接列指针没问题;约 400 个时一仓一指针给 agent 的决策过多,改用 progressive disclosure——按业务域一域一文件(billing.md、storefront.md);数千仓库时 skills marketplace 更合适。
- 指针指向的仓库不存在时 agent 自行 clone;也有做法是把仓库 clone 进 Home Repo 并 gitignore。worktree 配套:每仓库 clone 一次,每个 feature 在其内开 worktree,允许多 agent 并行操作同一仓库。
- AGENTS.md vs CLAUDE.md:指针放在 harness 会话启动时实际加载的那个文件里(Claude Code 加载 CLAUDE.md,可加一行指向 AGENTS.md 的桩文件)。
- CI 场景:software factory 中把 Home Repo 放进 sandbox,它按需 clone 其他仓库;工厂代码本身住在 Home Repo 或它指向的仓库里。
- 工具化可选:起步只需 AGENTS.md 指针加现有工具;后续 Home Repo 适合放连接外部服务的 CLI 及配套环境变量。
Open questions
- 20 / 400 / 数千这三个规模阈值全部是 Pocock 单源经验值,无第二来源验证。
- 个人多项目场景(一人维护 N 个 side project + 一个 agent 配置生态)是否比团队场景收益更大,源未讨论。
- 与 harness 原生 skill 发现机制(
~/.claude/skills、Hermes profiles 各自的 skills/)的共存边界:Home Repo 收录后,用户目录副本是否必须清空,源只说"stays installed"针对 installed 类。 - duplicate 桶"diff 后取最新"假设了最新版即正确版,对分叉演化(同名 skill 在不同仓库各有修改)没有给出合并规则。
Related
- claude-code/what-makes-good-agents-md — 单个 AGENTS.md 的写法;Home Repo 决定它该放在哪一层
- claude-code/agents-md-as-contract — AGENTS.md 作为可版本化契约;Home Repo 把契约提升到 workspace 层
- claude-code/skills-collection — skills 存放与共享的既有讨论,Home Repo 是其仓库化方案
- claude-code/personal-agent-minimal-setup — 个人 agent 的最小配置,Home Repo 是其多项目扩展
- claude-code/large-codebase-deployment — 单仓大规模部署;Home Repo 处理的是多仓而非大仓
- claude-code/overview — Claude Code 主题地图
Pending Jean review
- claude-code/home-repo-pattern —
ai_draft单来源;建议动作:对照你自己的.agents/skills+.claude/skills软链结构判断是否已经是一个事实上的 Home Repo,再决定 keep draft / verify / merge into skills-collection。