제12장 작업을 잘게 쪼개는 기술

Antigravity를 쓰다 보면 아주 빨리 깨닫는 사실이 하나 있다. 에이전트가 일을 못하는 것처럼 보일 때, 실제 원인은 모델의 지능이 아니라 내가 던진 작업의 모양인 경우가 많다는 점이다.

사람도 마찬가지다. 누군가에게 "우리 서비스 좀 더 좋게 만들어 줘"라고 말하면, 뭘 먼저 해야 할지부터 막막하다. 반대로 "모바일 홈 화면의 첫 진입 속도를 개선하되, 이미지 로딩과 번들 크기만 다루고 디자인은 건드리지 말아 달라. 완료되면 전후 비교와 테스트 결과를 남겨 달라"라고 말하면 훨씬 움직이기 쉽다.

에이전트는 더하다. 똑똑해 보여도, 애매한 요구 앞에서는 열심히 잘못된 방향으로 달려간다. 그래서 Agent-First 개발에서 중요한 능력은 프롬프트를 멋있게 쓰는 재주가 아니라, 일을 실패하기 어려운 단위로 설계하는 능력이다.

이 장의 핵심은 단순하다. 에이전트 성능의 절반은 모델이 아니라 작업 쪼개기에서 나온다. 큰 일을 덩어리째 맡기지 말고, 경계와 완료 조건이 분명한 작업으로 나눠야 한다.

큰 기능을 통째로 던지면 왜 망하는가

처음에는 누구나 이렇게 말하고 싶어진다. "결제 기능 붙여 줘." "대시보드 전면 개편해 줘." "레거시 인증 모듈을 새 구조로 옮겨 줘."

듣기에는 시원하다. 하지만 이런 지시는 에이전트에게 너무 많은 선택권을 한 번에 준다. 그러면 문제는 보통 네 방향에서 동시에 터진다.

첫째, 범위가 흐려진다. 어디까지가 이번 작업인지, 어디부터는 다음 작업인지 분간이 안 된다. UI만 손보는 줄 알았는데 API 스키마까지 바꾸고, 테스트를 고치는 줄 알았는데 런타임 로직도 재작성해 버린다.

둘째, 숨은 의존성이 폭발한다. 하나의 큰 기능 안에는 보통 데이터 모델, API, 프론트엔드, 에러 처리, 접근 권한, 테스트, 문서가 얽혀 있다. 이것을 한 작업으로 던지면 에이전트는 자연스럽게 여러 층을 동시에 건드리게 된다. 그러면 충돌이 늘고, 검토도 어려워진다.

셋째, 리뷰 비용이 커진다. 결과물이 너무 크면 사람은 결국 꼼꼼히 못 본다. "대충 괜찮겠지"라고 머지하는 순간, Agent-First는 마법이 아니라 사고로 바뀐다.

넷째, 실패했을 때 어디가 문제인지 찾기 어렵다. 작업이 하나의 큰 덩어리면, 실패 원인이 요구사항인지 구현인지 검증 누락인지조차 분리되지 않는다.

쉽게 말해 큰 작업은 에이전트에게 자유를 주는 것이 아니라, 혼란을 준다.

좋은 작업 단위는 무엇으로 이루어지는가

잘 쪼개진 작업에는 공통점이 있다. 읽는 순간 "무엇을 바꿔야 하는지", "무엇은 바꾸면 안 되는지", "언제 끝난 것으로 볼지"가 보인다.

좋은 작업 단위는 보통 다음 네 가지를 갖고 있다.

• 목표: 무엇을 달성해야 하는가

• 경계: 어디까지 다루고 어디는 건드리지 않는가

• 증거: 끝났다는 사실을 무엇으로 보여 줄 것인가

• 판정 기준: 사람이 무엇을 보고 승인할 것인가

이 네 가지가 없으면 작업은 부탁이 아니라 소망이 된다.

