Claude Code로 여러 리포지토리를 횡단 및 병렬 운용하기

🚀 시작하며

이전 기사에서 Claude Code의 커스텀 스킬을 17개 만든 이야기를 썼습니다. 그중에서 plan 구동 (plan-driven) 이라는 운용에 대해 조금 언급했는데, 이번에는 이를 여러 리포지토리 (repository)를 횡단하며 병렬로 돌리는 운용에 대해 쓰겠습니다.

핵심 원칙은 다음과 같습니다:

• 1 repo = 1 IDE = 1 Claude를 규칙화 (동일 repo에서 세션을 나누지 않음) - 병렬 작업은 별도의 repo에서 실행 (필요하다면 동일 repo를 별도로 clone하여 물리적으로 분리) - repo 간의 연락은 plan 파일 경유
• 사상은 TOYOTA의 「자동화 (Jidoka)」 (사람이 중요한 시점에 개입) - 구현은 1줄 alias + global gitignore로 해결

🧩 전제: plan 구동과 커스텀 스킬

필자는 d-plan-*라는 커스텀 스킬군 (Claude Code 커스텀 스킬)으로 plan 파일을 관리하고 있습니다.

• 스킬 본체: dotfiles/settings/claude/.claude/skills/
• plan 템플릿: d-plan-create/templates/ (feature / bugfix / investigation 3종류)

plan은 단순한 Markdown이며, 체크박스를 하나씩 구현 → 사용자 확인 → 체크 → 다음 단계라는 흐름으로 Claude Code가 진행해 줍니다. 자세한 내용은 이전 기사를 참조하세요.

📂 전체 구성

• Obsidian vault가 plan / knowledge / daily의 마스터 저장소
• 각 리포지토리 바로 아래에 .desk라는 심볼릭 링크 (symlink)를 생성
• IDE에서 repo를 열면 .desk/plans/active/...가 보이는 상태가 됨

🔗 dotdesk의 정체 — 1줄 alias

.zshrc에 이것만 있으면 됩니다:

alias dotdesk='ln -snf ~/.dotfiles/vault .desk'

이것이 dotdesk의 전부입니다. 매우 심플합니다.

사용법

cd ~/Works/repo-A
dotdesk # .desk symlink가 생성됨
ls .desk/
...

이렇게 하면 IDE (IntelliJ IDEA / VS Code 등)에서 이 repo를 열었을 때, 왼쪽 패널에 .desk/가 나타나며 그 하위에 Obsidian vault 전체가 보이게 됩니다.

.desk를 제외하기

🙈 .gitignore_global을 사용하여 각 repo의 .gitignore에 .desk를 추가하는 것은 번거롭습니다. 그래서 global gitignore로 일괄 제외하고 있습니다.

# ~/.gitignore_global
.desk

이렇게 하면 dotdesk를 입력해도 commit에 .desk가 혼입될 걱정이 없습니다.

팀 repo의 .gitignore를 멋대로 더럽히지 않는다는 점도 은근히 중요합니다.

🔄 작업 시작 워크플로우

리포지토리에서 작업을 시작할 때의 흐름:

cd ~/Works/repo-A
git pull
dotdesk
...

작업 마지막에는 daily에 진행된 plan의 상황을 남깁니다. daily는 d-daily-start를 통해 전날 내용 전기(transcription) + 예정 사항 삽입이 실행되므로, 그곳에 진척도를 추가해 적는 방식으로 plan과 느슨하게 연동하고 있을 뿐입니다.

🚦 plan의 배치 — repo와 연결하지 않음

필자는 plan을 리포지토리와 연결하지 않습니다. 이유는 단 하나, repo를 횡단하는 태스크가 있기 때문입니다.

vault/plans/active/
├── 20260605_01_validator_plan.md
├── 20260606_01_repoA_task1_plan.md
...

명명 규칙은 YYYYMMDD_NN_description_plan.md 형식입니다. "어느 repo의 plan인가"는 plan의 내용 (영향 범위 섹션)에 적는 방침이며, 파일명은 빠르게 식별할 수 있으면 충분합니다.

템플릿 구조의 상세 내용은 feature.md를 참조하세요.

⚡ 병렬 작업의 올바른 모습

이 부분이 본 기사의 핵심입니다.

대원칙: 1 repo = 1 IDE = 1 Claude

필자는 동일한 repo를 2개의 세션으로 동시에 구동하지 않습니다.

• 하나의 repo를 여는 것은
  단 하나의 IDE 창 - 거기서 실행되는 Claude Code 도
  단 하나의 세션 - repo 간의 상호작용은
  plan 파일 경유

"병렬"의 단위는 repo이지, Claude 세션 내부가 아닙니다.

