AI 에이전트에게 일 맡기는 법: 작업 지시서 쓰기

AI 에이전트에게 일을 맡길 때 필요한 것은 좋은 질문이 아니라 작업 지시서입니다. 질문은 답을 받고 끝나지만, 지시서는 에이전트가 여러 단계를 스스로 판단하며 진행하는 동안 계속 참조되는 기준이 되기 때문입니다. 지시서에는 여섯 가지가 들어갑니다. 목표, 완료 조건, 맥락, 하지 말아야 할 것, 권한 범위, 보고 형식입니다. 이 중 완료 조건과 경계를 빼먹는 경우가 압도적으로 많고, 대부분의 실패가 거기서 나옵니다.

왜 "잘 물어보기"만으로는 부족한가?

챗봇에게 묻는 상황과 에이전트에게 맡기는 상황은 정보 구조가 다릅니다. 챗봇은 답이 마음에 들지 않으면 곧바로 다시 물으면 됩니다. 사람이 매 턴 개입하므로, 첫 지시가 부정확해도 대화로 교정됩니다.

에이전트는 지시를 받은 뒤 사람 없이 여러 단계를 진행합니다. 중간에 판단이 필요한 지점이 나오면 지시서에 적힌 내용을 근거로 스스로 결정합니다. 지시서에 없는 것은 모델이 알아서 추정하고, 그 추정이 다음 단계의 전제가 됩니다. 다섯 단계쯤 지나면 원래 의도와 상당히 멀어져 있을 수 있습니다.

그래서 지시서는 "무엇을 해라"보다 "무엇을 기준으로 판단해라"에 가깝게 써야 합니다. 사람에게 일을 넘길 때 배경과 제약을 함께 설명하는 것과 같은 이유입니다.

지시서에 반드시 들어가는 여섯 가지

여섯 항목이 모두 길 필요는 없습니다. 각 한두 문장이면 충분하고, 짧아도 있는 것과 없는 것의 차이가 큽니다.

목표는 어떻게 써야 하나?

목표는 동사가 아니라 상태로 씁니다. "정리해라", "개선해라", "조사해라"는 동사이고 끝이 없습니다. "정리된 결과가 어떤 상태인가"를 적어야 판정할 수 있습니다.

• 나쁜 예: 회의록을 정리해라.
• 좋은 예: 회의록에서 결정 사항과 액션 아이템을 뽑아, 각 액션 아이템에 담당자와 기한이 채워진 표를 만들어라. 기록에 없으면 '미정'으로 남겨라.

좋은 예에는 완료 조건이 이미 녹아 있습니다. 표가 있는가, 항목마다 담당자와 기한 칸이 채워졌는가로 판정됩니다. 목표를 상태로 쓰면 완료 조건이 따라오는 경우가 많습니다.

완료 조건은 참·거짓으로 떨어져야 합니다. "읽기 좋게"는 판정할 수 없고, "각 항목이 세 문장 이내"는 판정할 수 있습니다. 판정 불가능한 기준은 환각이 통과하는 통로가 됩니다.

맥락은 얼마나 줘야 하나?

필요한 만큼만입니다. 맥락은 많을수록 좋은 것이 아니라, 컨텍스트 윈도우를 소모하는 자원입니다. 작업과 무관한 배경을 잔뜩 넣으면 정작 중요한 제약이 묻힙니다.

넣어야 할 것은 세 종류입니다.

• 에이전트가 알 수 없는 사실 — 사내 규칙, 진행 중인 사정, 이전 결정. 코드나 파일을 읽어서 알 수 있는 것은 굳이 적지 않아도 됩니다.
• 판단이 갈리는 지점의 선택 기준 — "속도보다 정확성", "기존 형식을 유지" 같은 우선순위입니다.
• 참고할 위치 — 파일 경로, 기존 예시. 설명하는 것보다 "이것과 같은 형식으로"가 훨씬 정확합니다.

반복되는 맥락이라면 매번 적는 대신 파일로 고정하는 편이 낫습니다. 프로젝트 규칙을 파일에 담는 방법은 CLAUDE.md 작성법에서 다룹니다.

하지 말아야 할 것은 어떻게 적나?

경계는 지시서에서 가장 자주 빠지고, 빠졌을 때 가장 성가신 결과를 만드는 항목입니다. 에이전트는 목표를 잘 달성하려는 방향으로 움직이므로, 명시하지 않으면 "도움이 될 것 같은" 일을 추가로 합니다. 요청하지 않은 리팩터링, 임의의 파일 정리, 형식 통일 같은 것들입니다.

효과적인 경계는 구체적입니다. "마음대로 하지 마라"는 작동하지 않고, "이 디렉터리 바깥의 파일은 수정하지 마라", "의존성을 새로 추가하지 마라", "기존 함수 시그니처를 바꾸지 마라"는 작동합니다.

권한 범위는 경계 중에서도 따로 떼어 적습니다. 읽기만 할 것인지, 새 파일 생성까지 할 것인지, 기존 파일 수정과 삭제까지 할 것인지, 외부로 전송해도 되는지를 명시합니다. 되돌리기 어려운 행동에는 가드레일로 사람 확인을 두는 것이 기본입니다.

보고 형식을 정해 두면 무엇이 달라지나?

