AI 코딩 에이전트에게 일 맡기는 법: 작업 명세와 검증 루틴

요즘 회사에서 개발하는 방식이 많이 바뀌었습니다. 설계는 제가 하고, 구현은 AI에게 맡깁니다. AI가 테스트까지 마치면 코드 검토는 제가 하고, 고칠 점을 다시 AI에게 넘겨 수정하는 식으로 일합니다.

목차

1. 한눈에 보기
2. 작업 명세에 꼭 넣는 5가지
3. 실제로 겪은 일 4가지
4. 검증 루틴
5. 직접 해보니
6. 마무리
7. 자주 묻는 질문 (FAQ)

이번에 제 블로그 글쓰기 도구를 만들면서 그 방식을 개인 프로젝트에도 그대로 적용해 봤습니다. 구조는 단순합니다. OpenCode에서 도는 AI가 오케스트레이터 역할을 맡아 작업 명세를 쓰고, 그 명세를 작업자 AI인 Claude Code에게 넘깁니다. 작업자가 결과를 보고하면 오케스트레이터가 다시 검증합니다. 저는 방향을 정하고 최종 결과를 확인합니다. 이 과정에서 명세를 어떻게 써야 하는지, 그리고 "다 했다"는 보고를 어디까지 믿어야 하는지 확실히 배웠습니다.

▲ AI 에이전트에게 일 맡기는 흐름

한눈에 보기

작업 명세를 넘기기 전에 확인하는 목록입니다.

• 목표: 무엇을 만드는지 한 문장으로 적었는가
• 범위: 만들 파일과 건드려도 되는 파일을 적었는가
• 완료 조건: 실행해서 확인할 수 있는 명령으로 적었는가 (예: npm test 통과)
• 금지 사항: 하면 안 되는 일을 구체적으로 적었는가
• 보고 형식: 무엇을 바꿨고, 어떻게 확인했고, 무엇을 못 했는지 보고하게 했는가

작업 명세에 꼭 넣는 5가지

1. 목표

"블로그 도구를 만들어 줘"처럼 쓰면 작업자가 알아서 범위를 넓힙니다. 누가, 어떤 상황에서, 무엇을 할 수 있게 되는지를 한 문장으로 적습니다. 제 경우에는 "마크다운으로 쓴 글을 검사하고, 티스토리 에디터에 붙여넣을 HTML로 바꾸는 도구"였습니다.

2. 범위

만들 파일 목록과 허용하는 의존성을 적습니다. 저는 빈 저장소에서 시작하면서 스크립트, 테스트, 문서 파일 목록을 명세에 넣었고, 외부 라이브러리는 marked와 gray-matter 두 개만 허용했습니다. 범위를 적지 않으면 작업자는 필요해 보이는 라이브러리를 계속 추가합니다.

3. 완료 조건

"잘 동작하게"는 완료 조건이 아닙니다. 사람이든 AI든 실행해서 확인할 수 있는 명령으로 적어야 합니다. 제 명세의 완료 조건은 "npm test가 통과한다"였습니다. 이 한 줄이 뒤에서 얼마나 중요했는지는 아래 사례에서 설명하겠습니다.

4. 금지 사항

AI는 시키지 않은 일도 열심히 합니다. 그래서 하지 말아야 할 일을 구체적으로 적습니다. 제가 넣은 금지 사항은 커밋하지 않기, 네트워크 호출과 티스토리 자동화 만들지 않기, 지정하지 않은 설정 파일 수정하지 않기, test.skip으로 테스트 건너뛰지 않기였습니다. 특히 마지막 항목은 테스트가 실패할 때 테스트를 꺼 버리는 식의 "통과"를 막기 위한 것입니다.

5. 보고 형식

작업이 끝나면 무엇을 바꿨는지, 어떤 명령으로 확인했고 결과가 어땠는지, 못 한 일이 무엇인지 보고하게 합니다. 못 한 일을 적는 칸이 있어야 작업자가 그 사실을 숨기지 않습니다.

명세 예시

실제로 쓰는 형식을 일반적인 예로 바꾸면 다음과 같습니다.

## 목표
마크다운 글을 검사하고 HTML로 변환하는 CLI를 만든다.

