여러 작업자에게 일을 나누는 방법

작은 쇼핑 목록 앱에 두 가지 기능이 필요합니다. 항목 필터와 목록의 CSV 내보내기입니다. 두 작업은 거의 관련이 없어 보이고, 둘이 나눠 맡으면 한 시간 대신 30분 만에 끝나지 않을까 하는 생각이 듭니다. 한 작업자는 필터를, 다른 작업자는 내보내기를 맡고, 변경 사항이 섞이지 않도록 각자 작업 폴더도 따로 둡니다. 하지만 두 기능이 목록 항목을 어떻게 이해해야 하는지는 미리 논의하지 않았습니다. 당연히 같을 거라 생각했죠.

30분 뒤 두 기능이 모두 완성됐습니다. 각자 검사는 통과했고, 병합도 충돌 없이 끝났습니다. 그런데 공통 시나리오는 작동하지 않습니다. 화면에는 필터 결과가 세 줄 보이는데, 내보낸 파일의 열은 비어 있습니다. 이유는 단순합니다. 한 작업자가 하는 김에 읽기 좋다는 이유로 completed 필드 이름을 done으로 바꿨고, 다른 작업자는 그 사실을 몰랐습니다.

작업 폴더를 나누면 파일은 분리되지만, 결정까지 합의되는 것은 아닙니다. 세 단계로 살펴보겠습니다. 먼저 일을 나눌 가치가 있는지 판단하고, 변경 영역과 공통 합의를 배분한 다음, 통합 결과를 검증해 이런 문제가 마지막에야 드러나지 않게 하겠습니다.

의존성을 확인하세요

일을 나누는 이유는 대개 두 가지입니다. 첫째, 서로 다른 영역을 독립적으로 조사하는 경우입니다. 목록이 어떻게 표시되는지와 내보내기가 무엇으로 만들어지는지를 동시에 알아볼 수 있습니다. 둘째, 경계와 검증 가능한 결과가 이미 정해진 부분을 동시에 작업하는 경우입니다. "여기는 계획, 저기는 실행, 그다음은 확인"이라고 나누는 것만으로 세 명이 필요한 것은 아닙니다. 한 세션에서 순서대로 진행할 수도 있습니다. 작은 작업이라면 작업자 한 명으로 시작하는 편이 합리적입니다.

나눌 이유가 있다면 다음 질문을 해 보세요. A의 결과가 아직 나오지 않았을 때 작업 B의 어떤 부분을 진행할 수 있을까요? B가 전적으로 A에 달려 있다면 두 단계는 순차적으로 진행됩니다. 경우에 따라 B가 독립된 부분을 미리 준비할 수는 있지만, 결과를 합치는 일은 여전히 A를 기다려야 합니다.

같은 쇼핑 목록 예시에서 세 가지 상황을 보겠습니다.

세 번째 행이 가장 흔한 함정입니다. 필터는 src/filter.js에 있고 내보내기는 src/export-csv.js에 있으니 두 부분이 독립적이라고 생각하기 쉽습니다. 파일은 다르니까요. 하지만 두 기능 모두 같은 항목과 completed 필드를 읽습니다. 글의 첫 부분에서 본 문제도 바로 이 때문에 생겼습니다. 파일이 달라도 해결되지 않았죠. 독립성은 동작과 공통 합의에 관한 것이지, 코드가 몇 개 파일에 들어 있는지에 관한 것이 아닙니다.

작업자들을 실행하지 않고, 작업 분할만 에이전트에게 맡길 수 있습니다.

작업을 여러 부분으로 나누세요. 각 부분의 입력, 결과,
의존성, 확인 방법을 적으세요. 지금 시작할 수 있는 부분도 표시하세요.
작업자는 아직 실행하지 마세요.

이런 답변은 실행 전에 검토할 수 있습니다. 해결되지 않은 의존성이 없는 부분은 동시에 시작할 후보입니다. 의존성 열이 비어 있다면 프로젝트와 대조해 보세요. 에이전트가 공통 모델이나 설정을 놓쳤을 수 있습니다.