확인 비용이 달라집니다. 형식을 정하지 않으면 에이전트는 대개 잘한 일을 길게 서술한 산문을 돌려주고, 사람은 그 산문을 읽으며 실제로 무엇이 바뀌었는지 추측해야 합니다.

보고 형식에 넣으면 좋은 항목은 세 가지입니다. 무엇을 변경했는지 목록, 완료 조건 각각에 대한 통과 여부, 그리고 확신이 낮거나 임의로 판단한 부분입니다. 세 번째가 특히 중요합니다. 지시서에 없어서 스스로 추정한 지점을 밝히게 하면, 다음 지시서에서 무엇을 보완해야 하는지 그대로 드러납니다.

다만 보고 자체가 검증은 아닙니다. 에이전트의 완료 보고를 어떻게 확인할지는 AI 완료 보고 검증하기에서 따로 정리했습니다.

한 지시서를 고쳐 쓴다면

여섯 항목이 실제로 무엇을 바꾸는지는 같은 요청을 두 번 써 보면 분명해집니다.

고치기 전입니다. "우리 문서 사이트의 검색이 좀 느린데 개선해줘." 한 문장이고, 목표를 빼면 아무것도 없습니다. 에이전트는 느리다는 기준이 무엇인지, 어디까지 손대도 되는지, 무엇을 보면 끝인지를 전부 스스로 정합니다. 십중팔구 검색 코드뿐 아니라 주변 모듈까지 함께 바뀐 결과가 돌아옵니다.

고친 뒤입니다.

• 목표: 문서 검색 API의 응답 시간이 로컬 벤치마크 기준으로 현재의 절반 이하가 된 상태
• 완료 조건: 기존 테스트 전부 통과, 벤치마크 스크립트 결과가 개선 전보다 빠름, 검색 결과 순서가 변경 전과 동일
• 맥락: 인덱스는 lib/search-index.ts에서 매 요청마다 새로 만들어집니다. 정확도보다 속도가 우선입니다
• 하지 말 것: 검색 알고리즘 자체 교체, 새 의존성 추가, lib/ 바깥 파일 수정
• 권한: 파일 읽기와 수정까지. 삭제와 외부 전송은 금지
• 보고: 변경 파일 목록, 완료 조건 3개 각각의 통과 여부, 임의로 판단한 부분

달라진 것은 정보의 양이 아니라 판단 여지의 양입니다. 고친 지시서에서 에이전트가 스스로 정할 수 있는 것은 "어떻게 빠르게 만들 것인가" 하나뿐이고, 나머지는 전부 고정되어 있습니다. 좋은 지시서는 자유를 주는 문서가 아니라 자유를 한 군데로 모으는 문서입니다.

매번 위처럼 풀어 쓸 필요는 없습니다. 여섯 항목을 그대로 채우는 틀을 두고 쓰면 됩니다.

목표: (달성된 상태를 한 문장으로)
완료 조건: (참·거짓으로 판정되는 항목 2~4개)
맥락: (에이전트가 알 수 없는 사실, 참고할 위치)
하지 말 것: (건드리면 안 되는 범위)
권한: (읽기 / 파일 생성 / 수정·삭제 / 외부 전송 중 허용 범위)
보고: (변경 목록 + 완료 조건 통과 여부 + 임의 판단한 부분)

처음에는 여섯 줄이 번거롭게 느껴지지만, 잘못된 결과를 되돌리는 시간보다 훨씬 짧습니다. 지시서 품질이 결과에 미치는 영향은 프롬프트 엔지니어링의 연장선에 있되, 여러 단계를 도는 에이전트에서는 그 영향이 훨씬 크게 누적됩니다.

FAQ

• Q. 지시서가 길면 오히려 헷갈리지 않나요?

  • A. 길이보다 구조가 중요합니다. 여섯 항목으로 나뉘어 있으면 각 항목이 짧아도 작동하고, 항목 구분 없이 긴 산문이면 오히려 중요한 제약이 묻힙니다. 각 항목 한두 문장을 기준으로 삼으세요.

• Q. 매번 여섯 항목을 다 적어야 하나요?

  • A. 반복되는 항목은 파일로 고정해 두고, 매번 달라지는 목표·완료 조건·맥락만 적으면 됩니다. 특히 권한과 경계는 프로젝트 단위로 한 번 정해 두는 편이 안전합니다.

• Q. 지시서를 잘 썼는데도 결과가 틀리면요?

  • A. 보고에서 "임의로 판단한 부분"을 확인하세요. 대개 지시서에 없던 지점을 에이전트가 추정한 곳에서 어긋납니다. 그 지점을 다음 지시서의 맥락이나 경계에 추가하면 같은 실패가 반복되지 않습니다. 자주 나오는 실패 유형은 AI 에이전트가 실패하는 5가지 패턴에서 정리했습니다.

정리

• 에이전트에게는 질문이 아니라 지시서를 줍니다. 사람 개입 없이 여러 단계를 도는 동안 계속 참조되는 기준이기 때문입니다.
• 여섯 항목은 목표, 완료 조건, 맥락, 경계, 권한, 보고 형식입니다.
• 목표는 동사가 아니라 달성된 상태로 씁니다. 그러면 완료 조건이 따라옵니다.
• 경계와 권한은 가장 자주 빠지고 가장 비싼 결과를 만듭니다. 구체적인 범위로 적으세요.
• 보고에 "임의로 판단한 부분"을 넣게 하면 다음 지시서에서 무엇을 보완할지 드러납니다.