## 범위
- 만들 파일: scripts/check.mjs, scripts/build.mjs, test/*.test.mjs, README.md
- 허용 의존성: marked, gray-matter (그 외 추가 금지)

## 완료 조건
- npm install 후 npm test가 모두 통과한다.

## 하지 말 것
- 커밋하지 않는다.
- 네트워크 호출, 외부 서비스 자동화를 만들지 않는다.
- 지정하지 않은 설정 파일을 수정하지 않는다.
- test.skip, test.only를 쓰지 않는다.

## 보고
바꾼 파일, 실행한 명령과 결과, 하지 못한 일을 적는다.

실제로 겪은 일 4가지

"완료" 보고와 "검증됨"은 다르다

작업자는 약 6분 반 만에 스크립트, 테스트, 문서까지 파일 21개를 만들었습니다. 그런데 실행 권한이 막혀 있어서 npm install도, 테스트도 돌리지 못했습니다. 다행히 작업자는 보고서에 그 사실을 그대로 적었습니다. "아무것도 실행해 보지 못했습니다."

그래서 오케스트레이터가 직접 npm install과 npm test를 실행했고, 테스트 30개가 모두 통과했습니다. 결과는 좋았지만, 만약 보고서에 "완료"라고만 적혀 있었다면 아무도 실행해 보지 않은 코드를 완성품으로 받았을 것입니다. 완료 조건을 실행 가능한 명령으로 적어 두었기 때문에 누가 실행하든 같은 기준으로 확인할 수 있었습니다.

깨진 한글, 원인을 바로 단정하지 않기

결과 파일을 콘솔에서 열었더니 한글이 전부 깨져 보였습니다. 처음 보면 파일이 망가졌다고 생각하기 쉽습니다. 하지만 원인은 파일이 아니라 PowerShell 콘솔의 인코딩이었습니다. 파일의 바이트를 직접 UTF-8로 디코딩해 보니 내용은 멀쩡했습니다. 여기서 성급하게 "인코딩이 깨졌으니 다시 만들어 줘"라고 지시했다면 멀쩡한 파일을 고치느라 시간만 썼을 것입니다. 눈에 보이는 증상과 실제 원인은 다를 수 있습니다.

그럴듯한 설명이 가장 위험하다

같은 작업자가 쓴 엑셀 관련 글 초안에서 사실 오류가 두 개 나왔습니다.

• 13자리 밀리초 값을 초 단위 수식에 넣으면 "먼 미래의 연도가 나온다"고 썼지만, 실제로는 엑셀 날짜 범위(9999년)를 넘어서 #####로 표시됩니다.
• #VALUE! 오류의 원인을 "텍스트로 저장된 숫자"라고 썼지만, 엑셀은 숫자만 든 텍스트는 계산할 때 자동으로 숫자로 바꿉니다. 실제 원인은 공백이나 따옴표 같은 문자가 섞인 경우입니다.

두 설명 모두 읽을 때는 자연스러워서 그냥 넘어가기 쉬웠습니다. 검토 단계에서 잡았고, 수정은 새 작업을 시작하지 않고 같은 작업자 세션을 이어서 지시했습니다. 앞의 맥락이 남아 있어서 수정은 20초 만에 끝났습니다. 글을 쓰는 단계와 사실을 확인하는 단계는 분리해야 한다는 것을 이때 확실히 느꼈습니다.

이상한 데이터는 측정 방법부터 의심하기

블로그 옛 글 96편을 점검하는 스크립트를 돌렸더니 최근 글 몇 개의 글자 수가 0자로 나왔습니다. 빈 글이 있나 싶었지만, 실제로는 새 에디터로 쓴 글의 HTML 구조가 달라서 글자 수 측정이 안 된 것이었습니다. 이 숫자를 그대로 믿었다면 멀쩡한 글을 "내용 없는 글"로 분류할 뻔했습니다. 데이터에 이상한 값이 보이면 데이터보다 측정 방법을 먼저 의심합니다.

검증 루틴

작업자가 "다 했다"고 보고하면 아래 순서로 확인합니다.

1. 보고서의 "못 한 일"부터 읽는다: 실행하지 못한 명령, 건너뛴 단계가 있는지 확인합니다.
2. 완료 조건 명령을 직접 실행한다: 보고서의 "통과"를 믿지 않고 npm test 같은 명령을 다시 돌립니다.
3. diff를 읽는다: 범위 밖 파일을 건드리지 않았는지, 금지 사항을 어기지 않았는지 봅니다. test.skip 같은 흔적도 여기서 찾습니다.
4. 구조를 본다: 테스트는 기능이 동작하는지만 확인합니다. 함수가 한 가지 일만 하는지, 같은 코드가 여러 군데 복사돼 있지 않은지는 사람이 읽어야 보입니다.
5. 사실 주장은 별도로 확인한다: 코드가 아니라 설명이나 글이라면 핵심 주장마다 실제로 확인합니다.
6. 이상 증상은 원인을 확인한 뒤에 지시한다: 깨져 보이는 결과, 이상한 숫자는 표시 문제나 측정 문제일 수 있습니다.
7. 수정은 같은 세션에 이어서 지시한다: 새로 시작하면 맥락을 다시 설명해야 합니다.

직접 해보니

AI에게 맡긴 결과물은 겉으로는 그럴싸하고 기능도 잘 동작합니다. 그런데 코드를 열어 보면 스파게티가 되어 있는 경우가 많습니다. 기능은 되지만, 기능"만" 되는 코드입니다.

테스트를 통과했다는 것은 기능이 동작한다는 뜻일 뿐, 구조가 괜찮다는 뜻은 아닙니다. 이런 문제는 테스트로 잡히지 않기 때문에, 제가 코드를 검토할 때는 기능보다 구조를 봅니다.

마무리

AI 코딩 에이전트에게 일을 맡길 때 가장 중요한 것은 두 가지였습니다. 명세에 실행 가능한 완료 조건과 구체적인 금지 사항을 적는 것, 그리고 "완료" 보고를 받은 뒤에 직접 검증하는 것입니다. 작업자가 빠르게 많은 파일을 만들어도, 실행해 보지 않았거나 사실 확인을 거치지 않았다면 아직 끝난 일이 아닙니다.

자주 묻는 질문 (FAQ)

Q. 작업을 얼마나 잘게 나눠야 하나요?

한 번에 몇 분 안에 끝나는 크기, 그리고 결과물이 하나로 정해지는 크기가 적당합니다. 결과물이 하나여야 완료 조건을 명령 하나로 적을 수 있고, 검증도 그만큼 쉬워집니다.

Q. AI가 다 했다는데 확인은 어디까지 해야 하나요?

최소한 네 가지는 직접 합니다. 완료 조건인 테스트를 직접 실행하고, 바뀐 내용(diff)을 읽으면서 코드 구조를 보고, 글이나 설명에 들어간 사실 주장은 따로 확인합니다. 구조와 사실 주장은 테스트로 잡히지 않기 때문에 사람이든 별도의 검토 단계든 꼭 한 번 더 거쳐야 합니다.