에이전트가 실행할 수 있는 티켓을 작성하는 방법

티켓에는 "로그인 버그를 수정하세요"라고 적혀 있었습니다. 에이전트는 비밀번호 재설정 흐름(flow), 세션 미들웨어(session middleware), 그리고 제가 들어본 적도 없는 피처 플래그(feature flag)를 건드리는 400줄짜리 PR(Pull Request)을 제출했습니다. 기술적으로 틀린 변경 사항은 하나도 없었습니다. 하지만 그 중 어떤 것도 버그를 수정하지는 못했습니다.

버그는 에러 메시지의 오타였습니다.

에이전트는 티켓이 요구한 것을 정확히 수행했습니다. 티켓이 모호한 것을 요구했기에, 에이전트도 모호한 작업을 수행한 것입니다. 잘못은 모델에 있지 않았습니다. 잘못은 명세(spec)에 있었습니다.

이것은 대부분의 팀이 "에이전트가 혼란을 겪었다"라고 치부하며 넘겨버리는 실패 모드(failure mode)입니다. 에이전트는 혼란을 겪은 것이 아닙니다. 에이전트는 티켓을 계약(contract)으로 취급했고, 그 계약에 따라 결과물을 내놓았습니다. 계약이 잘못되었을 뿐입니다.

문자 그대로 받아들이는 독자

해당 티켓을 받은 사람이었다면 다음 두 가지 중 하나를 했을 것입니다. 어떤 로그인 버그인지 물어보거나, 최근 버그 리포트(bug reports)를 살펴보고 문맥(context)을 통해 파악했을 것입니다. 어느 쪽이든 "로그인 버그를 수정하세요"와 실제 수정 사항 사이의 간극은 판단력, 직관, 그리고 슬랙(Slack) 메시지 한 통의 저렴한 비용을 통해 메워집니다.

에이전트에게는 그런 것이 전혀 없습니다. 에이전트에게 있는 것은 티켓, 코드베이스(codebase), 그리고 테스트 하네스(harness)가 로드하는 문맥뿐입니다. 에이전트는 어떤 로그인 버그인지 알지 못합니다. 버그 보고자와의 관계도 없습니다. "스탠드업 미팅에서 Sarah가 언급했던 오타"와 같은 패턴 매칭(pattern-match)도 하지 못합니다. 에이전트는 페이지에 적힌 내용을 읽고, 합리적인 해석을 내린 뒤, 그대로 실행합니다.

만약 티켓이 해석의 여지를 남겨둔다면, 에이전트는 해석을 할 것입니다. 만약 그 해석이 틀렸다면, PR도 틀릴 것입니다. 모호한 티켓의 비용은 상승했습니다. 왜냐하면 이제 소비자는 질문을 할 수 있는 인간이 아니기 때문입니다.

해결책은 해석을 요구하지 않는 티켓을 작성하는 것입니다.

계약으로서의 티켓

계약에는 몇 가지 속성이 있습니다. 범위 내에 있는 것(in scope)을 명시합니다. 범위 외에 있는 것(out of scope)을 명시합니다. 성공을 위한 테스트를 명시합니다. 당사자와 제약 사항(constraints)을 명시합니다.

좋은 에이전트 티켓도 이와 동일한 형태를 가져야 합니다.

무엇이 변하는가 (What changes). 티켓 작업이 완료된 후 달라질 동작을 명시합니다.

범위 외 (out-of-scope) 섹션은 폭발 반경 (blast radius)을 제한하는 가장 저렴한 방법입니다. 티켓에 적힌 다섯 줄의 문장이 리뷰에 소요되는 두 시간을 방지합니다. "src/auth/login.tsx 외부의 파일은 수정하지 마세요"라는 한 줄은 in-CLAUDE.md의 어떤 규칙보다 더 큰 무게를 가집니다. 왜냐하면 이는 작업에 특화된 (task-specific) 지침이기 때문입니다. 하네스 (harness)는 경계가 어디에 있는지 추측할 수 없지만, 티켓은 할 수 있습니다.

저는 범위 내 (in-scope) 사항이 명백할 때조차도, 사소하지 않은 모든 에이전트 작업에 대해 범위 외 (out-of-scope) 섹션을 작성하기 시작했습니다. 이러한 규율은 제가 변경 사항이 '무엇이 아닌지'를 생각하게 만들며, 이는 종종 에이전트가 작업을 수행하기 전에 숨겨진 가정을 드러내 줍니다.

테스트에서 시작하기

제가 작성하는 가장 강력한 티켓은 기능 (feature)이 아니라 테스트 (test)에서 시작합니다.

테스트는 인과 관계의 언어로 동작을 명명합니다. "사용자가 잘못된 이메일로 로그인 폼을 제출하면, 페이지의 폼 아래 빨간색 경고창에 '이메일 또는 비밀번호가 잘못되었습니다'가 표시된다." 여기에는 해석의 여지가 없습니다. 테스트는 통과하거나 실패할 뿐입니다. 에이전트의 역할은 테스트를 통과하게 만드는 것입니다.

만약 제가 테스트를 명확하게 설명할 수 없다면, 저는 제가 무엇을 요구하고 있는지 아직 모르는 것입니다. 그것은 티켓을 작성하기 전에 멈춰서 문제를 파악하라는 신호입니다. 모호한 티켓을 작성하고 에이전트가 이를 개선해주기를 바라는 방식이 바로 400줄짜리 PR (Pull Request)이 발생하는 원인입니다.

테스트에서 시작하는 것은 두 번째 이점도 있습니다. 테스트는 보통 정확히 하나의 파일, 혹은 기껏해야 몇 개의 파일을 가리킵니다. 범위 (scope)는 테스트로부터 자연스럽게 도출됩니다. 에이전트에게 범위 내에 머물라고 말할 필요가 없는데, 왜냐하면 범위가 이미 테스트가 실행하는 대상에 의해 정의되어 있기 때문입니다.

파일 경로가 중요하다

이제 제가 작성하는 모든 티켓에는 파일 경로가 포함됩니다. "로그인 폼"이 아니라 src/auth/login.tsx입니다. "세션 로직"이 아니라 src/middleware/session.ts:34-62입니다. 에이전트는 경로를 지침 (instruction)이자 경계 (boundary)로 사용합니다. 작업은 여기서 일어납니다. 다른 어디에서도 아닙니다.

경로를 포함하는 데 드는 비용은 티켓을 열기 전 리포지토리 (repo)를 20초 동안 살펴보는 것입니다. 경로를 포함하지 않을 때의 비용은 에이전트 (agent)가 15분 동안 검색하는 시간과