병렬의 구도

• 별도의 repo를 각각 다른 IDE에서 열어 병행 진행 - 각 세션은 자신의 plan을 진행함
• plan은 vault 상에서 공유되므로, 한쪽의 진행 상황을 다른 쪽이 참조할 수 있음

plan을 "병렬 관리"하는 의미

동일 repo 내에서 task1.md, task2.md와 같이 plan을 나누는 것은, 동시에 구동하기 위해서가 아니라:

목적	내용
논점 집중	1개의 plan에 여러 논점이 섞이면 Claude가 길을 잃음
완료의 체감	작은 단위로 completed 상태로 넘길 수 있음
중단 및 재개 용이성	d-plan-resume를 통해 쉽게 이어서 시작할 수 있음
횡단 관리	active 목록을 통해 "현재 이런 것들이 진행 중"임을 조망할 수 있음

"병렬 실행"이라기보다 "병렬 관리"의 감각에 가깝습니다. 실제로 실행하는 것은 순차적으로 합니다.

동일 repo에서 병렬로 하고 싶을 때는 "별도 clone"

"같은 repo의 태스크를 2개 병행해서 진행하고 싶다"면, 다른 디렉토리에 git clone을 추가하는 방식입니다.

~/Works/
├── repo-A/ ← 메인 작업
├── repo-A_task1/ ← 병렬 태스크 1용 (별도 clone)
...

각각 독립된 .desk / IDE / Claude 세션. "1 repo = 1 IDE = 1 Claude" 규칙이 유지되는 것이 포인트입니다.

repo 간 연계는 plan이 공유 게시판

A repo의 변경이 B repo에 영향을 주는 경우, plan 파일에 영향 범위 섹션을 작성하여 두 repo를 가로지르는 태스크로 관리합니다.

## 영향 범위
- repo-A: 변경점 (API / 스키마 / etc)
- repo-B: 필요한 추종
...

A repo 측의 Claude 세션을 닫고, B repo의 IDE를 다시 열어, 동일한 plan 파일을 참조하며 이어서 진행하는 흐름입니다.

Slack이나 구두 메모가 아닌, Markdown 파일이 정보 전달 수단이 됩니다. 템플릿 상세 내용은 feature.md를 참조하세요.

🛠️ 다른 AI 에이전트 오케스트레이터(Orchestrator)와의 관계

유사한 영역에 TAKT와 같은 AI agent 오케스트레이터가 있습니다. 여러 AI를 workflow로 강제 실행하여 재현성을 담보하는 강력한 메커니즘입니다.

사실 필자도 TAKT 도입을 검토했습니다. 하지만 본 기사의 스타일은 alias 한 줄 + Markdown으로 끝나는 가벼움이 있고, 이미 나름대로 잘 돌아가고 있었기에, 갈아타지 않고 현재의 스타일을 유지하고 있습니다.

두 방식은 방향성이 다르므로, 용도에 맞게 설계된 것이라고 생각합니다:

• 정형화된 처리를 확실하게 돌리고 싶다 → TAKT와 같은 오케스트레이터
• 탐색적·커스텀 중시이며 사람이 요점에 개입한다 → 본 기사와 같은 plan 구동 방식

TAKT에 대해서는 저자의 해설 기사가 이해하기 쉬우니, 관심이 있다면 그쪽도 확인해 보세요.

🎁 요약

포인트	한 줄 요약
dotdesk	ln -snf ~/.dotfiles/vault .desk 한 줄 alias
배포	global gitignore에 .desk만 추가
plan 관리	repo와 결합하지 않는 YYYYMMDD_NN_*_plan.md
1 repo = 1 IDE = 1 Claude	동일 repo에서는 1개 세션만 사용
병렬 처리	별도 repo 또는 별도 clone 사용 (worktree가 아닌 물리적 분리)
repo 간 연계	plan 파일이 공유 게시판 역할

메커니즘은 한 줄의 alias, 운용은 인간의 머리로 할당합니다. 심플하지만 효과적인 운용 방식입니다.

"여러 repo, 흩어지는 plan, IDE에서 보이지 않음, AI 에이전트 계열은 무거워 보임"이라고 느끼는 분들은 꼭 한번 시도해 보세요.

여담이지만, 저는 TOYOTA의 「자동화 (Jidoka)」 사상을 좋아하며, 대체로 리뷰에 무게를 두는 편입니다. IDEA와 같은 도구로 차이점(diff)을 일일이 확인하는 것을 중요하게 여기는 것도 그 흐름의 일환입니다.

필자의 dotfiles: https://github.com/ugdark/dotfiles

관련 기사: Claude Code의 커스텀 스킬로 개인 워크플로우 17개를 자동화한 이야기

Discussion