AI에게 구현을 맡기기 전에 완성 조건을 선언하는 Sprint Contract 운용

AI 코딩 에이전트(AI Coding Agent)에게 "이 기능을 구현해줘"라고 부탁하면, 구현 자체는 진행됩니다. 하지만 완료 정의(Definition of Done)가 모호하면 마지막에 다음과 같은 확인 사항이 남게 됩니다.

• 일반적인 동작은 충족했지만, 에러 발생 시의 동작이 미확인됨
• 인가(Authorization)나 이용 조건이 본문에 나타나지 않음
• 테스트는 통과했지만, 무엇을 확인하기 위한 테스트인지 알 수 없음
• 회귀 방지(no-regression) 관점이 누락됨

이 문제를 줄이기 위해, 구현 전에 "완성 조건"을 짧게 선언하는 Sprint Contract(본 기사에서의 독자적인 명칭)를 두도록 했습니다.

AI에게 구현을 부탁하면, 처음에 보이는 해피 패스(happy path)는 상당히 빠르게 만들 수 있습니다.

반면, 요청 문구가 부실하면 다음과 같은 누락이 발생합니다.

• 로그인된 상태를 전제로 하는데, 미로그인 시의 처리가 없음
• API 실패 시 화면에 무엇을 보여줄지 결정되지 않음
• 기존의 저장 형식이나 설정값과의 호환성을 고려하지 않음
• 테스트가 "정상적으로 저장할 수 있다"뿐이라서, 중복 실행이나 잘못된 입력(invalid input)을 확인하지 않음

구현 후에 이를 수정하려면 코드뿐만 아니라 테스트, UI 문구, 에러 처리까지 다시 돌아가야 합니다.

원인은 구현 태스크를 "만드는 것"만 전달했기 때문이었습니다.

사람이라면 대화 속에서 보완할 전제 조건이라도, AI에게 전달할 때는 명시하지 않으면 누락됩니다. 특히 다음 관점들은 요청 문구에 포함되어 있지 않으면 뒤로 밀리기 쉽습니다.

• 일반 동작
• 이용 전제 및 인가(Authorization)
• 잘못된 입력(invalid input)
• 에러 처리
• 중복 조작 및 재실행
• 기존 기능의 회귀 방지(no-regression)

그래서 작업 시작 전에 이것들을 완성 조건으로 선언하도록 했습니다.

저의 운용 방식에서는 구현 전에 다음과 같은 형태로 작성합니다.

완성 조건:
- 일반 동작:
- 전제 조건·인가:
...

모두 채울 필요는 없습니다. 해당하지 않는다면 해당 없음이라고 적습니다.

중요한 것은 구현 전에 "이번에는 보지 않겠다"라고 결정한 관점도 명시하는 것입니다. 정의되지 않은 채로 진행하는 것보다 나중에 리뷰하기 쉬워집니다.

예를 들어, 설정 화면에 "알림 활성화" 토글을 추가한다면 다음과 같이 쓸 수 있습니다.

완성 조건:
- 일반 동작:
- 설정 화면에서 알림 토글을 변경할 수 있음
...

이 상태로 AI에게 전달하면, 구현 후의 자기 체크나 테스트 추가를 위한 관점이 갖춰집니다.

테스트를 나중에 "적당히 작성해줘"라고 부탁하면, 해피 패스(happy path)만 작성되는 경우가 있습니다.

구현 전에 최소한 다음을 전달합니다.

테스트 관점:
- normal: 유효한 입력으로 저장할 수 있음
- boundary: 빈 문자열, 최대 길이, 0건 등 경계값을 다룸
...

매번 모든 테스트를 작성할 필요는 없습니다. 작은 변경이라면 normal과 regression만으로도 충분할 때가 있습니다.

단, 인가(Authorization), 과금, 외부 API, 영속 데이터(persistent data)를 다루는 변경에서는 invalid, authorization, idempotency를 생략하면 나중에 다시 작업해야 할 확률이 높습니다.

실제로 요청할 때는 완성 조건과 대상 범위를 함께 전달합니다.

다음 범위만 구현해 주세요.
대상:
- src/settings/notification.ts
...

이렇게까지 작성하면 AI는 "무엇을 만들지"뿐만 아니라 "무엇을 망가뜨리면 안 되는지"도 살피며 작업할 수 있습니다.

Sprint Contract를 너무 세세하게 만들면 구현 전 준비 단계만 무거워집니다.

저는 다음 기준에 따라 입도(granularity)를 조절하고 있습니다.

변경 종류	완성 조건의 입도
문구 수정, 단순 표시 변경	일반 동작과 no-regression만
...

모든 태스크에 최대치의 체크리스트를 사용하는 것이 아니라, 실패했을 때의 영향이 큰 부분에 두텁게 사용합니다.

AI에게 구현을 맡기기 전에 완성 조건을 선언하면 구현 후의 리뷰가 편해집니다.

저의 운용 방식에서는 적어도 다음을 먼저 작성하도록 했습니다.

• 일반 동작
• 전제 조건·인가
• 잘못된 입력(invalid input)
• 에러 처리
• 중복 조작·재실행
• 회귀 방지(no-regression)
• 검증 커맨드

AI에게 "만드는 것"만 전달하는 것이 아니라, "완료로 간주하는 조건"까지 전달한다. 이것만으로도 구현 후에 다시 돌아가는 횟수를 줄일 수 있었습니다.