통합 결과까지 걸리는 시간을 계산하세요

보통 속도 향상은 작업 자체에 걸린 시간 하나로 측정합니다. 하지만 계산해야 할 것은 통합 결과가 승인될 때까지의 시간입니다. 실제 작업 외에도 각 작업자에게 일을 설명하는 시간, 각자가 프로젝트를 다시 읽는 시간, 대기, 두 결과의 확인과 통합이 포함됩니다.

예시를 바탕으로 한 가상 계산입니다. 숫자는 산술을 위한 것이며 성능 측정값이 아닙니다.

공통 작업 준비는 두 방식 모두 필요하므로 계산에 넣지 않았습니다. 한 번의 재작업으로 10분의 이득이 사라집니다. 통합 비용이 클수록 병렬 작업은 더 많은 시간을 절약해야 합니다.

시간 외에도 쉽게 잊는 비용이 두 가지 더 있습니다. 작업자가 추가될 때마다 프로젝트를 다시 읽으므로 자원이 더 들고, 자세한 결과를 가져오면 공통 대화의 공간도 차지합니다. 두 번째 비용이 더 중요합니다. 바로 여러분의 주의력입니다. 두 결과를 읽고 서로 대조해 판단해야 합니다. 들어오는 내용을 제때 읽지 못한다면, 속도는 더 이상 여러분의 것이 아닙니다.

서로 비슷하고 독립적인 두 부분을 추가 비용을 적게 들여 진행한다면 거의 두 배 빨라질 수도 있습니다. 하지만 작업자 수만으로 그 결과가 보장되지는 않습니다.

중복 작업인가, 검증인가

중복 작업은 보고서에 드러나지 않습니다. 두 작업자가 말없이 같은 파일을 열어 목록 항목이 어떻게 구성되는지 조사하고, 둘 다 코드를 살펴봤다고 보고합니다. 하지만 때로는 의도적으로 두 번째 검토가 필요합니다. 중요한 가정을 첫 작업자의 추론을 보지 않은 사람이 확인하길 바랄 수 있습니다. 이런 검증은 우연한 중복과 다릅니다. 무엇을 왜 확인하는지, 답이 다를 때 어떻게 할지 미리 정해 둡니다. 마지막 항목이 빠지면 검증은 의견 수집으로 바뀝니다.

반대 상황도 보겠습니다. 두 작업자에게 목록 항목의 completed가 무엇을 뜻하는지 물었습니다. 둘 다 같은 답을 했습니다. 항목을 구매했다는 표시라는 것입니다. 양쪽에서 확인해 준 것처럼 보입니다.

실제로는 둘 다 1년 전에 작성된 README.md의 같은 한 줄을 읽었습니다. 하지만 코드에서 이 필드는 오래전부터 다른 의미였습니다. 일치한 것은 결론이 아니라 출처였습니다.

여기서 실무에 쓸 만한 습관 두 가지를 얻을 수 있습니다.

• 답의 근거를 보여 달라고 하세요. 파일, 줄, 코드 조각처럼 직접 열어 볼 수 있는 자료가 필요합니다. 요약만으로는 부족합니다;
• 공통 가정은 실제로 따로 검증하세요. 코드가 무엇을 하는지, 시나리오에서 어떤 일이 일어나는지 확인합니다. 모두 동의하더라도 마찬가지입니다.

세션이 따로라고 해서 오류도 독립적이라는 뜻은 아닙니다. 같은 출처를 보면 같은 실수를 할 수 있습니다. 답이 다를 때는 표를 세지 말고 근거를 살펴보세요. 한 명은 최신 코드를 보고 둘은 오래된 메모를 보고 있을 수도 있습니다.

코드로 확인한 필드 값이 공통 모델의 토대가 되고, 작업을 시작하기 전에 이 모델을 합의합니다. 세 가지 점검을 마친 뒤에도 분할이 여전히 이득으로 보인다면 이제 역할을 배분할 차례입니다.

