AI 코딩 에이전트에게 명확한 '완료의 정의'를 부여하는 법

인간 동료가 모호한 티켓을 맡으면, 판단으로 빈틈을 메우고 질문을 던진다. AI 코딩 에이전트는 둘 다 하지 않는다. 요청을 읽고, 코드를 작성하고, 가능한 검사를 실행한 뒤 기능이 완료되었다고 선언한다. 명확히 하려는 질문 하나 없이 그러는 경우가 많다. 한 가이드의 표현을 빌리면, 모호한 요구사항을 에이전트에게 넘기면 "그 여유분은 흡수되는 것이 아니라 코드로 만들어져 버린다."

그래서 당신의 **완료의 정의(definition of done)**야말로 당신이 쓸 수 있는 가장 지렛대 효과가 큰 한 가지다. 이 가이드는 에이전트가 실제로 실행할 수 있는 완료의 정의를 쓰는 방법을 다룬다.

인수 기준 대 완료의 정의

서로 관련되지만 구분해 두면 좋은 두 개념이 있다.

• **인수 기준(acceptance criteria)**은 기능별이다. 이 특정 작업이 올바르다고 인정받으려면 무엇을 해야 하는가.
• **완료의 정의(definition of done)**는 프로젝트 전반에 걸친다. 모든 변경이 출시되기 전에 통과해야 하는 품질 게이트다. 테스트, 리뷰, 문서, 비밀정보 커밋 금지 등.

인수 기준을 "우리가 옳은 것을 만들었는가", 완료의 정의를 "우리 기준에 맞게 만들었는가"로 생각하라. 에이전트에게는 둘 다 필요하다. (이 구분에 대해서는 Atlassian의 좋은 입문 자료가 있다.)

열망이 아니라 검증 가능하게 쓰라

좋은 기준인지 가늠하는 시험은 이것이다. 스크립트가, 혹은 에이전트 자신이 그것이 참인지 확인할 수 있는가? "로그인 폼은 빠르게 느껴져야 한다"는 검증할 수 없다. 경계가 분명한 것으로 다시 써라.

• 유효한 자격 증명을 제출하면 500ms 이내에 /dashboard로 리디렉션된다
• 잘못된 비밀번호를 제출하면 인라인 오류가 표시되고 페이지를 이동하지 않는다
• 빈 필드를 제출하면 네트워크 요청이 발생하기 전에 클라이언트 측에서 차단된다
• 로그인 실패는 IP당 분당 5회로 속도 제한된다

각 줄은 에이전트가 그것을 향해 만들어 갈 수 있는 동시에 확인할 수 있는 것이다. AI 에이전트를 위한 좋은 명세를 쓰는 법에 관한 Addy Osmani의 조언은 한 줄 한 줄의 방법이 아니라 무엇을, 왜에 집중하라는 것이다. 의도와 제약을 서술하고, 구현은 에이전트가 고르게 하라.

구체적인 예시

같은 작업에 대한 다음 두 프롬프트를 비교해 보라.

모호한 경우:

사용자가 비밀번호를 재설정할 수 있는 방법을 추가하라.

완료의 정의가 있는 경우:

비밀번호 재설정 플로우를 추가하라. 완료란 다음을 의미한다:

• POST /auth/reset-request 엔드포인트는 이메일을 받아 항상 200을 반환한다(이메일 존재 여부를 절대 노출하지 않는다)
• 1시간 동안 유효한 서명된 일회용 토큰을 src/lib/mail.ts의 기존 메일러를 통해 이메일로 발송한다
• POST /auth/reset-confirm은 토큰을 검증하고, 현재 비밀번호 정책을 강제하며, 사용 후 토큰을 무효화한다
• 테스트는 다음을 포함한다: 정상 재설정, 만료된 토큰, 재사용된 토큰, 알 수 없는 이메일
• 먼저 알리지 않고는 새로운 의존성을 추가하지 않는다

두 번째 버전이 더 긴 것은 관료적이어서가 아니다. 에이전트가 그렇지 않았으면 추측했을 모든 모호함이 이제 결정되어 있기 때문에 더 긴 것이다. 보안에 민감한 선택들(계정 존재 여부를 흘리지 말 것, 토큰을 만료시킬 것, 일회용으로 쓸 것)은 에이전트가 즉흥적으로 처리하는 것을 가장 원치 않는 부분이다.

'완료'를 에이전트의 루프에 엮어 넣으라

검증 가능한 완료의 정의가 지닌 진짜 힘은 그것이 에이전트의 피드백 루프를 닫아준다는 데 있다. 코드 작성 → 테스트 → 수정 → 반복이라는 에이전트 순환은 도달해야 할 명확한 목표가 있을 때에만 수렴한다. 기준이 실제 테스트로 대응될 때, 에이전트는 테스트를 실행하고 실패를 확인한 뒤 당신에게 돌려주기 전에 스스로의 작업을 고칠 수 있다.

그러니 완료를 서술만 하지 말고, 에이전트가 그것을 확인할 방법을 주라.

• 테스트 명령(npm test, pytest)을 가리켜 주고, 그것이 통과하기 전까지는 기능이 완료된 것이 아니라고 알려주라.
• 코드로 단언하기 어려운 것들 — 가독성, 기존 패턴 준수 — 에는 LLM-as-a-judge 패스를 사용하라. 출력물을 당신의 품질 기준에 비추어 검토하는 두 번째 프롬프트다. Anthropic을 비롯한 여러 곳에서 이 방식이 주관적 검사에 효과적임을 확인했다.
• 보안과 "플레이스홀더/목(mock) 코드 금지"는 프로젝트 전반의 완료의 정의에 넣어 두어, 당신이 언급하는 것을 기억한 변경뿐 아니라 모든 변경에 적용되게 하라.

에이전트가 볼 곳에 두라

프로젝트 전반의 완료의 정의는 한 번 작성하되, 에이전트가 자동으로 읽는 파일에 두라. 리포지토리 루트의 AGENTS.md나 CLAUDE.md가 그것이다. 기능별 인수 기준은 작업 프롬프트 자체에 넣는다. 그러면 "우리 기준"은 항상 컨텍스트에 있고, 당신은 오늘 작업에 고유한 것만 적어 주면 된다.

이 변화는 미묘하지만 그것이 게임의 전부다. 유능한 에이전트와 함께라면, 당신의 인수 기준은 더 이상 동료에게 남기는 메모가 아니라 코드가 그에 맞춰 만들어지는 명세가 된다. 그렇게 될 것처럼 그것을 써라.