Search

Git Worktree로 AI 병렬 개발하기 - Jina

subtitle
Tags
AI
git
Created
2026/01/25
2 more properties

동시적 X 병렬적 O

AI Agent에게 일을 시키고 작업이 다 끝날 때까지 멍 때린 적 있으셨나요?
AI에게 일을 시키는 동안 다른 AI에게 일을 시키면 어떨까요? 같은 시간에 N개의 이슈를 처리할 수 있지 않을까요?
Git Worktree를 사용하면 같은 레포에서 동시에 여러 Agent에게 병렬로 작업을 시킬 수 있습니다.
일해라 기계들아!

Git Worktree란?

Git으로 버전 관리를 하며 작업을 하다 보면 동시에 여러 개의 작업 트리를 이동해야 할 일이 생깁니다. 예를 들어 A 브랜치와 B 브랜치 두개를 동시 작업중이면서 갑자기 버그가 발견되어 핫픽스 해야 할 일이 생길 수도 있습니다. 보통은 git stash를 쓰거나 임시 커밋 같은 방식으로 하던 일을 저장해두고 브랜치를 이동합니다.
작업을 잠시 중단하고 다른 작업으로 바꾼다는 것은 아주 번거로운 일입니다. 그 밖에도 IDE의 indexing을 기다리는 시간 등 시간적 소요도 많고 일이 끝난 후 돌아왔을 때 어디까지 했는지 다시 기억을 되살려야 하는 것도 번거롭습니다. Stash를 여러 개 해둔 경우 어떤게 무슨 작업이였는지 헷갈리는 경우도 많습니다.
git worktree는 이런 상황에서 유용하게 사용할 수 있는 명령어로, 여러 개의 작업 디렉토리(a.k.a. 워킹 트리 또는 워크 트리)를 관리할 수 있도록 돕습니다.
일반적으로 git을 사용하면서 어떠한 작업의 단위로 branch를 나누어 개발하게 됩니다. 반면 git worktree는 특정한 작업을 별도의 워크 트리로 분리해 별도로 관리할 수 있게 해줍니다.

사용법

1.
프로젝트 루트로 이동합니다.
2.
아래 명령어를 실행합니다.
git worktree add ../<repo-name>-<new-branch-name>
Plain Text
복사
1.
현재 레포의 상위에 <repo-name>-<new-branch-name> 의 작업 디렉토리가 새로 생깁니다.
2.
각 작업 공간마다 분리된 브랜치를 가지므로 개별적으로 작업하면 됩니다.

그래서 어떨 때 사용하나요?

예시 1: 긴급 핫픽스

•
main에서 작업 중
•
갑자기 hotfix 필요
•
worktree로 hotfix 열고 바로 수정

예시 2: 모노레포 / 실험 브랜치

•
apps/web → main
•
apps/web-experiment → 실험 브랜치
•
서로 영향 없이 동시에 실행 가능

예시 3: AI Agent에게 병렬로 일 시키기

•
토큰을 2배로 써봅시다 ㅎㅎㅎ

AI Agent에게 병렬로 일 시키기

Context Engineering

AI Agent에게 일을 시키기 전에 먼저 Context Engineering부터 배워봅시다.
병렬로 일을 시킬 때 코드는 더 많이, 빠르게 변화합니다.
그리고 Agent는 다른 Agent의 작업에 의해 변경된 코드에 대한 맥락이 필요합니다.
Context Engineering이란 LLM(Learning Leadership Model)이 작업을 해결할 수 있도록 모든 컨텍스트를 제공하는 기술이다. - tobi lutke (Shopify CEO)
에이전트의 등장으로 "제한된 작업 메모리"에 어떤 정보를 로드하는지가 더욱 중요해졌습니다. 에이전트의 성공 여부를 결정짓는 핵심 요소는 에이전트에게 제공하는 컨텍스트의 질이라는 점이 분명해지고 있습니다. 이제 대부분의 에이전트 실패는 모델 자체의 실패가 아니라 컨텍스트의 실패에서 비롯됩니다.
•
지침/시스템 프롬프트: 대화 중 모델의 동작 방식을 정의하는 초기 지침 세트로, 예시, 규칙 등을 포함할 수 있으며 포함해야 합니다.
•
사용자 프롬프트: 사용자가 즉시 수행해야 하는 작업 또는 질문.
•
상태/이력(단기 기억): 현재 대화 내용(사용자 및 모델 응답 포함).
•
장기 기억: 여러 차례의 이전 대화를 통해 축적된 지속적인 지식 기반으로, 학습된 사용자 선호도, 과거 프로젝트 요약 또는 향후 사용을 위해 기억해야 한다고 전달받은 사실 등을 포함합니다.
•
검색된 정보(RAG): 특정 질문에 답하기 위해 문서, 데이터베이스 또는 API에서 가져온 외부의 최신 관련 정보.
•
사용 가능한 도구: 호출할 수 있는 모든 함수 또는 내장 도구에 대한 정의(예: check_inventory, send_email).
•
구조화된 출력: 모델 응답 형식에 대한 정의(예: JSON 객체)

왜 Context가 중요할까요?