예를 들어 "로그인 경험 개선"은 목표만 있고 나머지가 없다. 반면 "로그인 실패 시 에러 메시지가 항상 상단에만 뜨는 문제를 고치고, 이메일/비밀번호 오류와 서버 오류를 구분해 표시하되, 인증 API 계약은 변경하지 말고, 실패/성공 케이스 스크린샷과 수정된 테스트를 남겨 달라"는 훨씬 작업답다.

핵심은 기능의 크기가 아니라 검토 가능한 크기다. 사람 리뷰어가 한 번에 읽고 판단할 수 있어야 한다. 그보다 크면, 이미 쪼갤 시점을 놓친 것이다.

작업 단위를 나누는 가장 쉬운 기준: 경계

작업을 잘게 나눌 때 많은 사람이 "기능을 얼마나 잘게 쪼개야 하지?"부터 고민한다. 그런데 실제로는 크기보다 먼저 경계를 생각하는 편이 훨씬 쉽다.

경계는 간단히 말해 "이 작업이 책임지는 구역"이다. 보통 경계는 네 종류로 나눠 잡을 수 있다.

첫 번째는 파일 경계다. 예를 들어 components/dashboard/*만 수정하고, lib/api/*는 건드리지 않게 만드는 식이다. UI 수정처럼 침범 범위를 좁히고 싶을 때 특히 효과적이다.

두 번째는 계층 경계다. 프론트엔드만, API만, 테스트만, 문서만 맡기는 방식이다. 병렬 작업에 아주 유리하다. "한 에이전트는 화면, 다른 에이전트는 API, 또 다른 에이전트는 테스트"처럼 분리하면 서로 밟을 일이 줄어든다.

세 번째는 사용자 흐름 경계다. 회원가입, 초대 수락, 결제 실패 복구처럼 사용자의 여정을 한 조각으로 잡는 방식이다. 기능적으로 이해하기 쉽고, 검증 시나리오도 명확해진다.

네 번째는 위험 경계다. 위험한 변경과 안전한 변경을 나누는 것이다. 예를 들어 리팩터링은 따로, 마이그레이션은 따로, 운영 설정 변경은 또 따로 맡긴다. 특히 데이터 구조나 인증처럼 사고 비용이 큰 영역에서는 이 경계가 중요하다.

좋은 분해는 종종 이 네 가지를 섞는다. "초대 수락 플로우"라는 사용자 흐름을 잡되, 이번 작업에서는 "프론트엔드 화면과 상태 처리만" 다루고 "API 계약과 DB 스키마는 제외"한다고 못을 박는 식이다.

큰 일을 작은 일로 바꾸는 순서

막상 실무에서는 큰 요구만 던져지는 경우가 많다. "관리자 페이지 만들어 주세요"처럼 말이다. 이럴 때는 바로 구현에 들어가지 말고, 큰 일을 작은 일로 번역해야 한다.

가장 쉬운 순서는 이렇다.

먼저, 최종 결과를 한 문장으로 쓴다. 예를 들어 "관리자가 사용자 목록을 보고, 검색하고, 상태를 변경할 수 있어야 한다." 이 문장은 목적지다.

그다음, 그 결과를 이루는 하위 흐름을 나눈다. 목록 조회, 검색, 상태 변경, 에러 처리, 권한 확인, 테스트, 문서화처럼 쪼갠다.

그다음, 각각이 어떤 층을 건드리는지 표시한다. 목록 조회는 API와 UI가 함께 필요할 수 있고, 상태 변경은 감사 로그까지 얽힐 수 있다. 반면 검색 UI 자체는 프론트엔드만으로 먼저 만들 수 있다.

마지막으로, 사람이 한 번에 리뷰할 수 있을 정도로 자른다. 여기서 기준은 "에이전트가 할 수 있느냐"가 아니라 "사람이 검토할 수 있느냐"다.

이 과정을 거치면 원래 하나였던 요구가 여러 개의 선명한 미션으로 바뀐다. 그때부터 비로소 병렬화가 가능해진다.

나쁜 작업 의뢰와 좋은 작업 의뢰의 차이

둘의 차이는 길이가 아니라 구조에 있다.

나쁜 의뢰는 보통 이렇다.

"대시보드 UX 전반을 개선해 줘."

이 문장에는 의도는 있지만, 경계가 없다. 무엇이 문제인지, 무엇이 성공인지, 무엇을 건드리면 안 되는지 보이지 않는다. 에이전트는 높은 확률로 넓게 손대고, 당신은 높은 확률로 다시 범위를 줄이게 된다.

좋은 의뢰는 이렇게 생긴다.

"대시보드 상단 필터 영역의 모바일 사용성을 개선해 줘. 대상은 390px 기준 화면이며, 현재 두 줄로 깨지는 문제를 해결하는 것이 목표다. 이번 작업에서는 필터 컴포넌트 레이아웃과 간격만 수정하고, 필터 옵션 종류나 API 파라미터는 바꾸지 마라. 완료 기준은 첫 화면에서 줄바꿈 없이 보이고, 필터 열기/닫기 동작이 유지되며, 전후 스크린샷과 변경 요약을 남기는 것이다."

이 의뢰가 좋은 이유는 거창하지 않다. 그냥 판단해야 할 지점을 줄여 줬기 때문이다.

에이전트는 맥락을 읽는 존재이기도 하지만, 동시에 맥락을 과잉 해석하는 존재이기도 하다. 그러니 우리가 해야 할 일은 영감을 주는 것이 아니라, 해석 범위를 줄이는 것이다.

완료 기준은 반드시 관찰 가능한 문장으로 써라

초보자가 가장 자주 놓치는 부분이 바로 완료 기준이다. "깔끔하게 정리", "잘 동작하게 수정", "현대적으로 개선" 같은 표현은 사람끼리도 위험한데, 에이전트에게는 더 위험하다.

완료 기준은 반드시 눈으로 확인할 수 있는 문장이어야 한다.

예를 들어 이런 식이다.

• /users 페이지에서 검색어 입력 후 1초 이내에 결과가 갱신된다.

• 빈 결과일 때 안내 문구와 재시도 버튼이 함께 보인다.

• 기존 정렬 기능은 깨지지 않는다.

• 테스트 두 개가 추가되거나 갱신된다.

• 변경 이유와 영향 범위가 요약 문서에 정리된다.

이런 기준이 있으면 에이전트도 덜 헤매고, 사람도 덜 싸운다. "이 정도면 됐나?"라는 애매한 협상이 줄어들기 때문이다.

완료 기준을 쓰는 가장 쉬운 요령은 "끝났을 때 내가 무엇을 보게 될까?"를 문장으로 바꾸는 것이다. 코드가 아니라 증거의 형태를 먼저 적으면 훨씬 선명해진다.

제외 조건을 쓰면 실패가 줄어든다

많은 사람이 목표와 완료 기준은 쓰지만, 제외 조건은 빼먹는다. 그런데 실제로는 제외 조건이 사고를 막는 안전벨트다.

제외 조건은 "이번 작업에서 하지 않을 것"을 적는 부분이다. 이상하게 들릴 수 있다. 하지만 에이전트는 문제를 해결하기 위해 자꾸 더 넓게 손대려는 경향이 있다. 그러니 하지 말아야 할 것을 적어 두는 편이 낫다.

예를 들어 이런 문장이 유용하다.

• DB 스키마는 변경하지 않는다.

• 외부 라이브러리는 추가하지 않는다.

• API 응답 구조는 바꾸지 않는다.

• 디자인 토큰 시스템 전체 리팩터링은 이번 범위가 아니다.

• 테스트 픽스처 재구성은 별도 작업으로 남긴다.

이 문장들은 소극적으로 보이지만, 사실은 아주 적극적인 설계다. 범위를 좁혀야 속도도 나고, 리뷰도 쉬워지고, 병렬화도 가능해진다.

에이전트에게 자유를 주는 가장 좋은 방법은 무한한 선택지를 주는 것이 아니라, 좁고 안전한 운동장을 주는 것이다.

성공 판정은 PM처럼 써야 한다

Agent-First 개발에서는 개발자도 어느 정도 PM처럼 일해야 한다. 여기서 PM처럼 쓴다는 것은 문서를 길게 쓰라는 뜻이 아니다. 요구사항을 판정 가능한 형태로 쓰라는 뜻이다.

좋은 작업 의뢰는 대개 이런 순서를 따른다.

먼저 배경을 짧게 설명한다. 왜 이 작업을 하는지, 현재 무엇이 문제인지 말한다.

다음으로 목표를 한 문장으로 적는다. 이 작업이 끝나면 사용자나 팀이 무엇을 얻는지 분명히 한다.

그다음 범위를 적는다. 수정 가능한 영역과 수정 금지 영역을 같이 적는다.

이후 완료 기준을 적는다. 사람이 승인할 때 볼 체크포인트를 적는다.

마지막으로 결과물을 적는다. 코드 diff만 필요한지, 스크린샷이 필요한지, 테스트 결과가 필요한지, 변경 요약 문서가 필요한지 지정한다.

이 다섯 줄만 제대로 써도 작업 품질은 눈에 띄게 달라진다. 프롬프트가 멋져져서가 아니라, 업무 지시서로서 기능하기 시작하기 때문이다.

실전 예시: "사용자 초대 기능 추가"를 어떻게 쪼갤까

이제 흔한 기능 하나를 가지고 실제로 잘라 보자. 요구는 이렇다.

"조직 관리 화면에 사용자 초대 기능을 추가해 주세요."

이 문장을 그대로 던지면 거의 반드시 커진다. 초대 이메일 발송, 토큰 생성, 만료 처리, 수락 화면, 권한 부여, 실패 처리, 중복 초대 방지, 감사 로그, 테스트, 문서까지 줄줄이 붙기 때문이다.

이 기능을 잘게 쪼개면 보통 이렇게 된다.

첫 번째 작업은 명세 정리다. 초대 플로우가 어떻게 동작해야 하는지, 누가 누구를 초대할 수 있는지, 만료 시간은 얼마인지, 중복 초대는 어떻게 처리할지 결정한다. 이 단계는 구현보다 중요하다. 잘못된 가정으로 코드를 빨리 쓰는 것보다, 경계를 먼저 고정하는 편이 낫다.

두 번째 작업은 백엔드 초대 생성 API다. 초대 토큰 생성, 권한 검증, 중복 처리 규칙, 만료 정책을 다룬다. 하지만 이 작업에서는 이메일 발송은 아직 제외할 수 있다. 일단 시스템이 초대 레코드를 만들고 조회할 수 있게만 한다.

세 번째 작업은 조직 관리 화면의 초대 모달 UI다. 여기서는 폼 입력, 유효성 검사, 성공/실패 메시지 표시까지만 맡긴다. 초대 수락 화면은 아직 다루지 않는다.

네 번째 작업은 초대 이메일 발송과 템플릿 연결이다. 메일 시스템과 큐, 재시도 정책이 있다면 그 부분만 따로 맡긴다.

다섯 번째 작업은 초대 수락 화면과 가입/로그인 연동이다. 링크로 들어왔을 때 어떤 상태 분기가 필요한지 명확히 하고, 기존 인증 구조와 충돌하지 않게 설계한다.

여섯 번째 작업은 테스트와 검증이다. 단위 테스트, 통합 테스트, 브라우저 검증, 실패 케이스 점검을 따로 맡긴다.

일곱 번째 작업은 운영 관점 정리다. 감사 로그, 관리자 문서, 롤백 포인트, 알려진 한계를 정리한다.

이렇게 자르면 무엇이 좋아질까. 각 작업의 책임이 선명해지고, 서로 다른 에이전트가 동시에 움직일 수 있으며, 리뷰도 단계별로 가능해진다. 무엇보다 "초대 기능"이라는 거대한 덩어리가 더 이상 무섭지 않다.

병렬 작업이 되려면 겹치지 않게 잘라야 한다

작업을 잘게 쪼개는 것과 병렬로 돌릴 수 있게 쪼개는 것은 미묘하게 다르다. 잘게 쪼갰다고 해서 자동으로 병렬성이 생기지는 않는다. 서로 같은 파일, 같은 타입, 같은 설정, 같은 락파일을 건드리면 결국 충돌한다.

병렬 작업용 분해에서는 특히 두 가지를 신경 써야 한다.

첫째, 소유 구역이 겹치지 않아야 한다. 예를 들어 한 에이전트는 UI 컴포넌트, 다른 에이전트는 서버 핸들러, 또 다른 에이전트는 테스트 파일처럼 최대한 분리한다.

둘째, 순서 의존성을 최소화해야 한다. "B 작업은 A가 끝나야 시작 가능"한 구조가 많을수록 병렬성은 사라진다. 가능하면 계약을 먼저 고정하고, 그 위에서 독립 작업을 나눠야 한다.

그래서 큰 기능을 쪼갤 때는 종종 가장 먼저 "인터페이스를 정하는 작업"을 따로 빼는 것이 좋다. API 계약, 타입 정의, 상태 다이어그램, 화면 명세 같은 것을 먼저 확정하면 이후 작업들이 서로 부딪힐 가능성이 줄어든다.

병렬화의 기술은 결국 코딩의 기술이라기보다 충돌 관리의 기술에 가깝다.

너무 잘게 쪼개도 안 되는 이유

여기서 반대편 함정도 있다. 모든 걸 너무 작게 쪼개면 오히려 흐름이 끊긴다.

예를 들어 버튼 텍스트 수정, 패딩 조절, 아이콘 위치 수정, 에러 메시지 한 줄 변경을 각각 별도 작업으로 만들면 관리는 쉬워 보여도 실제로는 번거롭다. 작업 생성, 리뷰, 승인, 맥락 전달 비용이 더 커질 수 있다.

좋은 크기는 대체로 "에이전트가 한 번의 집중으로 끝낼 수 있고, 사람도 한 번의 검토로 승인할 수 있는 크기"다. 너무 크면 위험하고, 너무 작으면 행정이 된다.

간단한 기준을 하나 기억해 두면 좋다. 하나의 작업은 하나의 주된 질문에 답해야 한다.

"모바일 필터 UI가 깨지는가?" "이 API가 중복 초대를 올바르게 막는가?" "초대 수락 플로우가 기존 인증과 충돌하지 않는가?"

이 질문이 둘, 셋, 넷으로 늘어나기 시작하면 보통 이미 커진 것이다.

에이전트에게 맡길 작업 설명서 템플릿

실전에서 자주 먹히는 설명 구조를 하나 소개하자. 길게 쓸 필요는 없고, 아래 순서만 지켜도 된다.

배경

현재 어떤 문제가 있고 왜 이 작업이 필요한지 한두 문장으로 적는다.

목표

이번 작업이 끝났을 때 달성되어야 할 상태를 한 문장으로 적는다.

범위

수정해도 되는 영역과, 건드리면 안 되는 영역을 적는다.

완료 기준

성공 여부를 판정할 수 있는 관찰 가능한 조건을 적는다.

결과물

코드 외에 남겨야 할 증거를 적는다. 예를 들면 스크린샷, 테스트 결과, 변경 요약, 알려진 한계 등이다.

주의사항

기존 컨벤션, 성능 제한, 보안 조건, 라이브러리 선호 같은 팀 규칙을 적는다.

이 템플릿의 좋은 점은 에이전트에게 친절해서가 아니다. 사람 자신이 생각을 정리하게 만든다는 점이다. 일을 잘 못 나누는 이유는 에이전트가 멍청해서가 아니라, 애초에 우리 머릿속의 요구도 덩어리 상태인 경우가 많기 때문이다.

자주 터지는 안티패턴

작업을 잘게 쪼갠다고 하면서도, 실제로는 실패를 예약하는 방식들이 있다.

첫 번째 안티패턴은 "개선해 줘" 계열이다. 개선은 목표가 아니라 방향이다. 무엇을, 왜, 어느 기준으로 개선하는지 없으면 에이전트는 자기 취향을 섞기 시작한다.

두 번째는 "가능한 한 많이" 계열이다. 테스트도 추가하고, 성능도 높이고, 구조도 정리하고, UI도 다듬으라고 하면 결국 어느 것도 선명하지 않다. 우선순위가 사라지기 때문이다.

세 번째는 "문제 생기면 알아서" 계열이다. 얼핏 자율적으로 들리지만, 실은 책임 회피에 가깝다. 어떤 문제는 우회해야 하고, 어떤 문제는 멈추고 보고해야 한다. 그 기준을 미리 줘야 한다.

네 번째는 "결과만 좋으면 됨" 계열이다. Agent-First에서는 결과뿐 아니라 과정의 검증 가능성도 중요하다. 무엇을 바꿨고, 왜 바꿨고, 어떻게 확인했는지가 남아야 신뢰가 생긴다.

다섯 번째는 "모든 걸 한 에이전트에게" 계열이다. 한 명의 슈퍼 에이전트를 기대하는 순간, 관제는 다시 장인의 노동으로 돌아간다. 잘게 쪼갠 뒤 각자 잘하는 일을 맡겨야 멀티 에이전트의 의미가 생긴다.

좋은 분해는 좋은 검증을 부른다

작업 분해의 진짜 목적은 단지 일을 쉽게 만드는 것이 아니다. 검증을 가능하게 만드는 것이다.

작업이 선명하면 어떤 Artifact가 필요한지도 자연스럽게 따라온다. 설계가 핵심이면 계획 문서가 먼저 나오고, UI가 핵심이면 스크린샷과 브라우저 기록이 중요해지고, 안정성이 핵심이면 테스트 결과와 코드 diff가 중요해진다.

반대로 작업이 흐리면 Artifact도 흐려진다. 계획은 장황하고, 스크린샷은 핵심을 비껴 가고, 코드 diff는 넓게 퍼진다. 결국 사람은 다시 소스 전체를 뒤지게 된다. 그러면 신뢰의 격차는 줄지 않는다.

이 책 앞부분에서 계속 강조한 "결과물 중심 워크플로우"는 여기와 연결된다. 일을 잘 쪼개야 결과물도 검토 가능한 단위로 남는다.

결국, 잘 쪼개는 사람이 잘 지휘한다

Agent-First 개발에서 뛰어난 사람은 가장 빨리 코드를 치는 사람이 아니다. 가장 비싼 모델을 쓰는 사람도 아니다. 무엇을 한 번에 맡기고, 무엇을 분리하며, 어디에 경계를 긋는지 아는 사람이다.

좋은 관제자는 큰 요구를 보면 곧바로 구현으로 달려가지 않는다. 먼저 묻는다.

어디까지가 이번 일인가? 무엇이 성공인가? 무엇을 건드리면 안 되는가? 누가 이것을 검토할 것인가? 이 일은 다른 일과 병렬로 돌릴 수 있는가?

이 질문에 답한 뒤에야 비로소 에이전트를 보낸다.

그리고 이상하게도, 바로 그 순간 에이전트는 더 똑똑해진 것처럼 보인다. 사실 더 똑똑해진 것은 모델이 아니다. 당신의 작업 설계다.

이 장의 핵심

큰 기능을 통째로 던지면 에이전트는 넓게 헤맨다. 경계가 모호하고, 검증이 어려우며, 실패 원인도 흐려진다.

반대로 좋은 작업 단위는 목표, 경계, 완료 기준, 결과물이 선명하다. 무엇을 해야 하는지뿐 아니라 무엇을 하지 말아야 하는지도 적혀 있다.

병렬 작업이 잘 되려면 작게 쪼개는 것만으로는 부족하다. 서로 겹치지 않게 나누고, 순서 의존성을 줄이고, 사람이 한 번에 검토할 수 있는 크기로 설계해야 한다.

결국 에이전트 오케스트레이션의 출발점은 모델 선택이 아니라 작업 설계다. 일을 잘 나누는 순간, 에이전트는 비로소 믿고 맡길 수 있는 팀원이 된다.

다음 장에서는 이렇게 잘게 나뉜 작업들이 시간이 지날수록 더 정확하게 수행되도록, 팀의 규칙과 선호를 축적하는 구조인 Knowledge Base를 살펴보자.