AI 에이전트를 잘 쓰는 사람과 그렇지 않은 사람의 차이는 프롬프트 문장력이 아니라 작업을 자르는 능력에서 갈립니다. "이 기능 전체를 만들어줘"라고 맡기면 에이전트는 빠르게 많은 파일을 바꾸지만, 리뷰할 사람은 무엇이 핵심 변경인지 찾기 어렵습니다. 반대로 작고 검증 가능한 지시서를 주면 에이전트의 속도는 유지하면서도 결과를 사람이 통제할 수 있습니다.

이 글은 AI 코딩에서 가장 실전적인 습관인 작은 범위 작업 지시서 작성법을 다룹니다. 초보자에게는 "어디까지 말해야 하는지"를 알려 주고, 실무자에게는 여러 에이전트나 팀원이 동시에 움직여도 충돌을 줄이는 운영 단위를 제공합니다.

핵심 결론

AI 에이전트에게 맡길 작업은 한 번에 하나의 검증 가능한 문제로 잘라야 합니다. 좋은 지시서는 긴 요구사항 문서가 아니라, 다음 다섯 가지를 짧게 고정한 실행 카드입니다.

1. 작업 범위: 이번에 바꿀 사용자 문제와 예상 파일 영역
2. 제외 범위: 이번 작업에서 절대 넓히지 않을 것
3. 완료 기준: 어떤 결과가 보이면 끝인지
4. 검증 명령: 어떤 테스트, 빌드, 스모크로 확인할지
5. 보고 형식: diff 요약, 위험, 롤백 방법을 어떻게 남길지

핵심은 에이전트가 "열심히 많이 고치는 것"을 막고 "작게 끝내고 증거를 남기는 것"에 집중하게 만드는 것입니다. 작은 작업은 느려 보이지만, 리뷰와 배포까지 포함하면 훨씬 빠릅니다.

왜 중요한가

에이전트는 빈칸을 추측으로 채운다

AI 에이전트는 맥락이 비어 있으면 스스로 빈칸을 채웁니다. 예를 들어 "검색 페이지 개선"이라고만 말하면 UI 문구, 필터 로직, API 호출, 캐시 전략, 테스트까지 한 번에 건드릴 수 있습니다. 운이 좋으면 멋진 결과가 나오지만, 실무에서는 다음 문제가 생깁니다.

• 리뷰어가 의도한 변경과 부수 변경을 구분하기 어렵다.
• 실패했을 때 어디서 롤백해야 하는지 모호하다.
• 테스트가 실패해도 원인이 요구사항인지 구현인지 판단하기 어렵다.
• 다음 에이전트가 같은 파일을 다시 고치며 충돌을 만든다.

작은 지시서는 이런 추측을 줄입니다. 에이전트에게 "이번에는 필터가 선택됐을 때 URL 쿼리만 유지한다. 디자인 리뉴얼은 하지 않는다"처럼 경계선을 줍니다. 경계선이 있어야 에이전트의 자율성이 위험이 아니라 생산성이 됩니다.

좋은 컨텍스트는 많은 정보가 아니라 결정된 정보다

초보자는 에이전트에게 모든 배경을 길게 붙여 넣으려는 실수를 합니다. 하지만 컨텍스트는 길다고 좋은 것이 아닙니다. 필요한 것은 결정된 정보입니다. 사용자가 누구인지, 어떤 동작이 문제인지, 이번에 건드릴 수 있는 범위가 어디인지, 무엇을 확인하면 끝인지가 중요합니다.

좋은 지시서는 에이전트가 창의력을 발휘할 위치와 발휘하면 안 되는 위치를 동시에 알려 줍니다.

실제 작업 순서

1단계: 문제를 한 문장으로 압축한다

먼저 사용자 관점의 문제를 한 문장으로 씁니다. 문장은 입력, 행동, 결과를 포함해야 합니다.

• 약한 문장: "목록 UX 개선"
• 강한 문장: "사용자가 태그를 선택하면 목록이 즉시 좁혀지고 새로고침 후에도 같은 태그가 유지된다"

이 문장이 흐릿하면 작업 범위도 흐릿해집니다. 에이전트에게 구현을 맡기기 전에 먼저 이 문장을 다듬게 해도 좋습니다. 다만 다듬는 작업과 구현 작업은 분리합니다.