단적인 예로, Deep-Tools(Jira X Tempo 자동화 앱)를 개발할 때, 프롬프팅하는 날짜 그리고 대화에 대한 맥락 등이 없어서 엉뚱한 날짜에 엉뚱한 이슈를 생성하곤 했습니다.
에이전트 구축은 작성하는 코드나 사용하는 프레임워크에 관한 것이 아닙니다. 저렴한 데모와 "마법 같은" 에이전트의 차이는 ‘컨텍스트의 품질’에 달려 있습니다. 간단한 이메일을 기반으로 회의 일정을 잡도록 AI Agent에게 요청한다고 상상해 보세요.
안녕하세요, 내일 간단한 동기화 작업 때문에 시간 되시는지 확인차 연락드렸습니다.
"저렴한 데모" 에이전트는 맥락 정보가 부족합니다. 사용자의 요청만 볼 뿐 다른 정보는 전혀 인식하지 못합니다. 코드는 LLM을 호출하고 응답을 받는 등 완벽하게 작동할 수 있지만, 출력 결과는 도움이 되지 않고 기계적입니다.
메시지 감사합니다. 내일은 괜찮습니다. 몇 시쯤이신지 여쭤봐도 될까요?
"마법의" 에이전트 는 풍부한 컨텍스트 정보를 기반으로 작동합니다. 코드의 주요 역할은 응답 방법을 파악하는 것이 아니라 , LLM이 목표를 달성하는 데 필요한 정보를 수집하는 것 입니다. LLM을 호출하기 전에 컨텍스트를 확장하여 필요한 정보를 포함시켜야 합니다.
•
캘린더 정보(예약이 꽉 찼음을 보여줍니다).
•
(적절한 비공식적 어조를 판단하기 위해) 이 사람과 주고받았던 이전 이메일을 확인해 보세요.
•
(핵심 파트너를 파악하기 위한) 연락처 목록.
•
초대 또는 이메일 전송 도구.
그런 다음 응답을 생성할 수 있습니다.
짐, 안녕! 내일은 내 일정이 꽉 차서 하루 종일 쉴 틈이 없어. 목요일 오전은 괜찮은데? 초대장 보냈으니까 괜찮으면 알려줘.
마법은 더 똑똑한 모델이나 더 정교한 알고리즘에 있는 것이 아닙니다. 올바른 작업에 적합한 맥락을 제공하는 데 있습니다. 이것이 바로 컨텍스트 엔지니어링이 중요한 이유입니다. 에이전트의 실패는 단순히 모델 실패가 아니라 컨텍스트 실패이기도 합니다.

Memory Bank

Memory Bank는 Cursor 같은 AI 코딩 에이전트가 세션이 리셋될 때마다 프로젝트 맥락을 완전히 잃어버리는 문제를 해결하기 위한 문서 시스템입니다.
왜 이런 구조가 필요할까요?
일반적인 문제 상황을 보면:
•
AI에게 “이 프로젝트는 이런 구조야”라고 설명함
•
다음 날 다시 열면 → 전부 날아감
•
잘못된 가정으로 코드 작성
•
아키텍처 붕괴, 반복 설명, 생산성 하락
Memory Bank는 이를 방지하기 위해:
•
사람의 머릿속에만 있는 맥락을 문서로 고정
•
AI가 항상 같은 이해 상태에서 시작하도록 만듦
“AI 온보딩 문서 + 진행 상황판 + 기술 결정 기록”을 합친 것입니다.
memory bank는 이런 구조로 맥락을 문서화시킵니다.
projectbrief.md ← 최상위 (절대적 기준) ├─ productContext.md ← 왜 만드는가 ├─ systemPatterns.md ← 어떻게 설계했는가 ├─ techContext.md ← 무엇으로 만들고 있는가 └─ activeContext.md ← 지금 뭘 하고 있는가 └─ progress.md ← 현재 상태 요약
Plain Text
복사
memory bank 세팅 방법
•
GitHub - tacticlaunch/cursor-bank: Cursor memory bank feature like in Cline - Plan, Act, Update memory bank를 세팅하는 방법은 이 문서를 참고하세요
•
cursor가 아니더라도 .cursor/rules를 복사하여 claude-code에도 똑같이 적용 가능합니다.
memory bank 업데이트 방법
아래 명령어를 프롬프트하면 현재 레포의 memory-bank 폴더에 문서가 올라갑니다.
update memory bank
Plain Text
복사
Plan & Act Rule로 작업 명세서와 서브 테스크 명세서를 작성하세요!
명세서와 계획서 같은 문서를 작성하는 행위는 '계획'에 해당됩니다. 코드를 작성하는 행위는 '실행'이 되죠. 이에 문서를 잘 작성하기 위해 계획과 실행을 명확히 분리하는 것이 좋습니다. 하지만 AI IDE를 이용할 땐 보통 이를 분리하기 어렵습니다. 설계를 위한 논의 중에 AI IDE는 종종 혹은 자주 코드를 반영하죠. 이에 보통 '채팅에서만 먼저 논의하자', '코드를 먼저 작성하지 말아줘' 혹은 '채팅에서만 적용된 코드를 보여줘'와 같은 프롬프트를 추가했었죠. Memory Bank에선 이를 해결 하는 방법으로 PLAN and ACT cursor rule를 도입했습니다. 이 규칙을 도입하면 채팅 컨텍스트에서 'ACT'라고 명시적으로 말하기 전까진, 'PLAN' 모드이기 때문에, 코드 작업을 하지 않습니다. PLAN 모드에서 작업 명세서를 바탕하여 Agent와 함께 서브 테스크 명세서(코드 작업 계획서)를 만들고 이를 Jira나 Notion MCP를 사용해서 저장하세요.
PLAN and ACT rule은 always 모드로 적용 했습니다. always 모드를 사용하면 이 Repository를 적용하는 모든 개발자에게 적용되기에 조심스러웠지만, 빠르게 실험하고 검증하는 것이 중요하기에 팀과 논의 후 적용하면 될 것 같아요.
Plan & Act Rule은 memory bank의 cursor rules에 이미 적용되어있습니다.

