AI 코딩 에이전트가 만들기 전에 합의해야 할 것: 완료 정의를 고정하는 6칸 스프린트 계약

읽는 시간 약 8분 · 장기 실행 코딩 에이전트 운영

핵심 요약

• 에이전트의 자기보고는 완료의 증거가 아니라 출발점으로 다루는 편이 좋습니다.
• 한 스프린트에는 사용자가 실제로 확인할 수 있는 행동 하나와, 하지 않을 일을 함께 고정합니다.
• 평가는 구현 로그가 아니라 실행 중인 앱의 UI·API·저장 상태처럼 독립적으로 읽을 수 있는 결과를 봅니다.
• 중요 기준 하나가 미달하면 통과가 아니라 재작업으로 연결하고, 그 소유자를 미리 정합니다.
• 독립 평가자는 모든 작은 수정에 붙이는 장치가 아닙니다. 실패 비용과 검증 난이도가 클 때만 쓰는 것이 현실적입니다.

PR이 열린 뒤에만 확인하면 늦는 이유

예를 들어 “로그인한 사용자가 초안을 저장할 수 있게 해 주세요”라는 요청을 에이전트에게 맡겼다고 가정해 보겠습니다. PR에는 저장 버튼과 API 호출이 보일 수 있습니다. 그러나 실제 화면에서 저장한 뒤 새로고침했을 때 초안이 남는지, 다른 사용자의 초안이 보이지 않는지, 네트워크 오류에서 사용자가 무엇을 보게 되는지는 PR만으로 바로 판단하기 어렵습니다.

Anthropic은 장기 실행 앱 개발 사례에서 작성 역할과 평가 역할을 분리하고, 각 작업 단위 전에 무엇을 만들고 어떻게 확인할지 합의하는 방식을 설명합니다. 평가 역할은 실행 중인 앱을 탐색해 UI·API·데이터 상태를 확인하고, 정한 기준 중 하나라도 미달하면 작업을 되돌립니다. 이는 특정 도구를 그대로 따라 하라는 뜻이 아니라, 완료의 의미를 구현 전부터 검증 가능한 문장으로 바꾸는 방법이 필요하다는 사례입니다.

구현 전에 쓰는 FLOWIT 6칸 스프린트 계약

아래 표는 특정 모델이나 프레임워크와 무관하게 쓸 수 있는 최소 형식입니다. 한 장에 들어갈 만큼 좁게 쓰는 것이 핵심입니다. 넓은 제품 요구사항을 다시 쓰기보다, 이번 스프린트에서 통과·재작업을 가르는 내용을 적습니다.

이 형식은 역할을 늘리기 위한 문서가 아닙니다. 계약을 본 생성 역할은 구현 목표를 좁히고, 평가 역할은 확인해야 할 경로를 미리 압니다. OpenAI의 장기 작업 가이드도 큰 목표를 검증 가능한 단계로 나누고, 사람이 판단할 지점을 남기는 방식을 다룹니다. 다만 단계가 많다고 항상 좋은 것은 아닙니다. 기준이 분명하고 반복 수정의 가치가 있을 때만 평가 루프를 추가하는 편이 낫습니다.

예시: “초안 저장” 기능을 계약으로 바꾸기

여기서 좋은 증거는 “저장 기능을 구현했습니다”라는 보고가 아닙니다. 평가자가 별도 계정·별도 브라우저 세션처럼 독립적인 경로에서 행동을 재현하고, 필요한 경우 API와 저장 상태까지 대조할 수 있어야 합니다. 반대로 실제 환경 접근이 불가능하다면, 계약에 그 한계를 적고 사람이 확인할 항목으로 남기는 것이 정직합니다.

독립 evaluator를 붙일지 결정하는 기준

두 역할을 나누면 확인의 독립성은 높아질 수 있지만, 실행 시간과 비용도 함께 늘어납니다. 단순한 문구 수정이나 결정적 단위 테스트로 충분한 변경까지 무겁게 운영할 필요는 없습니다.

계약이 있어도 실패하는 다섯 가지 조건

