수락 기준(Acceptance Criteria) 작성 방식을 바꿨더니 AI 에이전트가 엉뚱한 것을 만드는 일이 사라졌다

한동안 저는 모델을 탓했습니다. 에이전트가 그럴듯하지만 틀린 것을 만들어내면, 저는 더 똑똑한 두뇌가 필요하다고 가정했습니다. 그러다 제가 에이전트에게 전달했던 티켓들을 다시 읽어보았고, 문제는 명백했습니다. 저의 수락 기준 (Acceptance Criteria)은 명세(Specification)가 아니라 희망 사항이었습니다. 에이전트는 제가 쓴 그대로를 만들었습니다. 단지 제가 의도한 바를 제대로 쓰지 않았을 뿐입니다.

대부분의 문제를 해결한 변화는 다음과 같으며, 이는 모델과는 아무런 상관이 없습니다.

산문 형태의 수락 기준은 의도가 죽는 곳이다

대부분의 AC(Acceptance Criteria)는 다음과 같이 작성됩니다:

내보내기(Export) 기능은 대용량 파일을 유연하게 처리해야 하며 타임아웃(Time out)이 발생해서는 안 된다.

이 문장의 모든 단어는 지뢰입니다. "대용량(Large)"은 얼마나 큰 것인가? "유연하게(Gracefully)"는 어떤 동작을 의미하는가? "타임아웃(Time out)"은 어떤 임계값에서 발생하는가? 인간 검토자는 이러한 공백을 가정을 통해 채우는데, 대개 작성자와는 다른 가정을 합니다. AI 에이전트 역시 이를 채우지만, 훨씬 더 빠르고 자신감 있게 수행합니다. 결국 아무도 실제로 동의하지 않은 명세에 따라 작동하는 코드를 얻게 됩니다.

해결책은 기준을 설명(Description)으로 쓰는 것을 멈추고, 검증 가능한(Checkable) 무언가로 쓰기 시작하는 것입니다. 만약 어떤 기준이 통과(Pass) 또는 실패(Fail)로 판가름 날 수 없다면, 그것은 기준이 아닙니다. 그것은 그저 느낌(Vibe)일 뿐입니다.

통용되는 형식

저는 모든 것을 Given / When / Then 구조로 옮겼습니다. 의도적으로 지루하게 만들었습니다.

Given 100,000개의 행이 있는 CSV 파일이 있을 때
When 사용자가 내보내기(Export)를 실행하면
Then 파일이 스트리밍되어 다운로드되고 30초 이내에 완료되어야 한다
...

이제 추측할 것이 아무것도 없습니다. 임계값(Thresholds)이 명시적입니다. 엔지니어가 읽는 방식, QA가 읽는 방식, 그리고 에이전트가 읽는 방식이 모두 동일합니다. 그리고 마지막 절이 조용한 영웅 역할을 합니다. 그것이 기준을 테스트 가능하게(Testable) 만들기 때문입니다. 코드를 작성하기 전에 테스트를 작성할 수 있으며, 에이전트는 이를 바탕으로 스스로를 점검할 수 있습니다.

제가 현재 지키고 있는 몇 가지 규칙은 다음과 같습니다:

형용사가 아닌 숫자를 사용하세요. "빠른(Fast)"은 "p95 기준 200ms 미만"이 됩니다. "대용량(Large)"은 행 수(Row count)가 됩니다. 숫자로 표현할 수 없다면, 당신은 아직 요구사항을 이해하지 못한 것이며, 에이전트 또한 마찬가지일 것입니다.

기준(Criterion)당 하나의 동작만 작성하세요. 기준에 "그리고 또한(and also)"이라는 표현이 등장하는 순간, 즉시 분리하십시오. 복합적인 기준(Compound criteria)은 절반만 완성된 기능이 리뷰를 통과하게 만드는 주범입니다.

불만족 경로(Unhappy path)를 명시적으로 기술하세요. 대부분의 에이전트 실패는 여기서 발생합니다. 빈 입력값, 중복 데이터, 권한 오류가 발생했을 때 어떤 일이 일어나는지 작성하십시오. 당신이 이를 작성하지 않는다면, 에이전트는 스스로 만들어낼 것이며, 당신은 그 에이전트가 만들어낸 결과물을 마음에 들어 하지 않을 것입니다.

