홈 레포(Home Repo) 패턴
TMThttps://www.aihero.dev/the-home-repo-pattern#the-problem-it-solves
스킬, AGENTS.md, 공유 문서를 레포 하나에 모으고 나머지 레포는 포인터로 가리킵니다. 복사해서 쓸 수 있는 설정 프롬프트를 담은 레퍼런스입니다.
홈 레포(Home Repo)는 스킬, AGENTS.md, 공유 문서를 한곳에 담는 레포지토리 하나를 말합니다. 에이전트는 홈 레포에서 실행합니다. 홈 레포의 AGENTS.md에는 다른 레포마다 그 위치를 알려 주는 내비게이션 포인터가 들어 있어서, 에이전트가 필요할 때 해당 레포를 열거나 클론할 수 있습니다.
해결하는 문제
프로젝트가 여러 레포에 걸쳐 있으면, 그중 한 레포에서 시작한 에이전트는 그 레포밖에 보지 못합니다. 결국 레포마다 스킬과 에이전트 설정을 따로 복사해 두게 되고, 여러 레포에 걸친 기능을 계획할 때는 전체 그림을 보지 못한 채 작업하게 됩니다.
홈 레포를 두면 다음을 얻습니다.
- 에이전트를 이끄는 파일(steering file)과 도구를 한곳에 모을 수 있습니다
- 모든 에이전트를 한곳에서 실행할 수 있습니다
- 여러 레포에 걸친 대규모 변경을 세션 하나에서 할 수 있습니다
설정하기
레포들이 모여 있는 폴더에서 코딩 에이전트의 새 세션을 열고 아래 프롬프트를 붙여 넣으십시오. 에이전트가 레포와 그 안의 스킬을 직접 찾아내고, 결정할 사항을 여러 차례에 걸쳐 꼼꼼히 캐묻습니다(grilling). 여러분이 계획을 승인하기 전까지는 아무것도 바꾸지 않습니다.
나와 함께 홈 레포를 설정해 주세요. 홈 레포는 공유 스킬, AGENTS.md, 공유
문서를 담고 다른 레포들을 가리키는 git 레포 하나입니다. 앞으로 에이전트는
여기서 실행합니다.
## 작업 방식
- 사실 정보는 전부 직접 찾아보세요(파일 시스템, git, gh). 넓게 뒤져야 하면
서브에이전트를 쓰세요. 나에게는 결정할 사항만 가져오세요.
- 결정할 사항은 여러 차례로 나눠서 물어보세요. 질문마다 번호를 매기고, 추천
답을 함께 제시하고, "예"라고만 하면 그 추천을 받아들이는 것이 되도록 써
주세요. 아직 답이 나지 않은 질문에 달린 질문은 다음 차례로 미루세요.
- 3단계에서 내가 계획을 승인하기 전까지는 읽기만 하세요.
- 비밀 정보는 있는 자리에 그대로 둡니다. .env 같은 비밀 파일은 읽지 마세요.
## 1단계: 레포 목록 만들기
홈 디렉터리 아래에 있는 git 레포를 모두 찾되, 의존성 폴더는 건너뛰세요.
레포마다 경로, 원격 저장소, 공개 여부(public 또는 private), 마지막 커밋
날짜를 기록하세요.
첫 번째 차례에서는 다음을 물어보세요.
- 홈 레포가 어떤 레포들을 가리킬지 (최근 커밋이 있는 레포를 추천)
- 홈 레포를 어디에 둘지, 새로 만들지 기존 레포를 쓸지 (다른 레포들 옆에 새
private 레포를 추천)
- 개인용인지, 팀과 공유할지
- 내 하네스가 세션을 시작할 때 어떤 파일을 불러오는지: AGENTS.md, CLAUDE.md,
또는 둘 다 (내 설정에 드러난 쪽을 추천)
찾아낸 레포마다 포함 여부가 정해지고 나머지 세 질문에 답이 나오면 끝입니다.
## 2단계: 공유 자료 목록 만들기
선택한 레포들과 사용자 수준 스킬 폴더(예: ~/.claude/skills)를 통틀어, 모든
스킬(SKILL.md가 들어 있는 폴더), 모든 AGENTS.md와 CLAUDE.md, 그리고
에이전트를 위해 쓴 모든 문서(코딩 표준, 용어집, ADR)를 나열하세요.
각 항목을 다음 분류 중 하나에 넣으세요.
- 공유: 여러 레포에 두루 해당하는 것
- 중복: 같은 항목이 여러 곳에 있는 것. 사본끼리 diff를 떠서 가장 최신본을
표시하세요
- 레포 전용: 한 레포의 코드, 명령, 도메인에 관한 것
- 설치됨: 공개된 스킬 레포나 마켓플레이스에서 설치한 것
모든 항목이 정확히 한 분류에 들어가면 끝입니다.
## 3단계: 계획 합의하기
모든 항목과 현재 위치, 옮길 위치를 표로 보여 주세요.
- 공유와 중복: 홈 레포로 옮깁니다. 사본은 하나만, 가장 최신본으로
- 레포 전용: 원래 레포에 남깁니다
- 설치됨: 설치된 상태로 둡니다
표 아래에는 홈 레포의 AGENTS.md를 보여 주세요. 짧은 소개를 쓰고, 이어서
"Other Repos" 절에 레포마다 포인터를 하나씩 둡니다.
<이름> (<무엇인지>): <로컬 경로>. 없으면 <원격 저장소>에서 클론하세요.
레포에 따라 필요하면 "먼저 그 레포의 AGENTS.md를 읽으세요" 같은 힌트를
덧붙이세요. 레포가 20개쯤을 넘으면 포인터를 영역별 파일로 묶고, 그 파일들을
가리키세요.
남은 사항은 추가 차례에서 정리하세요. 내가 표와 AGENTS.md를 승인하면
끝입니다.
## 4단계: 계획 적용하기
1. 홈 레포와 그 AGENTS.md를 만드세요. 내 하네스가 다른 파일을 불러온다면, 그
파일을 AGENTS.md를 가리키는 한 줄짜리 포인터로 추가하세요.
2. 공유 항목을 하나씩 복사해 넣되, 스킬 폴더는 통째로 옮기세요.
3. 각 하위 레포에서 새 로컬 브랜치를 만들고, 홈 레포로 옮긴 사본을 지우세요.
레포 전용 자료는 남겨 둡니다.
4. 홈 레포에 커밋하세요. 푸시는 내가 결정합니다.
표의 모든 행이 적용되면 끝입니다. 행마다 결과가 어땠는지, 레포마다 만든
브랜치, 그리고 건너뛴 것이 있다면 그 이유를 보고하세요.자주 묻는 질문
담는 내용
홈 레포에는 무엇을 넣나요? 여러 레포에서 쓰는 스킬, 포인터가 담긴 AGENTS.md, 에이전트를 이끄는 파일, 그리고 코딩 표준·용어집·시스템 전체에 영향을 주는 결정 같은 공유 문서를 넣습니다. 가장 먼저 공유할 만한 문서는 코딩 표준입니다. 하나로 통일한 표준은 프로젝트가 달라도 그대로 옮겨 쓸 수 있습니다. 홈 레포에는 Markdown 파일로 된 작은 위키나 도구를 넣어 둘 수도 있습니다.
각 레포에는 무엇이 남나요? 그 레포에만 해당하는 것은 모두 남습니다. 레포 고유의 AGENTS.md, 빌드와 테스트 명령, 레포 전용 문서가 그렇습니다. 홈 레포는 그 레포를 가리키기만 합니다. 코드는 제자리에 있고, 각 레포는 자기 히스토리와 원격 저장소, 이슈 트래커를 그대로 유지합니다.
왜 ~/.claude/skills가 아니라 레포인가요? 이상적인 최종 상태는 모두가 같은 스킬을 쓰고 그 스킬을 프로젝트 안에 두는 것입니다. 사용자 폴더는 그때까지 쓰는 임시방편입니다. 홈 레포는 프로젝트이므로 스킬을 git으로 버전 관리할 수 있고, 팀이 함께 쓸 수 있습니다.
AGENTS.md인가요, CLAUDE.md인가요? 이 가이드에서는 AGENTS.md라고 부릅니다. 포인터는 여러분의 하네스가 세션을 시작할 때 불러오는 파일에 넣으면 됩니다. Claude Code는 CLAUDE.md를 불러옵니다.
내비게이션 포인터
포인터는 어떻게 생겼나요? 레포마다 한 줄씩, 레포 이름과 위치를 적습니다.
For skills, clone mattpocock/skills to ~/repos/skills.
For Sandcastle, clone mattpocock/sandcastle to ~/repos/sandcastle레포에 따라 필요하면 힌트를 덧붙입니다.
## Other Repos
Storefront (Next.js app): ~/repos/acme/storefront. Clone from git@github.com:acme/storefront.git if missing.
Payments API: ~/repos/acme/payments-api. Read its AGENTS.md before changing it.
AI Hero: ~/repos/ai/ai-hero (git pull to view latest, likely out of date)에이전트가 레포를 클론하나요, 아니면 디스크에 있는 사본을 쓰나요? 둘 다입니다. 포인터가 가리키는 경로에 레포가 이미 있으면 에이전트는 거기서 작업합니다. 없으면 그 경로에 클론합니다. 레포들을 홈 레포 안에 클론하고 gitignore로 빼 두는 방식으로 설정하는 경우도 있습니다.
여러 레포에 걸친 작업
세션은 어디서 시작하나요? 개별 레포 안이 아니라 홈 레포에서 시작합니다. 여러 레포에 걸친 기능을 꼼꼼히 따져 볼 때도 홈 레포에서 합니다.
워크트리는 어떻게 쓰나요? 레포는 한 번씩만 클론합니다. 기능마다 그 클론 안에 워크트리를 하나씩 만들면, 여러 에이전트가 한 레포에서 동시에 작업할 수 있습니다.
이슈는 어디에 올리나요? 에이전트가 모든 레포의 이슈 트래커에 접근할 수 있으므로 이슈를 한데 놓고 파악할 수 있습니다. 에이전트가 이슈마다 알맞은 곳에 올리도록 맡겨도 잘 됩니다.
팀이 홈 레포를 함께 쓸 수 있나요? 네. 팀에서는 홈 레포 자체를 공유하고, 모두가 그 안에서 에이전트를 실행합니다.
규모와 대안
레포를 몇 개까지 다룰 수 있나요? 20개 정도는 문제없습니다. 400개쯤 되면 레포마다 포인터를 하나씩 두는 방식으로는 에이전트가 고를 선택지가 너무 많아집니다. 이때는 점진적 공개(progressive disclosure)를 쓰십시오. 사업 영역마다 파일을 하나씩 두고 그 파일을 가리키게 한 뒤, 각 영역의 레포는 해당 파일에 나열합니다.
## Other Repos
Billing (invoices, payments, tax): see repos/billing.md
Storefront (web and mobile apps): see repos/storefront.md
Internal tools: see repos/internal.md레포가 수천 개에 이르면 스킬을 쓰는 곳이 너무 많아지므로, 스킬 마켓플레이스를 두는 편이 더 낫습니다.
git 서브모듈을 써야 하나요? 써도 됩니다. 레포가 5~10개라면 서브모듈 방식으로 설정해도 괜찮습니다. 서브모듈 없이 평범한 포인터만으로도 같은 일을 할 수 있습니다.
모노레포와는 어떤 관계인가요? 모노레포를 쓸 수 있다면 모노레포가 잘 맞습니다. 홈 레포는 모노레포를 쓸 수 없을 때 그 자리를 대신합니다. 예를 들어 public 레포와 private 레포가 섞여 있거나, 팀이 모노레포를 받아들이지 않을 때가 그렇습니다.
도구와 CI
CLI 같은 도구가 필요한가요? 아니요. 처음에는 AGENTS.md의 포인터와 이미 쓰고 있는 도구만으로 충분합니다. 나중에 도구가 필요해지면 홈 레포에 두기 좋습니다. 예를 들어 에이전트를 외부 서비스에 연결하는 CLI를 두고, 그 CLI에 필요한 환경 변수도 같은 레포에서 관리할 수 있습니다.
CI에서도 동작하나요? 네. 소프트웨어 팩토리(software factory)에서는 홈 레포를 샌드박스에 넣어 두면, 필요할 때마다 다른 레포를 클론합니다. 팩토리를 돌리는 코드는 홈 레포에 두거나, 홈 레포가 가리키는 레포 중 하나에 둡니다.