각 영역의 담당자를 지정하세요

병렬 작업을 하는 동안의 규칙은 간단합니다. 변경 영역마다 담당자는 한 명입니다. "이 파일은 절대로 둘이 함께 건드리면 안 된다"는 뜻이 아니라, "이 두 작업이 진행되는 동안 이 부분은 이 사람이 수정한다"는 약속입니다. 프로젝트의 고정된 속성이 아니라 정해진 기간 동안의 합의입니다.

규칙의 두 번째 부분이 더 중요하지만 자주 잊힙니다. 통합 결과에도 담당자가 있어야 합니다. 각 부분을 합치고 전체가 준비됐는지 판단할 사람입니다. 통합 담당자를 정하지 않으면 마지막으로 끝낸 사람이 맡게 되는데, 하필 그 사람이 다른 쪽 작업을 가장 모릅니다.

작업을 시작하기 전에 프로젝트를 살펴보고 필요한 부분이 이미 어느 정도 분리되어 있는지 확인하세요. 그렇지 않다고 해서 병렬 작업을 위해 대규모 리팩터링을 시작할 필요는 없습니다. 리팩터링 자체가 그날의 가장 큰 작업이 되어 나눌 일이 없어질 수도 있습니다.

쇼핑 목록 예시에서는 다음과 같이 나눌 수 있습니다.

이 표는 변경 책임을 나누는 것이지 접근 권한을 나누는 것이 아닙니다. 공통 파일은 필요한 사람이라면 누구나 읽을 수 있습니다.

package.json에 관한 항목은 괜히 넣은 것이 아닙니다. npm install은 두 파일을 한꺼번에 변경하므로 병렬 설치 두 번이면 쉽게 충돌이 납니다. 같은 라이브러리의 서로 다른 버전을 쓰면 통합할 때 예상치 못한 문제가 생깁니다. 두 작업자 모두 라이브러리가 필요하다면 무엇이 왜 필요한지 요구사항으로 돌려보냅니다. 결정과 수정은 한 사람이 한 번만 합니다.

작업 전에 공통 모델을 합의하세요

파일 경계만 정하고 공통 합의를 하지 않으면 문제가 생깁니다. 필터와 내보내기는 같은 항목 모델에 의존합니다. 아래는 인터페이스를 보여 주는 개요이며 실행 가능한 예제가 아닙니다. 함수 구현은 생략했습니다. 작업 전에는 항목 순서를 유지하고, 원본 배열은 바꾸지 않으며, CSV의 불리언 값은 true/false로 기록하기로도 합의했습니다. CSV 이스케이프 규칙은 기존대로 둡니다.

// 목록의 한 항목: 이 세 필드는 작업 전에 합의하고 이름을 바꾸지 않습니다
const item = { id: 41, title: "oat milk", completed: false };

// filter.js는 형식을 바꾸거나 내보내지 않고 항목 배열을 반환합니다
filterItems(items, mode);   // mode: "all", "active", "completed"

// export-csv.js는 이미 필터링된 배열을 받고 직접 필터링하지 않습니다
exportCsv(items);           // id,title,completed 열이 있는 CSV 문자열을 반환합니다

여기서 합의할 것은 파일 이름이 아니라 입력과 출력입니다. "내보내기는 필터링된 목록을 받는다"는 말은 사소해 보여도, 두 작업자 중 누가 항목 선택을 책임지는지 결정합니다. 이 말이 없으면 둘 다 자기 쪽에서 필터링한다고 합리적으로 생각할 수 있습니다. 그러면 파일에 모든 항목이 들어가거나 같은 항목이 두 번 필터링됩니다.

작업 전에 결과를 어떻게 승인할지도 합의합니다. 이 예시의 공통 시나리오에서는 항목 41과 43이 completed: true, 항목 42가 false입니다. "completed" 모드는 41과 43을 원래 순서대로 보여 줘야 합니다. CSV에는 같은 두 항목이 포함되고, 헤더는 id,title,completed이며 마지막 열의 값은 true여야 합니다. 두 부분을 모두 거치는 이 시나리오는 글의 첫 부분에서 생긴 바로 그 오류를 잡아냅니다.

