AI 코딩 에이전트에게 재작업 없이 일을 맡기는 작업 요청 설계법How to Design Task Requests for AI Coding Agents Without Rework
📅
들어가기 전에 🔗
“로그인 오류를 고쳐 주세요”는 사람에게도 모호하지만, AI 코딩 에이전트에게는 특히 넓은 탐색 요청입니다.
에이전트는 로그인 화면, API, 세션, 환경 변수, 테스트를 모두 살펴보며 가능한 원인을 모두 추측해야 합니다.
그리고 결과는 그리 좋지 않다는 것은 다들 알고 계실것입니다.
좋은 작업 요청은 프롬프트가 아니라, 에이전트가 제대로 실행할 수 있는 작은 작업 계약(단위)입니다.
이 글에서는 작업의 목표·범위·제약·완료 조건을 빠짐없이 전달하는 요청 구조를 정리하는 시간을 가져보겠습니다.👨💻
에이전트에게 맡기는 일의 크기는 PR 하나가 아니라 “검증 가능한 결과 하나”에 맞추는 편이 좋습니다. 작은 계약은 탐색 범위를 줄이고, 실패했을 때 원인을 찾기도 쉽게 만듭니다.
AI 에이전트 작업 요청을 구성하는 목표 범위 제약 완료 조건 검증 판단 경계 인포그래픽
작업 계약 🔗
에이전트가 잘못된 코드를 만드는 이유는 능력이 부족해서가 아니라, 완료의 정의가 비어 있는 경우가 많습니다.
작업 요청에는 아래 여섯 항목을 넣습니다.
모든 항목을 길게 설명할 필요는 없지만, 에이전트가 추측하면 위험한 부분은 반드시 명시합니다.
| 항목 | 질문 | 예시 |
|---|---|---|
| 목표 | 무엇이 달라져야 하나요 | 비밀번호 재설정 화면에서 만료된 링크를 안내합니다. |
| 범위 | 어디를 바꿀 수 있나요 | apps/web과 해당 API 핸들러만 수정합니다. |
| 제약 | 무엇을 건드리면 안 되나요 | 기존 재설정 토큰 형식과 공개 API는 유지합니다. |
| 완료 조건 | 언제 끝난 일인가요 | 만료 링크에 안내 화면이 보이고 정상 링크는 기존처럼 동작합니다. |
| 검증 | 무엇으로 확인하나요 | 관련 단위 테스트와 pnpm lint를 실행합니다. |
| 판단 경계 | 언제 멈춰 물어봐야 하나요 | DB 스키마 변경이나 메일 템플릿 수정이 필요하면 먼저 질문합니다. |
OpenAI의 Codex 가이드도
AGENTS.md, 스킬, 작업 프롬프트처럼 에이전트의 일을 정하는 지침을 최신 상태로 유지하고, 작업에 맞는 문서를 가리키라고 권장합니다.
OpenAI Developers의 지침 설계 원칙↗나쁜 요청과 좋은 요청 🔗
같은 기능이라도 요청의 구조에 따라 에이전트가 읽는 범위와 결과가 달라집니다.
로그인 오류를 고쳐 주세요.이 요청에는 오류의 증상, 변경 가능 범위, 테스트, 기존 동작 보존 조건이 없습니다.
에이전트가 넓게 조사하거나, 가장 가까운 코드를 고쳐서 의도와 다른 해결을 낼 가능성이 큽니다.
## 목표
만료된 비밀번호 재설정 링크를 열면 안내 화면을 표시합니다.
## 범위
- apps/web의 재설정 페이지와 apps/api의 토큰 검증 핸들러만 수정합니다.
- 기존 정상 토큰 흐름은 바꾸지 않습니다.
## 완료 조건
- 만료 토큰은 안내 화면을 표시합니다.
- 유효 토큰은 현재 비밀번호 변경 화면을 표시합니다.
- 관련 테스트와 pnpm lint가 통과합니다.
## 판단 경계
- DB 스키마, 토큰 형식, 메일 문구 변경이 필요하면 구현 전에 질문합니다.두 번째 요청은 에이전트에게 구현 방향을 강요하지 않습니다.
대신
어디까지 스스로 결정해도 되는지와, 무엇을 보존해야 하는지
를 분명하게 만듭니다.👍
구현 방법을 지나치게 고정하면 더 단순하고 안전한 해결책을 막을 수 있습니다. “React 상태를 세 개 추가하세요”보다 “만료 상태를 사용자에게 구분해 보여 주세요”처럼 결과와 경계를 먼저 적습니다.
모호한 요청과 작업 계약형 요청의 정보 차이를 비교하는 인포그래픽
범위와 경계 🔗
작업 요청에서 가장 중요한 문장은 “무엇을 하지 말아야 하는가”일 때가 많습니다.
에이전트는 문제를 해결하려고 자연스럽게 더 넓은 영역을 만질 수 있기 때문입니다.
변경 경계 🔗
다음 세 가지를 나누어 적으면 불필요한 확장을 막을 수 있습니다.
- 수정 가능 영역바꿔도 되는 디렉터리, 파일, API를 지정합니다.
- 보존해야 할 계약호환성을 지켜야 할 공개 API, 데이터 형식, 사용자 흐름을 적습니다.
- 질문해야 할 조건스키마, 결제, 권한, 배포처럼 팀의 판단이 필요한 지점을 적습니다.
🖐️
“필요하면 리팩터링하세요”처럼 열린 권한을 기본값으로 두지 않습니다. 요청과 직접 관련 없는 대규모 리팩터링, 의존성 교체, 스키마 변경은 별도 작업으로 분리합니다.작업이 크다면 한 번의 긴 요청으로 해결하려 하지 말고, 먼저 조사 계약을 만듭니다.
예를 들어 “원인과 변경 후보를 정리하고, 수정 전 계획을 제안해 주세요”로 시작한 다음 구현 계약을 따로 넘깁니다.
이 분리는 큰 변경에서 되돌리기 쉬운 선택입니다.
완료 조건 🔗
“구현했습니다”는 완료 조건이 아닙니다.
에이전트와 리뷰어가 같은 결과를 확인할 수 있도록 관찰 가능한 조건을 적어야 합니다.
| 종류 | 모호한 표현 | 확인 가능한 표현 |
|---|---|---|
| 화면 | 오류를 잘 보여 주세요 | 만료 링크에서 제목·재요청 버튼·도움말 링크를 표시합니다. |
| API | 안전하게 처리하세요 | 잘못된 토큰에 400을 반환하고 사용자 정보는 노출하지 않습니다. |
| 테스트 | 테스트해 주세요 | 만료·유효·누락 토큰의 테스트를 추가하고 실행합니다. |
| 성능 | 느리지 않게 만드세요 | 추가 네트워크 요청 없이 기존 토큰 검증 흐름을 사용합니다. |
AI 에이전트 작업 계약의 요청 검토 구현 검증 질문 루프를 보여주는 인포그래픽
요청 템플릿 🔗
아래 템플릿을 이슈, PR 설명, 에이전트 대화의 시작점으로 사용해 보시기 바랍니다.
# 목표
<사용자에게 달라져야 하는 결과>
# 범위
- <수정 가능한 경로>
- <보존해야 하는 기존 흐름>
# 완료 조건
- <관찰 가능한 결과 1>
- <관찰 가능한 결과 2>
- <실행할 검증 명령>
# 판단 경계
- <질문이 필요한 변경>
- <명시적으로 제외한 작업>
# 전달 결과
- 변경한 파일과 이유를 요약합니다.
- 실행한 검증 명령과 결과를 기록합니다.
- 남은 위험 또는 결정이 있으면 적습니다.요청을 쓰는 시간이 조금 늘어도, 에이전트의 재탐색과 리뷰 왕복이 줄면 전체 시간은 더 짧아집니다.
특히 팀에서 반복되는 변경은 이 형식을 이슈 템플릿으로 만들면 품질 기준을 공유하기 쉽습니다.
팀 체크리스트 🔗
✓ 목표가 사용자나 시스템의 관찰 가능한 변화로 적혀 있습니다.
✓ 수정 가능 경로와 보존해야 할 계약이 구분되어 있습니다.
✓ 완료 조건에 테스트 또는 검증 명령이 포함되어 있습니다.
✓ 추가 판단이 필요한 지점은 질문 경계로 분리했습니다.
✓ 작업 범위보다 큰 리팩터링은 별도 계약으로 나눴습니다.
결론 🔗
AI 코딩 에이전트에게 좋은 요청은 더 긴 요청이 아닙니다.
목표, 범위, 제약, 완료 조건, 검증, 판단 경계를 빠짐없이 담은
명료한 작업 계약
이 핵심입니다.에이전트가 추측할 자리를 줄이고 확인할 기준을 늘리면, 결과물의 품질과 팀의 리뷰 속도를 함께 높일 수 있습니다.