2026. 5. 27. 22:40ㆍ카테고리 없음
AI 코딩 에이전트를 쓰다 보면 처음에는 자연스럽게 큰 요청을 하게 됩니다.
관리자 페이지의 회원 관리 기능을 만들어줘.
말로 보면 간단하지만, 실제로는 API 타입 정의, 목록 화면, 검색, 페이지네이션, 권한 처리, 에러 처리, 테스트, 스타일 정리까지 여러 작업이 섞여 있습니다. 사람 개발자라면 중간중간 판단하면서 쪼개서 진행하지만, AI에게 한 번에 맡기면 그 판단을 AI가 대신하게 됩니다.
문제는 여기서 시작됩니다. 결과물은 빠르게 나오지만 요구사항 일부가 빠지거나, 기존 패턴과 다른 구조가 생기거나, 리뷰해야 할 파일이 너무 많아집니다. 이전 글에서 AGENTS.md, Spec-Driven Development, 테스트 주도 흐름, AI 코드 리뷰 체크리스트를 다뤘다면 이번 글에서는 그보다 더 작은 단위인 작업을 어떻게 쪼개서 맡길 것인가를 정리해보겠습니다.
왜 작업 단위를 쪼개야 할까
AI 에이전트는 한 번에 많은 파일을 읽고 수정할 수 있습니다. 그래서 오히려 사람이 작업 범위를 명확히 정해주지 않으면 과하게 넓은 변경을 만들기 쉽습니다.
큰 요청의 흔한 문제는 다음과 같습니다.
- 요구사항 중 일부만 구현된다.
- 정상 케이스는 동작하지만 예외 케이스가 빠진다.
- 기존 컴포넌트나 유틸을 재사용하지 않고 새로 만든다.
- 테스트가 구현에 맞춰 작성되어 검증력이 약해진다.
- 리뷰해야 할 변경 파일이 많아져 사람이 놓치는 부분이 생긴다.
작업 단위를 쪼개는 목적은 AI를 느리게 쓰기 위한 것이 아닙니다. 검증 가능한 단위로 빠르게 반복하기 위한 것입니다. 작은 단위로 요청하면 실패했을 때 되돌리기 쉽고, 사람이 의도를 확인하기도 쉽습니다.
좋은 작업 단위의 기준
작업을 쪼갤 때 단순히 “작게” 나누는 것만으로는 부족합니다. 너무 작게 나누면 매번 설명 비용이 커지고, 너무 크게 나누면 다시 리뷰가 어려워집니다. 실무에서는 다음 네 가지 기준을 사용해볼 수 있습니다.
1. 결과를 한 문장으로 설명할 수 있는가
좋은 작업 단위는 완료 상태가 분명합니다.
나쁜 예:
- 회원 관리 기능을 개선해줘.
좋은 예:
- 회원 목록 API 응답 타입을 기준으로 `MemberListItem` 타입을 추가하고, 목록 화면에서 해당 타입을 사용하게 바꿔줘.
첫 번째 요청은 “개선”의 의미가 넓습니다. AI가 UI를 바꿀 수도 있고, API 호출 코드를 고칠 수도 있고, 테스트를 추가할 수도 있습니다. 두 번째 요청은 결과가 명확합니다. 타입을 추가하고 목록 화면에 적용하면 됩니다.
2. 변경 파일 범위를 예측할 수 있는가
요청하기 전에 어떤 파일이 바뀔지 대략 예상할 수 있어야 합니다. 예상이 안 된다면 작업이 너무 큰 것일 수 있습니다.
예를 들어 “로그인 UX 개선”은 범위가 넓지만 다음처럼 나누면 예측 가능합니다.
- 로그인 실패 메시지 문구를 상수로 분리한다.
- 인증 실패 코드별 메시지 매핑을 추가한다.
- 로그인 폼 테스트에 실패 케이스를 추가한다.
- 문서에 에러 코드 표를 정리한다.
각 단계는 바뀔 파일을 어느 정도 예상할 수 있습니다. AI가 예상 밖의 파일을 수정하면 리뷰에서 바로 확인할 수 있습니다.
3. 검증 명령이 있는가
AI에게 맡길 작업은 가능하면 검증 명령과 함께 줘야 합니다.
검증:
- pnpm typecheck
- pnpm test MemberList
- pnpm lint src/features/member
검증 명령이 있으면 AI도 작업 완료 기준을 이해하기 쉽고, 사람도 결과를 확인하기 좋습니다. 모든 작업에 완벽한 자동 검증이 있는 것은 아니지만, 타입 체크나 관련 테스트처럼 최소한의 안전장치는 지정하는 편이 좋습니다.
4. 되돌릴 수 있는가
작업 단위가 좋으면 실패했을 때 해당 변경만 되돌릴 수 있습니다. 반대로 여러 목적이 섞인 작업은 되돌리기가 어렵습니다.
예를 들어 다음 두 작업을 한 번에 맡기면 위험합니다.
- 회원 목록 리팩터링
- 디자인 변경
리팩터링은 잘됐지만 디자인이 마음에 들지 않을 수도 있고, 디자인은 괜찮지만 리팩터링이 기존 동작을 깨뜨릴 수도 있습니다. 두 목적은 커밋도 리뷰도 분리하는 편이 안전합니다.
실무에서 쓰기 좋은 분해 패턴
AI 에이전트에게 작업을 맡길 때 자주 쓰는 분해 패턴을 정리해보겠습니다.
패턴 1. 조사 → 계획 → 수정
바로 수정하게 하지 않고 먼저 조사와 계획을 시키는 방식입니다.
먼저 관련 파일을 읽고 작업 계획만 작성해줘.
아직 파일은 수정하지 마.
목표:
- 회원 목록에서 검색어 필터링 로직을 개선한다.
확인할 것:
- 현재 필터링이 어디에서 수행되는지
- 비슷한 검색 로직이 다른 화면에 있는지
- 테스트 파일이 있는지
이 방식은 기존 코드 맥락을 파악해야 하는 작업에 좋습니다. AI가 계획을 제시하면 사람이 범위가 맞는지 확인한 뒤 수정 단계로 넘어갈 수 있습니다.
패턴 2. 타입 → 구현 → 테스트
기능 구현을 타입, 구현, 테스트 순서로 나누는 방식입니다.
- API 응답 타입과 도메인 타입을 정리한다.
- 화면 또는 서비스 로직에 타입을 적용한다.
- 정상/빈 상태/에러 케이스 테스트를 추가한다.
이 순서는 프론트엔드와 백엔드 모두에서 유용합니다. 타입을 먼저 정리하면 AI가 구현할 때 기준이 생기고, 테스트를 별도 단계로 두면 구현에 맞춘 약한 테스트를 줄일 수 있습니다.
패턴 3. 한 파일 리팩터링 → 호출부 확장
공통 유틸이나 컴포넌트를 바꿀 때는 먼저 한 파일에서 안전하게 리팩터링한 뒤 호출부를 넓히는 편이 좋습니다.
1단계:
- `formatDate` 함수에 timezone 옵션을 추가한다.
- 기존 호출부는 아직 바꾸지 않는다.
- 단위 테스트만 추가한다.
2단계:
- 관리자 화면의 날짜 표시 3곳만 새 옵션을 사용하도록 바꾼다.
이렇게 하면 공통 코드 변경의 영향 범위를 나눠서 볼 수 있습니다.
패턴 4. 실패 재현 → 최소 수정 → 회귀 테스트
버그 수정은 특히 작게 나누는 것이 좋습니다.
- 실패를 재현하는 테스트를 먼저 추가한다.
- 테스트가 실패하는 것을 확인한다.
- 최소한의 코드만 수정한다.
- 관련 테스트를 실행한다.
AI에게 “버그 고쳐줘”라고만 하면 원인을 우회하거나 테스트를 약하게 만들 수 있습니다. 재현 테스트를 먼저 요구하면 문제의 기준이 분명해집니다.
요청 템플릿 예시
아래 템플릿은 AI 에이전트에게 작은 작업을 맡길 때 바로 사용할 수 있는 형태입니다.
목표:
- [한 문장으로 완료 상태를 설명]
범위:
- 수정 가능: [파일/폴더]
- 수정 금지: [건드리면 안 되는 파일/영역]
진행 방식:
1. 관련 파일을 읽고 현재 구조를 요약한다.
2. 변경 계획을 3줄 이내로 제시한다.
3. 계획이 맞으면 수정한다.
4. 변경 파일과 이유를 정리한다.
검증:
- [typecheck/test/lint 명령]
주의:
- 새 패턴을 만들기보다 기존 패턴을 우선 사용한다.
- 관련 없는 포맷 변경은 하지 않는다.
여기서 중요한 부분은 “수정 금지”입니다. AI에게 할 일만 말하면 해결을 위해 주변 파일을 넓게 수정할 수 있습니다. 건드리지 말아야 할 파일을 함께 알려주면 변경 범위가 훨씬 안정됩니다.
작업 단위를 나누는 체크리스트
AI에게 요청하기 전에 아래 항목을 확인해보면 좋습니다.
- 완료 상태를 한 문장으로 말할 수 있는가?
- 예상 변경 파일을 대략 적을 수 있는가?
- 수정 금지 영역을 정했는가?
- 검증 명령이 있는가?
- 테스트와 구현을 한 번에 맡겨도 괜찮은 작업인가?
- 실패했을 때 되돌리기 쉬운가?
- 리뷰할 사람이 10분 안에 변경 의도를 이해할 수 있는가?
체크가 많이 비어 있다면 바로 구현을 맡기기보다 조사나 계획 단계부터 요청하는 편이 안전합니다.
결론: AI에게도 작은 PR이 필요하다
AI 코딩 에이전트는 큰 일을 빠르게 처리할 수 있지만, 실무에서 중요한 것은 빠른 초안보다 안정적인 반복입니다. 작업 단위를 잘 쪼개면 AI 결과물을 더 쉽게 리뷰할 수 있고, 테스트와 커밋 단위도 자연스럽게 정리됩니다.
다음에 AI에게 큰 기능을 맡기고 싶다면 바로 “전부 만들어줘”라고 하기 전에 먼저 이렇게 물어보면 좋습니다.
이 작업을 검증 가능한 3~5개의 작은 단계로 나눠줘. 각 단계의 예상 변경 파일과 검증 방법도 함께 적어줘.
AI를 잘 쓰는 핵심은 더 멋진 프롬프트 한 줄이 아니라, 사람이 리뷰하고 되돌릴 수 있는 단위로 일을 설계하는 데 있습니다.