합의 자체를 바꾸는 경우도 따로 살펴봅시다. 작업 도중 공통 형식을 바꿔야 한다는 사실이 드러났다면, 한 파일만 살짝 수정할 문제가 아닙니다. 이미 진행한 작업 일부가 이전 형식에 의존했을 수 있으므로 관련된 모든 작업을 다시 검토해야 합니다.

각자 별도의 작업 폴더(git worktree)를 사용해도 합의가 대체되지는 않습니다. 변경을 물리적으로 분리하는 것은 유용합니다. 공용 폴더에서는 검사가 옆 작업의 미완성 변경까지 함께 잡아, 어느 작업자도 따로 검증하지 않은 상태를 통과로 판정할 수 있기 때문입니다. 하지만 폴더가 항목 형식을 합의해 주지는 않습니다. 포트, 로컬 데이터베이스와 그 밖의 외부 자원은 여전히 공유됩니다. Git이 추적하지 않는 .env는 새 폴더에 기본적으로 아예 없으므로, 예를 들어 .worktreeinclude로 복사해 둡니다.

각자에게 짧은 작업 지시를 주세요

작업 지시가 길 필요는 없습니다. 보통 일곱 항목이면 충분합니다. 목표, 시작할 버전, 담당 파일, 공통 합의, 검증 가능한 결과, 응답에 포함할 내용, 다른 영역이 필요할 때의 처리 방법입니다.

목표: 목록 필터가 모든 항목, 미완료 항목만 또는 완료 항목만 표시합니다.
시작 기준: 항목 모델을 합의한 기본 브랜치의 최신 커밋.
담당 파일: src/filter.js 및 tests/filter.test.js.
공통 합의: completed 필드는 불리언으로 유지하고, 필드 이름은 바꾸지 않습니다.
필터는 항목 배열을 반환하며 아무것도 내보내지 않습니다.
결과: 필터 테스트가 통과하고, 항목 세 개가 있는 목록에서 각 모드가
예상한 항목을 보여 줍니다.
응답에 포함할 내용: 실제 변경 파일 목록, 테스트 실행 출력과 실행한 버전,
남은 질문.
src/item-model.js 또는 src/app.js를 변경해야 한다면 멈추고,
필요한 변경과 이유를 설명한 뒤 답변을 기다리세요.

두 번째 작업자에게도 같은 방식으로 지시합니다. 담당 파일 두 개, 같은 항목 형식, 검증 가능한 결과, 경계를 넘을 때의 동일한 절차입니다. 여기서 지시 전체를 다시 쓸 필요는 없습니다.

이제 응답을 살펴보겠습니다. 실제 변경 파일 목록과 실제 검사 결과가 있어야 합니다. "다른 파일은 건드리지 않았습니다"라는 말은 쉽게 쓸 수 있고, 그렇게 써 달라고 강하게 요청할수록 응답에 더 잘 등장합니다. 문구가 아니라 변경 목록과 대조하세요. 작업 지시의 경계는 합의일 뿐 금지 규칙이 아닙니다. 요청 내용만으로 에이전트의 파일 쓰기를 막을 수는 없습니다. 접근 권한은 별도로 설정해야 합니다.

겹치는 영역을 다시 합의하세요

언젠가는 누군가 다른 사람의 경계와 맞닥뜨립니다. 작업자 B는 src/app.js를 수정하지 않으면 내보내기 기능을 연결할 곳이 없다는 사실을 알게 됩니다. 내보내기 버튼이 호출되지 않습니다.

좋은 응답에는 이유, 필요한 변경, 의존성이 포함됩니다. src/app.js에서 연결하는 일은 이미 통합 담당자에게 배정됐으므로 B는 모듈을 마무리하고 연결 요청을 전달할 수 있습니다. 공통 변경 없이는 자신의 작업을 계속할 수 없다면, 의존하는 작업을 중단합니다.

