1편에서 AI가 움직일 작업 경계를 먼저 정했다. 다음 문제는 기억이었다. 한두 파일을 고치는 작업은 대화 안에서 끝났지만, 여러 저장소를 오가거나 빌드와 화면 검증까지 이어지는 작업은 중간에 맥락이 자주 흐려졌다.
대화가 길어질수록 정보가 많아지는데 이상하게 판단은 더 불안정해졌다. 오래된 오류 로그, 이미 해결한 가설, 현재 브랜치와 관계없는 탐색 결과가 한 화면에 섞였기 때문이다. 컨텍스트가 크다고 항상 좋은 건 아니었다. 지금 결정에 필요한 내용이 얼마나 잘 남아 있는지가 더 중요했다.
대화 기록과 작업 상태의 분리
내가 먼저 바꾼 건 “AI가 앞 내용을 기억하겠지”라는 기대였다. 대화는 생각의 과정이고, 작업 상태는 다시 시작할 때 필요한 사실이다. 둘을 같은 것으로 보면 중간부터 이어서 일하기가 어렵다.
작업 상태에는 아래 다섯 가지만 남겼다.
goal: 무엇을 끝내야 하는가
current_state: 지금 어느 단계인가
evidence: 무엇을 직접 확인했는가
decisions: 어떤 선택을 왜 했는가
next_action: 다음 한 번의 행동은 무엇인가
예를 들어 “로그인 오류 수정 중”은 상태로 쓰기엔 너무 넓다. 아래처럼 쓰면 다음 작업자가 대화를 모두 읽지 않아도 출발점을 잡을 수 있다.
goal: 재로그인 후 이전 화면 상태 복구
current_state: 원인 분석 완료, 구현 전
evidence:
- 클라이언트에서 세션 만료 이벤트 확인
- API 응답은 정상
- 화면 상태 초기화 함수가 먼저 실행됨
decisions:
- 서버 응답 형식은 변경하지 않음
- 화면 복구 순서만 조정
next_action: 초기화와 복구 호출 순서에 대한 회귀 테스트 작성
이 구조가 좋은 이유는 요약이 짧아서가 아니다. 사실과 결정과 다음 행동이 서로 다른 칸에 있기 때문이다. 근거가 바뀌면 결정만 다시 평가하면 되고, 목표가 바뀌면 기존 결과 중 무엇을 버려야 하는지도 보인다.
컨텍스트의 세 가지 층
업무에서 쓸 때는 컨텍스트를 세 층으로 나누는 편이 이해하기 쉬웠다.
오래 유지되는 규칙
저장소의 구조, 금지된 작업, 테스트 명령처럼 여러 작업에서 반복되는 내용이다. 이런 정보는 AGENTS.md나 프로젝트 문서처럼 코드 가까이에 둔다. 대화마다 복사하지 않아도 되고 변경 이력도 남길 수 있다.
작업 동안 유지되는 상태
이번 목표, 대상 브랜치, 확인한 증거, 남은 검증처럼 작업이 끝나면 가치가 줄어드는 내용이다. 작은 상태 파일이나 체크리스트가 잘 맞았다.
한 번의 판단에만 필요한 증거
특정 로그 몇 줄, 현재 diff, 브라우저 응답처럼 금방 낡는 정보다. 이런 자료는 오래 저장하기보다 확인 시각과 출처를 붙여 현재 판단에만 사용했다.
| 층 | 예시 | 갱신 시점 |
|---|---|---|
| 프로젝트 규칙 | 브랜치 정책, 테스트 명령, 비밀정보 처리 | 규칙이 바뀔 때 |
| 작업 상태 | 목표, 현재 단계, 결정, 다음 행동 | 단계가 끝날 때 |
| 현재 증거 | diff, 로그, 응답, 화면 | 확인할 때마다 |
이렇게 나누면 오래된 로그가 현재 사실처럼 남는 문제를 줄일 수 있다. 특히 배포 전과 후의 증거를 같은 묶음으로 취급하지 않게 됐다.
컨텍스트 압축에서 버리지 않은 것
긴 작업은 언젠가 요약해야 한다. 처음에는 대화 내용을 골고루 줄였는데, 그러면 실패 이유나 하지 않기로 한 결정이 사라졌다. 이후에는 아래 항목을 우선적으로 남겼다.
- 사용자가 최종 승인한 목표와 제외 범위
- 현재 브랜치와 변경 파일
- 이미 실행한 검증 명령과 실제 결과
- 실패를 재현하는 조건
- 되돌리면 안 되는 사용자 소유 변경
- 아직 확인하지 못한 가설
- 외부 반영에 필요한 승인 여부
반대로 탐색 중에 한 번 열어 본 파일 목록, 결과가 없었던 광범위 검색, 이미 폐기한 가설의 세부 내용은 줄였다. 필요하면 Git과 로그에서 다시 찾을 수 있기 때문이다.
코드보다 먼저 갱신한 체크포인트
작업이 길어질 때는 단계가 끝날 때마다 체크포인트를 남겼다.
[ANALYZED]
- 원인: 화면 초기화가 복구 이벤트보다 먼저 실행
- 영향: 모바일 화면 한 곳
- 제외: API 계약, DB 구조
[IMPLEMENTED]
- 변경: 상태 복구 순서 조정
- 테스트: 재로그인 회귀 시나리오 추가
- 미확인: 실제 배포 화면
[VERIFIED]
- 로컬 테스트 통과
- 빌드 산출물 확인
- 배포 검증은 아직 실행하지 않음
상태 이름은 프로젝트마다 달라도 된다. 중요한 것은 IMPLEMENTED와 VERIFIED를 같은 말로 쓰지 않는 것이다. 코드를 바꿨다는 사실과 문제가 해결됐다는 증거가 분리돼야 다음 사람이 잘못된 위치에서 시작하지 않는다.
컨텍스트 엔지니어링의 실제 의미
컨텍스트 엔지니어링이라는 말을 처음 들었을 때는 모델에 더 많은 문서를 넣는 기술처럼 느껴졌다. 실제 사용에서는 반대에 가까웠다. 무엇을 넣을지보다 무엇을 현재 사실로 취급하지 않을지를 정하는 일이 더 중요했다.
좋은 컨텍스트는 백과사전이 아니라 잘 정리된 인수인계 문서에 가까웠다. 목표가 한 줄로 보이고, 확인한 증거가 출처와 함께 남고, 다음 행동이 하나로 좁혀진 상태다. 이 구조가 잡히자 AI에게 다시 설명하는 시간보다 작업을 검토하는 시간이 늘었다. 나에게 필요한 변화도 바로 그 지점이었다.
이전 글: Codex AI 하네스 엔지니어링 설계 1 — 작업 경계
다음 글: Codex AI 하네스 엔지니어링 설계 3 — 도구 계약
기술 문서 기반의 책임 경계
이 문제를 고친 뒤 관련 공식 자료를 찾아 읽으면서, 당시 코드에서 우연히 맞았던 부분과 규칙으로 남겨야 할 부분을 나눠 봤다.
에이전트 활용 자료를 다시 읽으며 workflow와 agent를 먼저 구분했다. 순서와 분기가 정해진 일은 workflow로 고정하고, 탐색이 필요한 부분만 도구 선택을 맡기는 편이 결과를 비교하기 쉽다. 저장소 작업도 격리된 환경, 명시적 권한, 실행한 테스트와 diff가 함께 있어야 검토 가능한 변경이 된다.
하네스는 지시문 모음보다 입력 범위, 허용 도구, 중단 조건, 증거 형식을 코드와 문서로 고정하는 층에 가깝다.
다음에 Codex AI 하네스 엔지니어링 설계 2 — 컨텍스트 구조 같은 문제를 보면 아래 순서부터 확인하려고 한다.
- 읽기·수정·실행·배포 권한 구분
- 작업마다 허용한 파일과 도구 범위
- diff·테스트·실행 화면 증거
- 반복 상한과 사람에게 돌려줄 조건
성공 문장보다 실제 diff·테스트 출력·배포 화면을 우선하고, 쓰기·배포·비밀 접근은 별도 권한 경계로 남겨야 한다.
공식 참고 자료
- OpenAI Codex 소개 — 격리된 저장소 작업·테스트·권한 경계
- Building effective agents — workflow와 agent 구분, 단순한 조합 패턴과 평가
- Codex app 소개 — 병렬 작업·sandbox·권한·검토 흐름