Linear, Confluence, Notion을 활용한 Context Engineering

작업을 시킬 때는 무작정 시키지 않고 Plan 먼저 짭니다.
memory bank rule이 적용되어있다면 ‘실행해’라고 하기 전까지는 작업하지 않습니다.
채널톡에서는 linear를 사용했지만 우리 회사에서는 Confluence를 사용했기 때문에 이를 context 제공에 사용했습니다.

세팅 방법

{ "mcpServers": { "mcp-atlassian": { "command": "uvx", "args": ["mcp-atlassian"], "env": { "JIRA_URL": "https://koreadeep.atlassian.net/", "JIRA_USERNAME": "koreadeep65@gmail.com", "JIRA_API_TOKEN": "<비밀>", "CONFLUENCE_URL": "https://koreadeep.atlassian.net/wiki", "CONFLUENCE_USERNAME": "koreadeep65@gmail.com", "CONFLUENCE_API_TOKEN": "<비밀>" } } } }
Plain Text
복사

적용 방법

1.
먼저 AI Agent와 함께 Plan 모드로 전체적인 Task들을 뽑아냅니다.
2.
Memory Bank에 업데이트하세요. Confluence MCP(mcp-atlassian)를 사용해서 업데이트 해주세요.
3.
해당 작업이 메모리 뱅크에 올라가면 Agent들은 작업 사항에 대해 공유 받습니다.
4.
각 Task들에 대한 Sub Task 작업을 AI Agent와 함께 정의해주세요.
5.
이 Sub Task를 토대로 worktree에서 Agent들이 작업을 시킵니다.

Git Worktree로 AI Agent에게 병렬로 작업시키기

적용 방법

1.
AI와 함께 병렬 작업할 Task들을 정리합니다.
2.
Confluence MCP를 사용해서 Task들을 각 문서로 생성합니다.
3.
AI와 함께 각 Task 페이지에서 SubTask 명세서를 작성합니다.
4.
첫번째 Worktree를 파서 AI Agent에게 SubTask 명세서를 전달합니다.
5.
…N번째 Worktree를 파서 AI Agent에게 SubTask 명세서를 전달합니다.

Tips

Worktree 생성 팁

Development 브랜치에서 커서와 함께 작업하지 말고 Git worktree를 파서 작업하길 권장합니다. worktree는 Development 브랜치에서 만들어야 하는데, 해당 브랜치가 작업중이면 새 worktree를 만들기가 어렵습니다.
즉, 베이스 브랜치는 그대로 두고 worktree를 개별적으로 만들어야 합니다.

1. 웹 서버가 같은 포트에 뜨는 문제

그림1과 2는 서로 다른 worktree입니다. 동시에 테스트를 실행하면 그림 1은 통과하되 그림 2는 서버 조차 뜨지 못했습니다. 그림 3과 같은 상황이라고 볼 수 있습니다. 이는 간단하게 해결할 수 있습니다. 테스트를 실행 할 때 웹서버가 올라오는 포트를 랜덤으로 설정하면 됩니다.

2. 테스트 DB가 이미 포트를 점유하고 있는 문제

테스트 DB 포트가 같은 것 또한 문제가 될 수 있습니다. 서로 다른 worktree에서 병렬로 실행했을 때 일부 테스트는 통과하고 일부 테스트는 성공합니다. 타이밍 이슈로 테스트가 부분적으로 통과하게 됩니다.
테스트용 DB가 랜덤 포트에서 뜨도록 설정하여 해결할 수 있습니다.

Git Worktree 사용 후기

핫픽스를 해야할 일이 있을 때에도 기존에 작업하던 브랜치를 전환할 필요가 없습니다.
기존 브랜치에서 AI를 돌리고 핫픽스 브랜치에서 작업한 뒤, 다시 기존 브랜치로 돌아와 AI 코드 리뷰를 하고.
이런 식으로 시간을 효율적으로 사용할 수 있어서 좋았습니다.
다만, 같은 파일을 수정해야하는 경우 conflict가 걱정되어 쉽게 사용하지는 못해 그 점은 아쉬웠습니다.

References

Made with