다음 선택지는 두 가지입니다. 통합 담당자가 자신의 영역인 공통 파일을 직접 수정하거나, 해당 영역을 작업자 B에게 명시적으로 넘길 수 있습니다. 넘기기 전에 기존 담당자가 그 파일을 더 이상 수정하지 않는지 확인해야 합니다. 작업을 멈추지 않은 채 담당자를 바꾸면 역할 분담이 막으려던 바로 그 문제가 생깁니다.

작업자에게 경계를 우회하게 해서는 안 됩니다. "app.js는 건드리지 말고 다른 방법을 찾아보세요"라고 하면 대개 자기 파일에 다른 사람의 로직을 복사하거나, 나중에 아무도 설명할 수 없는 불필요한 계층을 만들게 됩니다. 겉으로는 표를 지켰지만, 프로젝트에는 내보내기가 어떻게 작동하는지에 대한 두 번째 진실이 생깁니다.

파일뿐 아니라 동작도 통합하세요

통합 담당자는 통합 전에 세 가지를 파악해야 합니다. 각 부분이 어떤 버전에서 시작했는지, 각 작업자가 어떤 버전에서 무엇을 확인했는지, 실제로 어떤 파일이 바뀌었는지입니다. 작업 지시 응답에 이 내용이 있어야 하며, 파일 목록은 실제 변경 내역과 대조해야 합니다.

그런 다음 각 부분을 합치고, 작업 전에 합의한 공통 시나리오를 실행하는 것이 중요합니다. 여기서 서로 다른 두 가지 문제가 생길 수 있습니다.

텍스트 충돌. 두 부분이 같은 영역을 다르게 수정하거나 파일을 삭제하거나 이름을 바꿔 Git이 자동으로 병합하지 못합니다. 충돌을 해결한 다음 최종 동작을 확인합니다.

의미상 비호환. 같은 줄을 두 작업자가 함께 건드리지 않았고, 텍스트 병합도 깔끔하며 충돌 메시지도 없습니다. 바로 여기서 필드 이름 변경 문제가 생깁니다. 필터는 done을 읽고, 내보내기는 completed를 읽어 결과가 비어 버립니다. 각 부분의 검사는 모두 통과합니다. 각자 자기 데이터로 자기 부분만 확인했기 때문입니다.

그림의 아래쪽 화살표를 보세요. 위쪽은 보통 일을 나눈다고 할 때의 모습입니다. 서로 다른 파일에서 독립된 두 부분을 작업합니다. 하지만 준비됐는지 판단하는 지점은 한 단계 아래에 있습니다. 두 부분을 모두 거치는 시나리오입니다. 이 화살표를 따라가지 않았다면 로컬 결과 두 개만 있을 뿐, 통합 결과는 없습니다. 프로젝트 규칙에서 전체 검사를 요구한다면 공통 시나리오가 이를 대신하지는 않습니다.

공통 결정을 기록하세요

통합이 끝나면 통합 결과 담당자가 다음 단계를 선택합니다. 예를 들면 다음과 같습니다.

1. 공통 결과를 승인합니다. 시나리오가 통과하고, 변경 사항을 설명할 수 있으며, 기준이 충족됐습니다.
2. 구체적인 부분을 다시 작업하도록 돌려보내고 무엇이 무엇과 맞지 않는지 설명합니다. "내보내기가 좀 이상해요"가 아니라 "내보내기가 모델에 더 이상 없는 필드를 읽습니다"라고 하세요.
3. 작업 분할 자체를 다시 검토합니다. 작업자 수를 줄이거나 각 부분을 순차적으로 진행합니다.

세 번째 선택도 실패가 아니라 정상적인 판단입니다. 역할 분담을 다시 살펴볼 신호는 꽤 빨리 나타납니다.

• 공통 항목 형식이 계속 바뀌고, 바뀔 때마다 두 부분을 모두 다시 작업합니다;
• 작업자들이 서로를 기다립니다. 의존성이 있었지만 이름 붙이지 않았다는 뜻입니다;
• 결과가 여러분이 읽는 속도보다 더 빠르게 도착합니다.

