2026. 5. 25. 13:58ㆍ카테고리 없음
AI 코딩 에이전트를 쓰다 보면 가장 먼저 체감하는 장점은 속도입니다. “로그인 기능 만들어줘”, “관리자 페이지 붙여줘”, “이 버그 고쳐줘”처럼 요청하면 코드 초안이 빠르게 나옵니다.
하지만 실무 프로젝트에서는 빠른 생성보다 중요한 것이 있습니다. 바로 수정 범위를 통제하는 것입니다.
AI가 한 번에 너무 큰 작업을 맡으면 다음 문제가 자주 생깁니다.
- 요구하지 않은 파일까지 수정한다.
- 기존 프로젝트 구조와 다른 패턴을 만든다.
- 핵심 기능은 만들었지만 예외 처리가 빠진다.
- 리뷰해야 할 변경량이 너무 커진다.
- 실패했을 때 어디서부터 되돌려야 할지 애매해진다.
그래서 AI 코딩 에이전트를 실무에 잘 쓰려면 “큰 기능을 한 번에 맡기는 능력”보다 작고 검증 가능한 작업으로 쪼개는 능력이 더 중요합니다.
이 글에서는 AI 에이전트에게 일을 맡길 때 기능을 작은 PR 단위로 나누는 방법을 정리해보겠습니다.
왜 작은 PR 단위가 중요할까?
사람 개발자에게도 큰 PR은 리뷰하기 어렵습니다. 파일이 수십 개 바뀌고, UI·API·상태 관리·테스트·리팩터링이 한 번에 섞이면 변경 의도를 파악하기 힘듭니다.
AI 에이전트가 만든 큰 변경은 더 조심해야 합니다. AI는 사용자의 의도를 바탕으로 빈 부분을 추론합니다. 문제는 이 추론이 항상 프로젝트의 실제 규칙과 맞지 않는다는 점입니다.
예를 들어 “회원 관리 기능을 만들어줘”라고 요청하면 AI는 다음 작업을 한 번에 하려고 할 수 있습니다.
- 라우트 추가
- 페이지 UI 작성
- API 클라이언트 작성
- 상태 관리 추가
- 테이블 컴포넌트 생성
- 권한 체크 추가
- 테스트 작성
- 기존 폴더 구조 변경
겉으로는 생산적이어 보이지만, 리뷰하는 입장에서는 위험합니다. 변경 범위가 크면 작은 오류도 숨어들기 쉽고, 마음에 들지 않는 방향으로 구현됐을 때 되돌리기도 어렵습니다.
작은 PR 단위로 나누면 장점이 분명합니다.
- AI가 임의로 판단할 영역이 줄어듭니다.
- 리뷰할 변경량이 작아집니다.
- 테스트와 검증 기준이 명확해집니다.
- 실패해도 되돌리기 쉽습니다.
- 다음 작업으로 이어가기 편합니다.
즉, 작은 PR은 AI의 속도를 늦추기 위한 장치가 아니라 AI의 결과물을 안전하게 받아들이기 위한 가드레일입니다.
좋은 작업 단위의 기준
AI에게 맡기기 좋은 작업은 “작다”는 말만으로는 부족합니다. 좋은 작업 단위는 다음 조건을 만족해야 합니다.
1. 변경 목적이 하나여야 한다
하나의 작업에는 하나의 목적만 있어야 합니다.
나쁜 예시는 다음과 같습니다.
회원 목록 페이지를 만들고, API도 붙이고, 권한 처리도 하고, 디자인도 다듬고, 테스트도 작성해줘.
좋은 예시는 다음과 같습니다.
기존 Table 컴포넌트를 사용해서 회원 목록 페이지의 정적 UI만 작성해줘. API 연동은 하지 말고 목 데이터로만 구성해줘.
목적이 하나이면 AI가 판단해야 할 범위가 줄어듭니다. 리뷰어도 “이번 변경이 UI 구조만 다루는지” 확인하면 됩니다.
2. 완료 기준이 있어야 한다
AI에게 “적당히 만들어줘”라고 하면 AI는 그럴듯한 결과를 만듭니다. 하지만 실무에서는 “그럴듯함”보다 “완료 기준”이 필요합니다.
예를 들어 UI 작업이라면 완료 기준을 이렇게 적을 수 있습니다.
- /members 경로에서 회원 목록 화면이 보여야 한다.
- 기존 Button, Input, Table 컴포넌트를 재사용해야 한다.
- 새 API 호출 코드는 작성하지 않는다.
- 반응형은 최소 768px 이상 화면에서 깨지지 않으면 된다.
- 변경 파일 목록을 마지막에 요약한다.
이렇게 기준을 주면 AI의 결과물을 검증하기 쉬워집니다.
3. 되돌릴 수 있어야 한다
좋은 작업 단위는 실패했을 때 되돌리기 쉽습니다. 특정 컴포넌트 하나, 테스트 하나, API 함수 하나처럼 경계가 분명해야 합니다.
반대로 다음 작업은 되돌리기 어렵습니다.
- 전체 폴더 구조 변경
- 상태 관리 라이브러리 교체
- 디자인 시스템 전면 수정
- 여러 페이지의 공통 로직 동시 변경
이런 작업은 AI에게 맡기더라도 먼저 설계 문서나 변경 계획을 만들고, 실제 구현은 여러 단계로 나누는 것이 좋습니다.
기능을 작은 PR로 쪼개는 예시
예를 들어 “회원 관리 페이지”를 만든다고 해보겠습니다. 한 번에 요청하면 너무 큽니다.
큰 요청은 이렇게 생겼습니다.
관리자용 회원 관리 페이지를 만들어줘. 회원 목록을 보여주고, 검색하고, 상세 페이지도 볼 수 있게 해줘.
이 요청을 작은 작업으로 나누면 다음과 같습니다.
1단계: 화면 구조만 만들기
- /admin/members 라우트 추가
- 페이지 제목, 검색 영역, 테이블 영역 배치
- 목 데이터 사용
- API 연동 없음
AI에게 줄 요청 예시는 다음과 같습니다.
회원 관리 기능 중 1단계만 구현해줘.
/admin/members 페이지에 정적 UI를 만든다.
기존 Layout, Button, Input, Table 컴포넌트를 우선 재사용한다.
API 연동은 하지 말고 파일 내부의 목 데이터만 사용한다.
작업 후 변경 파일과 의도하지 않은 수정이 있었는지 요약해줘.
2단계: 조회 API 함수 추가
- getMembers API 함수 작성
- 타입 정의
- 에러 응답 타입 정리
- 화면 연결은 아직 하지 않음
이번 작업에서는 회원 목록 조회 API 함수만 추가해줘.
UI 파일은 수정하지 않는다.
API 경로는 GET /api/admin/members 를 사용한다.
응답 타입은 MemberListResponse로 정의한다.
테스트 가능한 순수 함수 형태를 유지해줘.
3단계: UI와 API 연결
- 기존 목 데이터 제거
- 로딩 상태 추가
- 실패 메시지 추가
- 성공 시 테이블 렌더링
4단계: 검색 조건 추가
- 검색어 상태 추가
- 검색 버튼 클릭 시 API 재호출
- 빈 검색어 처리
5단계: 테스트 작성
- 목록 렌더링 테스트
- 로딩 상태 테스트
- API 실패 상태 테스트
- 검색 조건 테스트
이렇게 나누면 각 단계가 하나의 작은 PR이 됩니다. AI가 실수하더라도 어느 단계에서 문제가 생겼는지 찾기 쉽습니다.
AI에게 작업을 맡길 때 포함하면 좋은 문장
작업을 작게 나누는 것만큼 중요한 것이 요청 문장입니다. 다음 문장들은 AI 에이전트에게 일을 맡길 때 유용합니다.
수정 범위 제한
이번 작업에서는 아래 파일만 수정해줘.
- src/pages/admin/members.tsx
- src/components/members/MemberTable.tsx
다른 파일 수정이 필요하면 먼저 이유를 설명하고 작업을 멈춰줘.
구현 제외 항목 명시
이번 단계에서는 API 연동, 권한 처리, 테스트 작성은 하지 않는다.
정적 UI 구성만 완료한다.
기존 패턴 우선 사용
새로운 상태 관리 방식이나 UI 라이브러리를 추가하지 말고,
기존 프로젝트에서 사용 중인 패턴을 먼저 찾아서 그대로 따라줘.
검증 명령 지정
작업 후 다음 명령을 실행해줘.
- pnpm typecheck
- pnpm lint
테스트를 실행하지 못했다면 이유를 남겨줘.
결과 요약 요청
마지막에 다음 형식으로 요약해줘.
1. 변경 파일
2. 구현한 내용
3. 구현하지 않은 내용
4. 확인한 명령
5. 다음 작업 제안
이런 문장을 반복해서 사용하면 AI가 더 예측 가능한 방식으로 작업합니다.
작은 PR 체크리스트
AI 에이전트에게 작업을 맡기기 전에 아래 체크리스트를 확인하면 좋습니다.
- 이번 작업의 목적이 하나인가?
- 수정 가능한 파일 범위가 정해져 있는가?
- 구현하지 않을 항목을 명시했는가?
- 완료 기준이 문장으로 적혀 있는가?
- 검증 명령이 정해져 있는가?
- 실패했을 때 되돌리기 쉬운가?
- 다음 작업과의 경계가 분명한가?
이 중 2~3개 이상이 애매하다면 아직 AI에게 구현을 맡기기보다, 먼저 작업 계획을 더 쪼개는 편이 좋습니다.
AGENTS.md와 Spec 문서를 함께 쓰기
기존 글에서 다룬 것처럼 AGENTS.md는 AI 에이전트에게 프로젝트의 공통 규칙을 알려주는 파일입니다. 예를 들어 패키지 매니저, 테스트 명령, 코드 스타일, 금지할 작업 등을 적어둘 수 있습니다.
반면 작은 PR 단위의 작업 지시는 특정 기능에 대한 세부 요청입니다.
역할을 나누면 다음과 같습니다.
- AGENTS.md: 프로젝트 전체 규칙
- 기능 Spec 문서: 기능의 요구사항과 완료 기준
- 작업 프롬프트: 이번 단계에서 수행할 작은 변경
AI 에이전트는 이 세 가지가 함께 있을 때 훨씬 안정적으로 동작합니다. 프로젝트 규칙을 알고, 기능 요구사항을 이해하고, 지금 해야 할 작은 작업만 수행하기 때문입니다.
결론: AI에게 일을 잘 시키는 핵심은 작업을 작게 만드는 것
AI 코딩 에이전트는 빠릅니다. 하지만 빠르다는 이유로 큰 작업을 한 번에 맡기면 리뷰와 유지보수 비용이 커질 수 있습니다.
실무에서 중요한 것은 AI가 코드를 많이 쓰게 하는 것이 아니라, 작고 검증 가능한 단위로 안전하게 변경하게 만드는 것입니다.
정리하면 다음과 같습니다.
- AI에게 큰 기능을 한 번에 맡기면 수정 범위가 커질 수 있습니다.
- 작은 PR 단위는 리뷰와 롤백을 쉽게 만듭니다.
- 좋은 작업 단위는 목적이 하나이고 완료 기준이 분명해야 합니다.
- 구현하지 않을 항목을 명시하면 AI의 과잉 구현을 줄일 수 있습니다.
- AGENTS.md, Spec 문서, 작업 프롬프트를 나누어 관리하면 효과적입니다.
다음에 AI 에이전트에게 기능 구현을 맡길 때는 바로 “만들어줘”라고 말하기보다, 먼저 이렇게 물어보는 것이 좋습니다.
이 기능을 리뷰 가능한 작은 PR 단위로 나누면 어떻게 될까?
이 질문 하나가 AI 코딩의 품질을 크게 바꿀 수 있습니다.
SEO 메타 설명 후보
AI 코딩 에이전트가 과도한 파일 수정이나 요구사항 누락을 만들지 않도록, 기능을 작은 PR 단위로 쪼개고 검증하는 실무 방법을 정리합니다.