2단계: 작업 범위와 제외 범위를 나란히 쓴다

작업 범위만 쓰면 에이전트는 관련 있어 보이는 것을 계속 넓힙니다. 제외 범위까지 써야 안전합니다.

작업 범위:
- 태그 필터 선택 상태를 URL 쿼리와 동기화
- 기존 목록 컴포넌트의 렌더링 구조 유지
- 필터 동작을 확인하는 테스트 추가

제외 범위:
- 카드 디자인 개편 금지
- 데이터 모델 변경 금지
- 검색 랭킹 알고리즘 변경 금지

제외 범위는 에이전트의 발목을 잡는 문장이 아니라 팀의 시간을 지키는 안전장치입니다. 리뷰어는 제외 범위만 봐도 불필요한 diff를 빠르게 찾아낼 수 있습니다.

3단계: 완료 기준을 관찰 가능한 상태로 만든다

"잘 동작한다"는 완료 기준이 아닙니다. 완료 기준은 사람이 다시 실행할 수 있어야 합니다.

• 태그를 클릭하면 URL에 선택 값이 남는다.
• 새로고침 후 같은 태그 필터가 유지된다.
• 빈 결과일 때 안내 문구가 보인다.
• 기존 전체 목록 링크는 그대로 작동한다.

완료 기준은 테스트 이름으로 거의 그대로 옮겨질 수 있어야 합니다. 만약 테스트 이름으로 바꾸기 어렵다면 아직 기준이 추상적이라는 신호입니다.

4단계: 검증 명령과 수동 스모크를 함께 지정한다

검증 명령은 에이전트가 마지막에 "했습니다"라고 말하기 전에 반드시 실행해야 하는 체크포인트입니다. 프로젝트마다 명령은 다르지만 구조는 비슷합니다.

검증 명령:
- 관련 단위 테스트 1개
- 전체 린트
- 프로덕션 빌드
- 전체 테스트

수동 스모크:
- 목록 페이지 열기
- 태그 선택하기
- 새로고침하기
- 콘솔 오류 확인하기

여기서 중요한 것은 명령 이름보다 증거입니다. 에이전트의 최종 보고에는 어떤 검증을 실행했고 결과가 어땠는지, 실패했다면 무엇을 고쳤는지가 남아야 합니다.

5단계: 보고 형식을 미리 정한다

작업이 끝난 뒤 보고 형식을 요구하면 에이전트가 중요한 정보를 빠뜨릴 수 있습니다. 처음부터 다음 항목을 요구합니다.

• 변경 요약: 사용자에게 보이는 변화 2~3줄
• 주요 diff: 어떤 파일과 책임이 바뀌었는지
• 검증 결과: 실행한 테스트와 빌드 결과
• 남은 위험: 의도적으로 제외한 범위나 확인하지 못한 환경
• 롤백 방법: 문제가 생기면 어떤 커밋 또는 파일 단위로 되돌릴지

이 형식은 사람 리뷰에도 좋고, 다음 에이전트에게 넘길 컨텍스트로도 좋습니다.

상황별 예시

예시 1: 버그 수정 지시서

문제:
모바일에서 저장 버튼을 두 번 누르면 같은 항목이 중복 생성된다.

작업 범위:
저장 요청 중 버튼을 잠그고, 중복 클릭을 막는 테스트를 추가한다.

제외 범위:
저장 API 구조 변경, 새 알림 디자인 추가, 목록 정렬 변경은 하지 않는다.

완료 기준:
빠르게 두 번 클릭해도 요청은 한 번만 발생하고, 버튼 상태가 사용자에게 보인다.

검증:
중복 클릭 테스트, 전체 린트, 빌드, 관련 페이지 수동 스모크.

이 정도면 에이전트가 구현 방향을 잡을 수 있고, 동시에 불필요한 리팩터링을 피할 수 있습니다.

예시 2: 리팩터링 지시서

문제:
결제 요약 컴포넌트 안에 가격 포맷팅 로직이 세 군데 반복된다.

작업 범위:
가격 포맷팅 helper를 만들고 기존 화면 출력이 바뀌지 않도록 테스트한다.

