AI 병렬 작업과 충돌 관리Parallel AI Tasks and Conflict Management
📅
들어가기 전에 🔗
AI 하나에는 검색 화면을, 다른 AI에는 검색 API를 맡겼습니다.
각자 테스트를 통과했다는데 결과를 합치니 화면은
items를 읽고 API는 results를 반환합니다.
같은 파일을 수정하지 않았으므로 Git 충돌도 나지 않습니다.
하지만 기능은 동작하지 않습니다.병렬 작업은 여러 세션을 여는 것만으로 끝나지 않습니다.
공유 계약과 담당 범위를 먼저 정하고, 변경을 격리한 뒤 통합 결과를 검증하는 과정
이 필요합니다.
이번 글에서는 검색 기능을 예제로 작업을 나누는 기준과 Git worktree 운영, 결과 통합 방법을 정리합니다.작업 분할 🔗
동시에 진행할 수 있는 것은 서로의 미완성 결과를 기다리지 않고 판단할 수 있는 작업입니다.
검색 화면과 API를 병렬로 구현하려면 입력 파라미터와 응답 구조가 먼저 정해져 있어야 합니다.
아직 응답 형식을 고르는 중이라면 API 설계를 확정한 뒤 나누는 편이 낫습니다.
합의되지 않은 경계를 두 작업이 각각 추측하면 구현 시간보다 조정 시간이 커질 수 있습니다.
| 작업 관계 | 권장 흐름 | 이유 |
|---|---|---|
| 계약이 확정된 화면과 API 구현 | 병렬 진행 | 서로 같은 입출력을 기준으로 작업 가능 |
| 응답 구조 설계와 그 구조를 쓰는 화면 | 설계 후 구현 | 앞선 결정이 다음 작업의 입력 |
| 서로 다른 모듈의 독립 버그 수정 | 병렬 진행 검토 | 공통 상태와 테스트 환경 확인 필요 |
| 같은 핵심 함수의 서로 다른 수정 | 순차 진행 또는 담당자 통합 | 변경 의도와 회귀 조건이 겹침 |
단순히 “프론트와 백엔드를 나눠”라고 요청하기보다 계약을 코드나 문서로 고정합니다.
다음은 화면과 API가 함께 따를 타입의 예시입니다.
export type SearchItem = {
id: string;
title: string;
};
export type SearchResponse = {
items: SearchItem[];
nextCursor: string | null;
};
export type SearchError = {
code: "INVALID_QUERY" | "INTERNAL_ERROR";
message: string;
};타입과 함께 요청 파라미터, 빈 결과, HTTP 상태 코드도 정합니다.
타입이 같더라도 화면은
q를 보내고 API가 query를 받으면 연결되지 않습니다.
런타임 응답이 이 계약을 따르는지도 검증해야 합니다.
입출력 계약과 기준 커밋을 정한 뒤 화면과 API를 병렬 구현하고 순차 통합과 회귀 검증으로 연결하는 작업 분할
👨💻
공유 계약이 바뀌어야 한다면 한 작업이 몰래 수정하지 말고 변경안을 통합 담당자에게 전달하도록 정합니다.
필요한 변경을 기준 코드에 반영하고 영향받는 작업이 갱신된 계약을 확인한 뒤 계속합니다.
담당 범위 🔗
각 작업에는 목표와 완료 조건 외에 수정할 파일 영역을 지정합니다.
어느 작업도 책임지지 않는 공통 파일은 통합 담당자가 관리합니다.
| 담당 | 수정 영역 예시 | 공유 경계 |
|---|---|---|
| 화면 작업 | src/features/search/, 화면 테스트 | API 계약을 소비 |
| API 작업 | 검색 라우트·서비스, API 테스트 | 같은 계약에 맞춰 응답 |
| 통합 담당 | 공유 계약, 패키지 설정, 전체 연결 | 변경 순서와 최종 검증 결정 |
package.json, lockfile, 공통 테스트 설정은 자주 겹치는 영역입니다.
의존성 추가가 필요하면 요구사항으로 남기고 한 담당자가 반영하도록 할 수 있습니다.
서로 다른 세션이 동시에 같은 설정을 고치지 않게 하는 것만으로도 조정 범위를 줄일 수 있습니다.읽기 범위까지 완전히 막을 필요는 없습니다.
API 작업이 화면의 사용 방식을 읽는 것은 도움이 됩니다.
파일을 읽을 수 있는 범위와 수정 책임 범위를 구분
해서 전달합니다.목표: 검색어 입력, 빈 결과, 오류 상태 표시
계약: src/contracts/search.ts와 합의된 q 파라미터 사용
수정: src/features/search/와 관련 화면 테스트
공유 파일: 계약·패키지 설정 변경은 제안만 전달
검증: 화면 상태 테스트와 요청 파라미터 확인
완료 보고: 결과 커밋, 변경 파일, 검증 결과, 미검증 범위worktree 격리 🔗
같은 체크아웃에서 여러 세션이 수정하면 한 세션의 변경을 다른 세션이 읽거나 덮어쓸 수 있습니다.
Git worktree는 같은 저장소에 여러 작업 디렉터리를 연결해 브랜치별 파일과 인덱스를 따로 사용할 수 있게 합니다.
Git worktree 문서↗
아래는 터미널에서 직접 관리하는 예시입니다.
공유 계약이 이미 커밋돼 있고, 브랜치 이름과 대상 경로가 아직 존재하지 않는다고 가정합니다.
먼저 현재 저장소의 변경 상태를 확인합니다.
git status --short
task_base=$(git rev-parse HEAD)
git worktree add -b ai/search-ui ../shop-search-ui "$task_base"
git worktree add -b ai/search-api ../shop-search-api "$task_base"
git worktree listtask_base는 두 작업이 출발하는 같은 커밋입니다.
현재 폴더의 미커밋 변경은 이 커밋에 포함되지 않으므로 새 worktree로 자동 전달되지 않습니다.
필요한 계약 변경이 아직 미커밋 상태라면 팀의 작업 방식에 따라 먼저 기준 상태를 준비합니다.Codex 앱은 worktree를 이용한 격리 작업 흐름을 제공합니다.
앱이 관리하는 worktree는 앱의 생성·이동·정리 기능으로 관리하고, 위 수동 명령은 별도로 운영하는 CLI 예제로 구분합니다.
Codex worktree 가이드↗
Claude Code도
--worktree로 격리된 병렬 세션을 시작하는 방법을 안내합니다.
이미 수동으로 만든 worktree를 사용한다면 각 디렉터리에서 세션을 시작하면 됩니다.
Claude Code worktree 흐름↗공유 자원 🔗
폴더가 분리돼도 개발 서버 포트와 외부 DB가 자동으로 분리되지는 않습니다.
예를 들어 두 작업이 같은 포트로 서버를 띄우면 충돌하고, 같은 테스트 데이터를 수정하면 서로의 결과에 영향을 줄 수 있습니다.
기존 프로젝트의 격리 방법에 맞춰 포트·테스트 계정·데이터 영역을 나눕니다.
worktree에서 분리되는 파일과 브랜치, 별도로 확인해야 하는 포트와 DB 및 로컬 설정의 범위
Node 프로젝트의 의존성 설치와 Git이 추적하지 않는 환경 파일도 별도로 준비해야 할 수 있습니다.
한 worktree에서 서버가 실행됐다는 이유로 다른 worktree도 준비됐다고 가정하지 않습니다.
예를 들어 화면용 서버는 3101, API 작업 확인용 서버는 3102처럼 정하고 내부 API 주소와 테스트의 기준 URL도 맞춥니다.
👍
테스트용 DB를 나눴더라도 마이그레이션 대상과 외부 API 계정이 같은지 확인합니다.
worktree는 파일 변경을 격리하는 수단이며 외부 서비스의 실행 권한이나 데이터를 격리하는 기능은 아닙니다.
결과 통합 🔗
병렬 작업이 끝나면 10편의 인계 기록처럼 결과 커밋, 기준 커밋, 변경 범위, 검증 근거를 받습니다.
통합 담당자는 공유 계약을 지켰는지 확인한 뒤 결과를 하나씩 반영합니다.
미완성 파일을 복사해서 섞기보다 변경의 단위를 식별할 수 있는 방식으로 가져옵니다.
아래는 작업별 결과가 각각 커밋 하나로 정리된 경우의 예시입니다.
앞에서 기록한
task_base와 두 작업 브랜치가 남아 있고, 각 작업은 완료돼 추가 수정하지 않는다고 가정합니다.git worktree add -b ai/search-integration ../shop-search-integration "$task_base"
task_ui_commit=$(git rev-parse ai/search-ui)
task_api_commit=$(git rev-parse ai/search-api)
git -C ../shop-search-integration cherry-pick "$task_ui_commit"
git -C ../shop-search-integration cherry-pick "$task_api_commit"cherry-pick은 지정한 커밋의 변경을 현재 브랜치에 적용합니다.
작업 결과가 여러 커밋이면 마지막 커밋만 가져와서는 이전 변경이 빠질 수 있으므로, 커밋 목록과 의존 순서를 확인하거나 팀의 merge 방식을 사용합니다.
Git cherry-pick 문서↗첫 적용이 충돌로 멈추면 다음 적용으로 넘어가지 않습니다.
의도와 계약을 확인해 해결한 뒤
git cherry-pick --continue로 이어갑니다.
적용을 취소해야 한다면 git cherry-pick --abort의 복구 범위를 확인하고 현재 적용을 중단합니다.충돌의 종류 🔗
Git 충돌 표시가 없어도 의미 충돌은 발생합니다.
본문 첫 예시처럼
items와 results가 어긋나거나, 화면이 빈 배열을 정상 결과로 보는데 API가 오류로 반환하는 경우입니다.| 충돌 | 예시 | 확인 방법 |
|---|---|---|
| 파일 충돌 | 같은 함수의 같은 줄 수정 | diff와 변경 의도 검토 |
| 계약 충돌 | 응답 필드·오류 코드 불일치 | 계약 검사와 API 소비자 테스트 |
| 환경 충돌 | 포트·테스트 데이터 공유 | 실행 주소와 데이터 격리 확인 |
| 검증 누락 | 개별 테스트만 통과 | 통합 상태에서 사용자 흐름 실행 |
🖐️
충돌을 없애기 위해 한쪽 변경을 통째로 선택하거나 테스트를 삭제하지 마십시오.
양쪽 작업의 완료 조건을 기준으로 필요한 동작을 보존하고 통합 결과에서 다시 검증합니다.
통합 검증 🔗
작업 A의 테스트는 A의 코드 상태, 작업 B의 테스트는 B의 코드 상태에 대한 근거입니다.
둘을 합친 상태에 그대로 적용되는 증명은 아닙니다.
통합 브랜치에서 계약과 실제 연결을 확인합니다.
- 화면이 합의한 요청 파라미터를 보내는지 확인합니다.
- API의 성공·빈 결과·오류 응답을 화면이 처리하는지 확인합니다.
- 관련 타입 검사와 단위·통합 테스트를 실행합니다.
- 검색 입력부터 결과 표시까지 실제 브라우저 흐름을 확인합니다.
- 통합 과정에서 바꾼 코드가 있으면 영향받는 검사를 다시 실행합니다.
목 응답으로 화면을 먼저 구현했다면 마지막 연결 검증에는 실제 테스트 API를 사용합니다.
목과 실제 응답이 같은 계약을 따르는지도 확인합니다.
현재 예시는 운영 프로젝트에 명령을 실행한 결과가 아니라 작업 순서를 설명하는 가이드입니다.
정리 조건 🔗
worktree는 결과가 보존됐고 실행 중인 세션·서버가 더 이상 사용하지 않을 때 정리합니다.
수동 worktree라면
git worktree list로 정확한 경로를 확인하고 변경과 필요한 로컬 파일을 점검한 뒤 git worktree remove를 사용합니다.
앱이 관리하는 worktree는 해당 앱의 정리 기능을 사용합니다.👨💻
Git이 무시하는 환경 파일과 테스트 산출물은 결과 커밋에 없을 수 있습니다.
정리 전에 보관할 파일이 있는지 확인하고, 미완료 작업을 정리로 해결하려고 하지 않습니다.
시간과 비용 🔗
작업 A와 B가 독립적이라면 병렬 실행 구간은 대체로 더 오래 걸린 작업에 맞춰 끝납니다.
하지만 전체 소요 시간에는 분할 준비, 각 작업의 탐색, 결과 검토, 충돌 해결과 통합 검증도 포함됩니다.
작은 수정 하나를 여러 작업으로 쪼개면 이 부대 시간이 더 클 수 있습니다.
토큰 비용도 모든 작업과 통합 담당자의 사용량을 합쳐 봅니다.
병렬 세션은 저장소 지침과 관련 코드를 각각 읽을 수 있으므로, 시간을 줄였다고 토큰까지 줄었다고 결론 내리지 않습니다.
8편의 지표처럼 완료율·사람 재작업·전체 시간·총사용량을 함께 비교합니다.
병렬 작업을 처음 적용한다면 계약이 안정적이고 수정 영역이 다른 두 작업부터 시작해 보시기 바랍니다.
통합에 쓴 시간이 얼마나 늘었는지 기록하면 팀에서 병렬화할 작업의 기준을 조정할 수 있습니다.
결론 🔗
AI 병렬 작업은 공유 계약을 먼저 정하고, 담당 범위와 작업 공간을 분리한 뒤 결과를 순차 통합하는 방식으로 운영할 수 있습니다.
worktree를 사용하더라도 포트와 DB 같은 공유 자원, Git이 표시하지 않는 의미 충돌은 따로 확인해야 합니다.
계약 확정 → 담당 범위 분리 → 작업 공간 격리 → 순차 통합 → 연결 검증
을 기본 흐름으로 삼아 보시기 바랍니다.
마지막 12편에서는 이 과정을 앞선 요청 설계·모델 선택·검증·측정과 연결해 팀의 개발 워크플로로 정리합니다.