장기 코딩 에이전트를 위한 상태 기록과 완료 검증

여러 세션에 걸친 코딩 작업에서는 구현 상태와 검증 상태를 따로 기록해야 합니다. 다음 세션이 완료한 작업을 반복하거나 미검증 동작을 완료로 처리하지 않도록, 확인한 결과와 남은 일을 대화 밖에 보존합니다.

Anthropic의 장기 에이전트 하네스 사례에서는 작업 상태를 대화 밖의 파일에 기록하고 검증 절차로 확인합니다. 하네스는 에이전트를 실행하고 작업 상태와 검사를 관리하는 환경입니다. 이 사례에서 코딩 에이전트는 기능 목록과 진행 기록을 읽은 뒤 한 기능을 선택해 구현하고 검사합니다. 이는 웹 애플리케이션 개발 실험의 사례이며 모든 작업에 같은 파일 구조를 요구하는 표준은 아닙니다.

초기 환경과 기능 목록

사례에서는 초기화 에이전트가 기능 목록, 실행 스크립트, 진행 기록, 초기 저장소 상태를 준비합니다. 이후 코딩 에이전트는 이 자료를 읽고 아직 완료되지 않은 기능을 선택합니다.

기능 목록에는 사용자가 관찰할 수 있는 동작과 확인 절차를 담습니다. “채팅 기능 구현”처럼 넓게 쓰면 어느 부분이 끝났는지 판단하기 어렵습니다. “새 채팅을 만들면 목록에 표시되고 빈 대화 화면이 열린다”처럼 동작을 나누면 구현과 검증을 연결할 수 있습니다.

원문 실험은 큰 애플리케이션의 기능 목록을 JSON으로 관리했습니다. 작은 작업에서는 기존 상태 문서에 관찰할 동작과 검사 결과를 기록하는 방식도 사용할 수 있습니다.

직접 만든 채팅 화면 예시입니다. 그림에는 생성 버튼 조작, 목록 추가와 빈 대화 표시, 재조회 뒤 저장 결과를 각각 확인할 위치를 표시했습니다.

새 세션의 기본 검사

새 세션의 코딩 에이전트는 작업 경로, 최근 변경, 진행 기록, 선택한 기능의 상태를 확인합니다. 실행 스크립트로 환경을 준비한 뒤 기존 동작의 기본 검사를 수행합니다. 이전 기록에 정상이라고 적혀 있어도 현재 환경이 같은지는 확인해야 합니다.

검사가 실패했다면 새 기능을 쌓기 전에 원인을 구분합니다. 실행 환경이 준비되지 않은 것인지, 이전 구현이 깨진 것인지, 검사 자체의 전제가 달라진 것인지 확인합니다. 다른 작업자가 남긴 변경도 이번 작업과 구분해서 보존해야 합니다.

작업 시작마다 전체 저장소를 모두 읽을 필요는 없습니다. 현재 상태와 이번 기능의 관련 파일에서 시작하고 근거가 부족한 부분을 추가로 확인하면 됩니다.

한 기능의 동작과 수용 조건

여러 기능을 동시에 일부만 구현하면 다음 세션에서 각 기능의 남은 일을 구분하기 어려워질 수 있습니다. 선택한 기능을 구현하고 그 기능의 수용 조건을 확인한 뒤 상태를 갱신하면 중간 상태를 관리하기 쉽습니다.

예를 들어 새 채팅 생성 기능에서는 버튼 클릭, 화면 전환, 목록 표시, 저장 상태를 확인할 수 있습니다. API 응답만 검사하면 버튼 연결이나 화면 갱신이 빠진 문제를 놓칠 수 있습니다. 실제 사용자 흐름이 중요한 기능은 브라우저에서 끝까지 확인합니다.

문구 변경은 표시 결과를, 저장 기능 변경은 저장과 재조회까지 검사하는 식으로 동작에 맞는 방법을 고릅니다. 기존 검사가 그 조건을 확인하는지도 읽어야 합니다.

종료 상태를 뒷받침하는 증거

기능 목록의 통과 상태는 구현자의 판단만으로 바꾸지 않습니다. 해당 동작을 확인한 검사와 결과가 있어야 합니다. 어려운 항목을 삭제하거나 검사를 약하게 바꿔 통과시키면 완료 기준이 사라집니다.

코딩 에이전트는 종료 기록에 바뀐 부분, 검사 결과, 미검증 사항, 다음 행동을 남깁니다. 실행하지 못한 검사는 실패나 통과로 꾸미지 않고 필요한 조건을 적습니다. 다음 세션에서 같은 조사를 반복하지 않도록 실패 원인도 보존합니다.

원문은 세션 종료 시 커밋을 남기는 방법도 사용합니다. 실제 프로젝트에서는 사용자의 권한과 저장소 정책에 따라 커밋 여부를 정해야 합니다. 상태 기록이 필요하다는 이유로 푸시나 배포까지 자동으로 확장할 수는 없습니다.

새 채팅 기능의 종료 기록에는 버튼 클릭, 목록 표시, 저장 상태 중 어디까지 확인했는지 적습니다. 다음 세션의 에이전트는 미검증 항목부터 이어가고, 이미 통과한 동작은 새 변경의 영향을 받는지 판단해 검사할 수 있습니다.

종료 전에는 기능 상태와 검사 결과가 일치하는지 대조합니다. 구현했지만 확인하지 못한 동작은 미검증으로 남기고, 다음 세션에서 필요한 조건과 첫 행동을 기록합니다.