제외 범위:
결제 계산식, 통화 정책, 레이아웃은 변경하지 않는다.

완료 기준:
렌더링 결과가 기존과 같고 중복 로직만 제거된다.

리팩터링은 특히 제외 범위가 중요합니다. 에이전트가 "정리"라는 단어를 보고 구조 전체를 바꾸기 쉽기 때문입니다.

예시 3: 새 기능 탐색 지시서

새 기능은 바로 구현하지 말고 탐색과 구현을 분리합니다.

1차 작업: 구현하지 말고 현재 구조, 필요한 파일, 위험한 의존성, 테스트 위치만 조사한다.
2차 작업: 조사 결과를 바탕으로 가장 작은 사용자 흐름 하나만 구현한다.

탐색 작업의 산출물은 코드가 아니라 계획이어야 합니다. 이렇게 분리하면 에이전트가 모르는 상태에서 큰 diff를 만드는 일을 줄일 수 있습니다.

실수와 주의점

실수 1: 작은 작업을 단순 작업으로 착각한다

작은 작업은 대충 해도 되는 작업이 아닙니다. 오히려 더 정확해야 합니다. "버튼 문구 수정"처럼 작아 보이는 작업도 접근성 이름, 번역, 테스트 스냅샷, SEO 문구에 영향을 줄 수 있습니다. 작게 자르되 완료 기준은 선명하게 둡니다.

실수 2: 제외 범위를 예의상 한 줄만 쓴다

제외 범위가 약하면 에이전트는 "관련 개선"을 계속 제안합니다. 이번 작업에서 하지 않을 것을 적극적으로 적으세요. 특히 디자인 개편, 데이터 구조 변경, 인증 흐름 변경, 대규모 파일 이동은 명시적으로 막는 편이 안전합니다.

실수 3: 검증을 마지막에 에이전트 재량으로 둔다

검증 명령을 마지막에 생각하면 에이전트는 구현에 맞는 검증만 고를 수 있습니다. 지시서에 먼저 넣어야 합니다. 그래야 테스트를 통과시키기 위해 구현이 좁아지고, 실패했을 때도 원인을 빨리 찾습니다.

실수 4: 한 지시서에 여러 목표를 넣는다

"필터 개선, 카드 디자인 정리, 로딩 속도 개선"은 세 개의 작업입니다. 하나로 묶으면 diff가 커지고 실패 원인이 섞입니다. 에이전트에게는 작은 성공을 여러 번 만들게 하는 편이 안전합니다.

검증 체크리스트

작업 지시서를 보내기 전에 다음 질문에 답해 보세요.

• 이 작업의 사용자 문제를 한 문장으로 말할 수 있는가?
• 작업 범위와 제외 범위가 둘 다 있는가?
• 완료 기준이 화면, 응답, 테스트 결과처럼 관찰 가능한가?
• 에이전트가 실행할 검증 명령이 명시되어 있는가?
• diff가 커졌을 때 멈추고 보고하라는 기준이 있는가?
• 실패하면 어떤 단위로 롤백할지 설명할 수 있는가?
• 최종 보고에 리뷰 포인트와 남은 위험을 요구했는가?

이 체크리스트 중 두 개 이상 비어 있다면 아직 구현을 맡기지 말고 지시서를 먼저 다듬는 것이 좋습니다.

다음 단계

처음부터 완벽한 지시서를 만들 필요는 없습니다. 다음 작업부터 작은 템플릿 하나를 복사해 쓰면 됩니다.

목표:
사용자 관점의 문제 한 문장.

작업 범위:
이번에 바꿀 동작과 파일 영역.

제외 범위:
이번에 하지 않을 변경.

완료 기준:
통과해야 하는 테스트, 화면 상태, 응답 상태.

검증:
실행할 자동 검증과 수동 스모크.

보고:
변경 요약, 주요 diff, 검증 결과, 위험, 롤백 방법.

이 템플릿을 팀의 기본 언어로 삼으면 AI 에이전트는 더 예측 가능한 동료가 됩니다. 프롬프트를 길게 쓰는 것보다 작업을 작게 자르고, 완료 기준을 선명하게 만들고, 검증 증거를 남기는 습관이 훨씬 강력합니다.