AI 코딩 에이전트가 일을 끝냈다고 말할 때, 나는 바로 결과 파일부터 보지 않는다.

먼저 무엇을 남겼는지 본다.

코드는 바뀌었는데 어떤 요청에서 시작했는지 없고, 테스트를 돌렸다고 했는데 명령과 결과가 없고, 위험한 변경을 왜 허용했는지 기록이 없으면 다음 사람이 이어받기 어렵다. 며칠 뒤의 나도 그 다음 사람에 포함된다.

그래서 에이전트 작업은 결과물만 남기면 부족하다. 작업 로그, 감사 추적, 검증 증거를 따로 남겨야 한다.

에이전트 기록을 작업 로그, 감사 추적, 검증 증거 세 카드로 나누어 보여주는 다이어그램.

기록의 목적은 모든 대화를 보존하는 것이 아니다. 나중에 다시 봤을 때 “무엇을 했고, 왜 했고, 어디까지 확인했는지”를 빠르게 복원하는 것이다.

결과물만 남기면 일이 뭉개진다

에이전트가 만든 결과물은 보기 좋을 때가 많다.

새 문서가 생기고, UI가 바뀌고, 테스트가 통과하고, 변경 저장(commit)이 남는다. 겉으로는 끝난 것처럼 보인다.

하지만 나중에 문제가 생기면 결과물만으로는 부족하다.

예를 들어 고객 문서 한 건을 릴리스했다고 해보자. 문서 파일은 있다. 필요한 공개 파일(asset)도 있다. 빌드(build)도 통과했다. 그런데 나중에 검색 결과 설명이 이상하게 나오거나, 첨부 이미지가 고객 포털에서 안 뜨거나, 공개하면 안 되는 표현을 발견하기도 한다.

그때 필요한 질문은 이런 것들이다.

처음 요청은 무엇이었나?
어떤 문서를 기준으로 썼나?
초안에서 무엇을 제외했나?
공개 파일(asset)은 실제 경로에 저장됐나?
어떤 검증 명령이 통과했나?
원격 저장소 반영(push)이나 배포(deploy)는 했나, 아니면 로컬에서 멈췄나?

이 질문에 답할 수 없으면, 에이전트가 한 일은 “파일이 바뀌었다”로만 남는다.

그건 기록이 아니라 흔적이다.

작업 로그는 무엇을 했는지 남긴다

작업 로그는 가장 단순한 층이다.

여기에는 에이전트가 무엇을 바꿨는지 적는다. 문서를 만들었는지, 테스트를 추가했는지, 설정을 고쳤는지, 공개 파일(asset)을 저장했는지, 어떤 파일은 건드리지 않았는지 남긴다.

좋은 작업 로그는 길 필요가 없다.

변경:
- 릴리스 노트를 추가했다.
- 공개 이미지와 첨부 파일(asset)을 배포 경로에 저장했다.
- 문서 색인과 검색에 쓰는 공개 데이터(document index mirror)를 문서 메타데이터(metadata) 기준으로 맞췄다.

건드리지 않음:
- 실제 서비스 데이터베이스(production DB)는 변경하지 않았다.
- 원격 저장소 반영(push)과 운영 배포는 하지 않았다.

핵심은 “했다”와 “하지 않았다”를 같이 적는 것이다.

에이전트 작업에서 사고는 보통 이 둘이 섞일 때 생긴다. 로컬 빌드(build) 통과가 실제 서비스(live) 배포를 보장하지 않는다. 대화창에 보이는 이미지가 문서 저장소의 실제 파일(repo asset)로 남았다는 보장도 없다. 데이터 변경용 SQL 작성과 실제 서비스 데이터베이스(production DB) 적용 역시 별개다.

작업 로그는 이 구분을 남긴다.

감사 추적은 왜 했는지 남긴다

감사 추적은 더 귀찮지만 더 중요하다.

감사 추적은 “무엇을 했는가”보다 “왜 그렇게 판단했는가”를 남긴다. 어떤 규칙을 읽었는지, 어떤 사용자 승인이 있었는지, 어떤 대안은 왜 버렸는지, 위험한 작업 앞에서 어디서 멈췄는지를 적는다.

예를 들어 이렇게 남긴다.

판단:
- 고객 문서 릴리스 요청이므로 초안 상태를 해제했다. 사용자가 공개 요청을 승인했기 때문이다.
- 원격 저장소 반영(push)은 외부 상태 변경이라 수행하지 않았다. 별도 승인이 필요하다.
- 공개 이미지는 임시 그림이나 대체 SVG가 아니라, 문서 배포 기준이 요구하는 실제 공개 파일(asset)로 저장했다.

이 기록이 없으면 나중에 결과만 보고 오해하기 쉽다.

“왜 원격 저장소 반영(push)을 안 했지?”