마지막 신호가 가장 곤란합니다. 겉으로는 성공처럼 보이기 때문입니다. 한 번 분할이 잘됐다고 해서 늘 그렇다는 뜻은 아닙니다. 에이전트의 결과는 실행할 때마다 달라질 수 있으므로 중요한 결론은 비슷한 작업에서 다시 확인하세요.

부분 결과도 정상적인 결과입니다. 필터는 완성되어 검증됐지만 내보내기는 아직일 수 있습니다. 이때는 그대로 기록하세요. 두 부분 중 하나만 끝난 것입니다. 전체 작업은 여전히 진행 중입니다. 절반이 작동한다는 이유로 전체가 끝났다고 할 수는 없으며, 아무리 신중하게 역할을 나눠도 달라지지 않습니다.

직접 확인해 보세요

두 가지 상황입니다. 먼저 직접 답을 생각한 뒤 확인해 보세요.

오류 원인을 아직 찾지 못했습니다.
내보내기 결과가 가끔 빈 파일로 나오면 곧바로 두 사람에게 수정을 맡기고 싶을 수 있습니다. 먼저 재현하고 조사하세요. 검증할 가설이 서로 다르다면 두 작업자에게 나눠 맡길 수 있습니다. 하지만 근거 없이 수정안 두 개를 내놓는다고 문제가 해결되지는 않습니다. 각 수정안을 원인과 연결하고 원래 시나리오에서 확인해야 합니다.

파일은 다르지만 다루는 수량은 같습니다.
필터는 상품 수량을 낱개로 세고, 내보내기는 같은 수량을 묶음 단위로 출력합니다. 두 부분의 검사는 모두 통과했지만 화면과 파일의 숫자가 다릅니다. 코드 오류는 아닙니다. 어느 부분도 자신에게 배정된 경계를 어기지 않았습니다. 측정 단위에 관한 합의가 빠졌습니다. 작업 전에 공통 항목 모델에 이를 기록하고, 통합 담당자가 src/item-model.js를 수정한 다음 공통 시나리오를 다시 실행합니다.

Claude Code가 맡을 수 있는 일

글의 첫 부분에서 본 것처럼 에이전트에게 작업 분할 초안을 요청하고, 여러분이 정한 항목을 바탕으로 일관된 작업 지시를 작성하게 할 수 있습니다. 다음 세 가지에도 유용하지만, 결정은 여전히 여러분이 합니다.

• 영역 지도 초안. 프로젝트를 살펴보고 작업의 각 부분에서 어떤 파일을 바꿀지 경로와 함께 제안해 달라고 하세요. 어디까지나 초안입니다. 각 영역의 담당자는 여러분이 지정합니다.
• 통합과 공통 검사. 에이전트가 각 부분을 통합하고 전체 변경 목록을 보여 준 다음 공통 시나리오를 실행할 수 있습니다. 이후에는 변경 사항 전체를 직접 살펴보세요.
• 의견이 갈리는 지점. 자신 있는 설명이 두 개 있다고 해서 결론이 정해지는 것은 아닙니다. 근거와 파일, 줄을 요청하세요. 공통 파일을 누가 수정할지는 더 설득력 있게 들리는 답이 아니라 미리 작성한 표로 정합니다.

결국 하나의 결정과 두 가지 역할 지정이 핵심입니다. 결정은 일을 나눌지 여부입니다. 추가 작업자마다 준비, 확인, 통합에 드는 비용을 정당화할 만큼의 이득이 있어야 합니다. 역할은 각 변경 영역의 담당자와 공통 결과의 담당자를 정하는 것입니다. 쇼핑 목록 사례에서 부족했던 것도 바로 이 점입니다. completed 필드에 대한 합의와 필터 및 내보내기를 함께 실행할 담당자가 없었습니다. 도구는 반복 작업을 덜어 주지만, 통합된 동작이 실제 요청한 대로인지 판단하는 일은 사람이 맡습니다.