1. 기준이 작업 중 바뀝니다. 새 요구가 생기면 기존 계약에 덧붙이지 말고 다음 작업 단위로 분리합니다.
2. 자기보고만 증거로 남습니다. 로그·설명·스크린샷은 보조 자료일 뿐, 실행 행동을 대체하지 못합니다.
3. 임계값이 있어도 예외로 통과시킵니다. 핵심 실패를 “나중에 고치자”로 넘기면 계약은 체크박스가 됩니다.
4. 권한과 비용 상한을 잊습니다. 평가를 반복하다 접근 범위나 실행 시간이 커지는지 확인해야 합니다.
5. 재작업 주인이 없습니다. 실패 기록만 남기면 다음 스프린트의 불확실성이 됩니다. 수정·재확인·승인 주체를 구분해 둡니다.

바로 써 보는 도입 체크리스트

• 한 스프린트에 관찰 가능한 사용자 행동 하나를 고정했나요?
• 비목표와 허용하지 않는 외부 효과를 함께 적었나요?
• 증거가 생성자의 설명이 아닌 실행 앱 또는 독립 읽기 결과인가요?
• 핵심 기준 하나가 미달하면 재작업으로 간다는 합의가 있나요?
• 평가 시간·비용 상한과 재작업 소유자를 정했나요?
• 사람이 계속 책임져야 할 권한·제품 판단 지점을 남겼나요?

이 계약은 구현 후의 검토를 없애지 않습니다. 구현 뒤 사람이 병합을 판단할 때는 AI 코딩 에이전트 PR 인수 패킷을, 운영 중 발견한 실패를 다음 평가에 반영할 때는 trace를 평가 사례로 바꾸는 원장을 이어서 볼 수 있습니다. 브라우저 결과를 별도 경로로 확인하는 패턴은 브라우저 에이전트 결과 영수증에서도 다룹니다.

자주 묻는 질문

자동 테스트가 있으면 evaluator는 필요 없나요?

항상 필요하지는 않습니다. 테스트가 핵심 사용자 행동과 실패 조건을 충분히 덮고, 변경의 영향이 작다면 단일 테스트와 사람 확인이 더 효율적일 수 있습니다. 다만 테스트가 놓치기 쉬운 권한·화면 흐름·다중 시스템 연결은 독립 확인의 가치가 커질 수 있습니다.

평가 역할도 틀릴 수 있지 않나요?

맞습니다. 그래서 평가 결과를 절대 판정으로 두지 않고, 명시한 행동과 증거를 따라가게 해야 합니다. 위험이 큰 기능은 사람이 승인하는 지점을 남기고, 실제 실패 사례가 쌓이면 계약의 확인 항목을 보완하는 편이 좋습니다.

작은 수정에도 6칸을 모두 써야 하나요?

아닙니다. 영향이 작고 기준이 명확한 수정은 짧은 체크리스트로 줄일 수 있습니다. 중요한 점은 문서의 길이가 아니라, 누가 무엇을 보고 통과·재작업을 결정하는지가 분명한가입니다.

실행 환경에 접근할 수 없으면 어떻게 하나요?

접근 불가 자체를 계약에 적고, 대체 증거의 한계를 표시하세요. 예를 들어 테스트 결과는 확인하되 실제 계정·권한 경로는 배포 전 담당자가 확인하도록 분리합니다. 확인하지 못한 부분을 완료로 표현하지 않는 것이 중요합니다.

계약은 언제 고쳐야 하나요?

새 요구가 기존 범위나 실패선을 바꿀 때, 또는 실제 실패가 현재 증거로 잡히지 않았을 때 고칩니다. 이미 진행 중인 작업의 기준을 조용히 바꾸기보다 다음 작업 단위에서 변경 이유와 함께 합의하는 편이 추적하기 쉽습니다.

참고 자료

• Anthropic — Harness design for long-running application development: 작성·평가 역할 분리, 스프린트 계약, 실행 중인 앱을 통한 확인 사례를 살펴볼 수 있습니다.
• OpenAI — Codex-maxxing for long-running work: 장기 작업을 검증 가능한 단계로 나누고, 사람의 판단 지점을 남기는 관점을 제공합니다.
• Anthropic — Building effective agents: 명확한 평가 기준과 반복 개선 가치가 있을 때만 평가 루프의 복잡성을 늘리라는 원칙을 설명합니다.