이것이 AI 시대에 더욱 중요한 이유

모호한 수락 기준(AC)을 읽는 인간 엔지니어는 대개 멈춰서 질문을 던집니다. Slack으로 메시지를 보내거나, 리파인먼트(Refinement) 단계에서 문제를 제기하거나, 반론을 펼칩니다. 이러한 마찰은 번거롭지만 동시에 안전망 역할을 합니다. 모호한 명세(Spec)는 사람이 추측하기를 거부하기 때문에 명확해집니다.

에이전트는 추측하기를 거부하지 않습니다. 에이전트는 즉시 추측하고 실행에 옮깁니다. 따라서 인간이라면 지적했을 모호한 AC가 코드 단계까지 그대로 직행하게 됩니다. 인간만이 독자였을 때는 건너뛰어도 괜찮았던 그 규율이, 이제는 시스템을 지탱하는 핵심 요소(Load-bearing)가 되었습니다.

이것이 바로 사람들이 "AI가 당신을 더 빠르게 움직이게 한다"라고 말할 때 놓치는 부분입니다. AI가 속도를 높여주는 것은 맞지만, 미비하게 작성된 티켓(Ticket)을 잡아내던 인간을 제거해 버립니다. 에이전트는 당신을 대신해 엄격함을 제공하지 않으므로, 당신이 직접 명세에 그 엄격함을 다시 불어넣어야 합니다.

좋은 기준만으로는 충분하지 않은 경우

솔직해집시다. 날카로운 AC는 "잘못된 것을 만든" 실패는 해결해 줍니다. 하지만 "시스템의 나머지 부분을 보지 못한" 실패는 해결하지 못합니다. 에이전트는 기준을 완벽하게 충족하면서도, 기존의 유틸리티를 중복 생성하거나 자신이 알지 못했던 아키텍처 결정(Architecture decision)을 위반할 수 있습니다. 왜냐하면 그 맥락(Context)이 다른 도구에 존재하기 때문입니다.

따라서 AC는 필요조건이지만 충분조건은 아닙니다. 에이전트에게는 기준(Criterion)뿐만 아니라 주변의 진실, 즉 기존 테스트, 관련 결정 사항, 연관된 스토리(Stories)가 함께 필요합니다. 제가 기준을 검증 가능한 문장(Checkable statements)으로 작성하고, 에이전트가 프로젝트의 나머지 부분과 함께 이를 조회할 수 있게 만들었을 때, 결과물은 그럴듯해 보이는 수준을 넘어 정확해지기 시작했습니다.

그것이 바로 제가 Stride에서 구축하고 있는 것의 핵심 논지입니다. AI가 수락 기준 (Acceptance Criteria)을 관련 테스트 및 결정 사항 옆에 연결된 노드 (linked nodes)로서 작성하고 읽도록 하여, 기준이 그것을 증명하는 대상으로부터 세 개의 탭만큼 떨어져 있는 일이 결코 발생하지 않도록 만드는 것입니다. 하지만 오늘날 이러한 이점을 대부분 얻기 위해 반드시 특정 도구가 필요한 것은 아닙니다. 당신은 '바람(wishes)'을 쓰는 것을 멈춰야 합니다.

다음 티켓에서 이것을 시도해 보세요

에이전트에게 넘겨주려는 다음 작업을 가져오세요. 수락 기준 (Acceptance Criteria)에 포함된 모든 형용사를 찾아 숫자나 구체적인 동작 (concrete behavior)으로 교체하세요. 예외 경로 (unhappy path)를 추가하세요. 그런 다음 에이전트를 실행하세요. 그 차이는 미묘한 수준이 아닙니다.

지나고 보니 당신이 배포했던 수락 기준 (Acceptance Criteria) 중 최악의 것은 무엇이었나요? 제가 먼저 말씀드리겠습니다: "빠릿빠릿한 느낌을 주어야 한다 (should feel snappy)". 이 문구 때문에 일주일 동안 재작업을 해야 했습니다. 이제 당신 차례입니다.