작업 계약
개요
AI에게 작업 지시는 보통 너무 느슨하다.
- 무엇을 바꾸라는지는 말하지만
- 어디까지 바꿀 수 있는지는 흐리고
- 무엇이 끝난 상태인지는 모호하며
- 실패하면 어디서 멈춰야 하는지도 비어 있다
그래서 필요한 것이 task contract다.
이 문서는 transition에서 필요성을 반복 설명하지 않는다.
harness/ai 적용 레이어에서 AI 작업자를 어떤 계약 안에 넣을지 바로 다룬다.
task contract란 무엇인가
task contract는 프롬프트보다 더 실행에 가까운 작업 계약이다. 핵심은 다음 네 가지를 명시하는 것이다.
- 변경 범위
- 허용된 진입점과 금지 표면
- 확인해야 하는 check
- stop condition과 done condition
즉 task contract는
무엇을 시도해도 되는가와 어디서 멈춰야 하는가를 같이 정의한다.
왜 prompt만으로는 부족한가
프롬프트는 방향을 줄 수 있다. 하지만 다음을 고정하기에는 너무 느슨하다.
- 이 파일 밖 변경이 허용되는가
- 리팩터링과 수정 중 무엇을 원하는가
- 새 abstraction 추가가 허용되는가
- 어떤 검증이 통과해야 완료인가
이 빈칸이 남아 있으면 AI는 가장 가까운 shortcut으로 그 빈칸을 채운다.
좋은 task contract의 최소 요소
scope
- 어떤 파일이나 모듈을 수정할 수 있는가
- 어떤 경계는 읽기만 가능하고 수정은 금지되는가
- unrelated cleanup은 허용되지 않는가
합법 경로
- 써야 하는 public API나 canonical path는 무엇인가
- 금지된 helper, direct access, bypass path는 무엇인가
checks
- 어떤 command나 validator를 통과해야 하는가
- 전체 build인지, narrow test인지, lint subset인지
stop condition
- 범위가 task boundary 밖으로 퍼질 때
- 같은 failure가 반복될 때
- 정책 판단이 필요한 예외가 나올 때
done condition
- 어떤 상태가 되면 task를 끝난 것으로 간주하는가
context와의 관계
context가 작업 해석을 돕는 구조화된 패킷이라면,
task contract는 그 패킷을 실행 가능한 작업 계약으로 닫는다.
- context는 무엇을 보게 할지 정하고
- task contract는 무엇을 바꿔도 되는지 정한다
즉 context가 탐색 비용을 줄인다면, task contract는 행동 반경을 줄인다.
나쁜 task contract 패턴
- “필요한 만큼 수정"처럼 범위가 무한하다
- done condition 없이 “고쳐봐"로 끝난다
- build 하나만 적고 어떤 failure가 task relevant한지 구분하지 않는다
- 금지 표면이 없어 fallback refactor가 쉽게 발생한다
- unrelated cleanup이 묵시적으로 허용된다
이런 계약은 자유로워 보이지만, 실제로는 broad refactor와 우회를 부른다.
AI 코딩에서 왜 더 중요해지는가
AI는 비어 있는 계약을 사람보다 더 빠르게 임의 해석한다.
- scope가 흐리면 더 넓은 파일로 퍼지고
- 합법 경로가 없으면 가까운 shortcut을 고르고
- done condition이 없으면 과도한 polishing으로 시간을 쓴다
그래서 AI 환경에서는 좋은 contract가 좋은 prompt보다 더 큰 차이를 만든다.
실무 질문
- 수정 가능한 범위가 명시되어 있는가
- 금지 표면과 canonical path가 같이 보이는가
- 어떤 check를 통과해야 완료인지 분명한가
- 같은 failure가 반복될 때 멈추는 조건이 있는가
- unrelated refactor를 막는 문장이 포함되어 있는가
요약
좋은 task contract는 다음을 만족한다.
- scope가 잠겨 있고
- 합법 경로가 드러나며
- check와 stop condition이 명시되고
- done condition이 분명하다
하네스의 AI 적용에서 task contract는 프롬프트의 장식이 아니라, 행동 반경과 종료 조건을 고정하는 실행 계약이다.