“왜 이미지가 꼭 필요했지?”

“왜 초안 상태가 해제됐지?”

감사 추적은 이런 질문에 답한다. 사람을 감시하지 않고 판단을 다시 검토하게 만드는 문서다.

특히 에이전트가 여러 단계를 거쳤다면 감사 추적은 더 필요하다. 처음에는 API 문서를 수정하는 작업이었는데, 중간에 공개 이미지, 문서 색인 데이터 정리(index), 빌드(build), 변경 저장(commit)까지 이어지기도 한다. 범위가 넓어질수록 “왜 이 단계까지 갔는가”를 남겨야 한다.

검증 증거는 어디까지 확인했는지 남긴다

검증 증거는 말이 아니라 확인 결과다.

에이전트가 “테스트했습니다”라고 쓰는 것만으로는 부족하다. 어떤 명령을 실행했고, 결과가 통과했는지, 어떤 문서 주소(route)를 열어 봤는지, 어떤 파일이 실제로 생겼는지를 남겨야 한다.

검증 증거는 이런 형태가 좋다.

검증:
- 관련 공개 검증 스크립트 통과
- npm run check 통과
- npm run build 통과
- 새 API 문서의 대표 주소(canonical route)가 빌드 결과(build output)에 포함됨
- 공개 이미지 파일이 배포 대상 파일 경로에 있음

브라우저로 확인했다면 더 구체적으로 적는다.

브라우저 확인:
- 데스크톱 문서 주소(route)에서 H1, 공개 이미지, 설명(description) 확인
- mobile 390px에서 가로 overflow 없음 확인

반대로 확인하지 않은 것도 적어야 한다.

미수행:
- 공개 배포 뒤 실제 서비스 확인은 하지 않음
- 운영 데이터베이스의 문서 검색용 복사본 갱신은 하지 않음
- 고객 계정이나 조회수처럼 상태를 바꾸는 검증은 하지 않음

이렇게 적으면 완료 보고가 과장되지 않는다.

검증 증거는 에이전트를 믿기 위한 장식이 아니다. 나중에 같은 문제를 다시 볼 때 “어디까지는 통과했고, 어디부터는 확인하지 않았다”를 빠르게 나누기 위한 기준이다.

기록하지 말아야 할 것도 있다

기록을 남긴다고 해서 모든 것을 저장하면 안 된다.

특히 공개 문서나 외부 공유 보고에는 아래 내용을 그대로 넣지 않는다.

  • secret, token, API key
  • 비공개 저장소명(private repo명)이나 비공개 조직명
  • 내부 절대 경로
  • 고객 정보나 개인 정보
  • 비공개 대화 원문
  • 긴 로그 전체

필요하면 치환한다.

[private repo]
[internal path]
[redacted]

좋은 기록은 많은 정보를 담는 것이 아니라, 공개해도 되는 최소 증거를 담는다. 전체 로그가 필요하면 안전한 내부 저장소에 두고, 공개 문서나 완료 보고에는 판단에 필요한 요약만 남기는 편이 낫다.

내가 쓰는 최소 템플릿

작업이 작으면 아래 정도면 충분하다.

요청:
- 사용자가 요구한 최종 상태

변경:
- 실제 바꾼 파일과 내용

판단:
- 기준으로 삼은 문서, 규칙, 승인, 버린 대안

검증:
- 실행한 명령과 통과/실패
- 확인한 화면, 문서 주소(route), 파일, 증거 파일(artifact)

미수행:
- 하지 않은 원격 반영(push), 배포(deploy), DB 변경, 실제 사이트 확인(live smoke)

남은 리스크:
- 다음 사람이 이어서 봐야 할 것

이 템플릿은 완벽한 감사 시스템이 아니다. 그래도 에이전트 작업이 “대화가 끝났으니 끝”으로 사라지는 것을 막는다.

작업 로그에는 결과를 쓴다.

감사 추적에는 판단을 남긴다.

검증 증거는 완료 주장을 뒷받침한다.

이 셋이 있어야 에이전트가 한 일을 나중에 다시 본다.

하네스 안에 기록을 넣는다

하네스 엔지니어링에서는 작업, 기준, 검증, 기록, 재시도, 승인을 한 흐름으로 묶어야 한다고 썼다. 오늘 글은 그중 “기록”을 조금 더 좁힌 것이다.

기록은 마지막에 붙이는 보고서가 아니다. 작업 중간중간 완료 주장을 검증 가능한 말로 바꾸는 장치다.

에이전트에게 일을 맡길수록 속도보다 더 중요한 것이 생긴다.

나중에 다시 봐도 이해되는가.

다음 사람이 이어받을 수 있는가.

하지 않은 일을 했다고 착각하지 않게 막는가.

AI 코딩 에이전트가 한 일을 남긴다는 것은 결국 이 세 질문에 답하는 일이다.