회사에서 AI를 개발 업무에 써 보기 시작했을 때 가장 먼저 기대한 건 속도였다. 오류가 난 코드와 로그를 넣으면 원인을 바로 찾고, 필요한 코드까지 만들어 줄 거라고 생각했다. 실제로 간단한 함수나 낯선 문법을 설명받는 일은 빨라졌다. 그런데 저장소가 여러 개이고 설정과 배포 환경까지 얽힌 문제에서는 답이 그럴듯한 것만으로 부족했다.
AI는 질문에 포함되지 않은 사정을 알 수 없다. 지금 보고 있는 브랜치가 배포 대상인지, 옆 저장소의 인터페이스를 함께 바꿔야 하는지, 이 명령이 읽기인지 쓰기인지도 자동으로 알 수 없다. 설명을 잘 만드는 능력과 안전하게 일을 끝내는 능력 사이에는 꽤 큰 간격이 있었다.
그 간격을 메우는 작업 환경을 나는 AI 하네스라고 부르기 시작했다. 모델을 더 똑똑하게 만드는 일이 아니라, 모델이 읽고 판단하고 행동할 수 있는 레일을 까는 작업에 가깝다.
프롬프트보다 먼저 필요한 작업 계약
처음에는 매번 긴 프롬프트를 작성했다. 하지만 같은 저장소에서 비슷한 설명을 반복할수록 중요한 조건이 빠졌다. 그래서 반복되는 규칙은 대화가 아니라 저장소 가까이에 두기로 했다.
# AGENTS.md
## 작업 범위
- 현재 저장소와 명시된 연관 저장소만 읽기
- 수정 전 브랜치와 변경 파일 확인
- 실제 주소, 토큰, 계정 정보는 출력하지 않기
## 변경 규칙
- 원인 분석과 구현을 구분하기
- 공통 계약 변경은 영향 저장소를 먼저 나열하기
- 배포와 서버 재시작은 별도 승인 이후 수행하기
## 완료 조건
- 테스트와 빌드 결과 확인
- 변경된 파일과 남은 불확실성 기록
- 실행하지 못한 검증을 성공처럼 표현하지 않기
이런 파일은 정답을 적어 두는 문서가 아니다. AI가 작업을 시작할 때 지켜야 할 계약이다. OpenAI의 Codex 문서에서도 AGENTS.md를 프로젝트별 지침과 맥락을 전달하는 방식으로 설명한다. 실제로 사용해 보니 가장 유용했던 내용은 코딩 스타일보다도 작업 경계와 검증 방법이었다.
읽기와 쓰기의 분리
AI에게 “원인을 찾아서 고쳐 줘”라고 하면 분석과 수정이 한 문장에 섞인다. 작은 개인 프로젝트에서는 편하지만, 업무 저장소에서는 위험했다. 원인 후보를 찾는 과정과 파일을 바꾸는 과정은 필요한 권한도 다르고 실패했을 때의 영향도 다르기 때문이다.
그래서 작업을 세 구간으로 나눴다.
| 구간 | 허용 작업 | 다음 구간으로 넘어가는 조건 |
|---|---|---|
| 조사 | 코드 검색, Git 이력, 문서와 로그 읽기 | 실제 호출 경로와 근거 확보 |
| 구현 | 승인된 파일 수정, 포맷과 로컬 테스트 | 변경 범위와 테스트 결과 확인 |
| 외부 반영 | 커밋, 푸시, 배포, 재시작 | 대상과 복구 방법까지 명확한 승인 |
이 구분을 해 두면 “분석해 줘”라는 요청이 갑자기 배포로 이어지지 않는다. 반대로 구현까지 맡겼을 때는 조사만 하고 멈추는 일도 줄어든다. 하네스는 AI의 행동을 무조건 막는 장치가 아니라, 요청의 의도를 실행 가능한 단계로 번역하는 장치였다.
질문 대신 전달한 작은 작업 패킷
긴 설명을 한 번에 넣는 것보다 필요한 정보만 같은 형식으로 전달하는 편이 안정적이었다.
goal: 로그인 이후 화면 상태가 복구되지 않는 원인 확인
scope:
repositories: [client-app, api-server]
writable: []
evidence:
- 재현 시각과 화면 상태
- 최근 관련 커밋 두 개
- 요청 경로와 응답 코드
constraints:
- 실제 계정 정보 비공개
- 서버와 DB는 읽기 전용
done_when:
- 확인된 사실과 가설을 분리
- 다음 검증 위치를 파일 단위로 제시
핵심은 정보를 많이 넣는 것이 아니라 판단에 필요한 정보의 종류를 고정하는 것이었다. 목표만 주면 AI는 빈칸을 추측으로 채우기 쉽다. 범위, 증거, 제약, 완료 조건까지 주면 모르는 부분을 모른다고 남길 가능성이 높아졌다.
경계가 만든 의외의 속도
처음에는 규칙을 적는 시간이 아깝게 느껴졌다. 하지만 실제로 오래 걸린 건 문서를 쓰는 시간이 아니라 잘못된 저장소를 뒤지거나, 로컬 성공을 배포 성공으로 착각하거나, 권한이 없는 작업을 다시 설명하는 시간이었다. 작업 경계를 정한 뒤에는 탐색 범위가 좁아졌고 결과를 검토하기도 쉬워졌다.
이 시점의 결론은 단순했다.
AI 활용의 첫 설계 대상은 프롬프트가 아니라 작업 경계다.
하네스의 첫 번째 부품은 좋은 지시문이 아니라, 무엇을 읽고 무엇을 바꾸며 어디에서 멈출지를 적은 계약이었다. 다음 글에서는 이 계약을 매번 다시 설명하지 않도록 목표와 증거를 작은 단위로 유지하는 컨텍스트 구조를 정리한다.
다음 글: Codex AI 하네스 엔지니어링 설계 2 — 컨텍스트 구조
참고: OpenAI Codex의 AGENTS.md 안내
추가 구현 기준
이 문제를 고친 뒤 관련 공식 자료를 찾아 읽으면서, 당시 코드에서 우연히 맞았던 부분과 규칙으로 남겨야 할 부분을 나눠 봤다.
에이전트 활용 자료를 다시 읽으며 workflow와 agent를 먼저 구분했다. 순서와 분기가 정해진 일은 workflow로 고정하고, 탐색이 필요한 부분만 도구 선택을 맡기는 편이 결과를 비교하기 쉽다. 저장소 작업도 격리된 환경, 명시적 권한, 실행한 테스트와 diff가 함께 있어야 검토 가능한 변경이 된다.
하네스는 지시문 모음보다 입력 범위, 허용 도구, 중단 조건, 증거 형식을 코드와 문서로 고정하는 층에 가깝다.
다음에 Codex AI 하네스 엔지니어링 설계 1 — 작업 경계 같은 문제를 보면 아래 순서부터 확인하려고 한다.
- 읽기·수정·실행·배포 권한 구분
- 작업마다 허용한 파일과 도구 범위
- diff·테스트·실행 화면 증거
- 반복 상한과 사람에게 돌려줄 조건
성공 문장보다 실제 diff·테스트 출력·배포 화면을 우선하고, 쓰기·배포·비밀 접근은 별도 권한 경계로 남겨야 한다.
공식 참고 자료
- OpenAI Codex 소개 — 격리된 저장소 작업·테스트·권한 경계
- Building effective agents — workflow와 agent 구분, 단순한 조합 패턴과 평가
- Codex app 소개 — 병렬 작업·sandbox·권한·검토 흐름