본문으로 건너뛰기
Hoegun You
뒤로

에이전트는 잊는다, 그래서 적는다

책과 바인더로 쌓은 계단을 오르는 사람과 작은 로봇

9월에 우리 시스템에 대해 간단한 질문을 하나 던졌다. 이 테이블을 바꾸면 어디가 깨지지?

찾아볼 곳이 없었다. 저장소는 열한 개였다. 그중 제대로 된 문서가 있는 곳은 하나뿐이었고, 그 문서마저 버전 관리 밖에 있었다. 어떤 저장소의 README는 자기 이름 한 줄이 전부였다. 코딩 에이전트에게 어디서부터 보라고 알려 주는 규칙 파일은 어디에도 없었다. 그래서 그 질문이 나올 때마다 누군가 코드를 처음부터 다시 읽어야 했다. 에이전트가 대신 읽게 된 뒤에도 나아지지 않았다. 새 세션은 앞 세션이 알아낸 것을 갖고 있지 않았고, 그래서 또 처음부터 읽었다.

이 글의 교훈은 이것이다. 기록이 에이전트의 기억이다. 다음 세션이 이번 맥락을 갖고 있다고 가정하지 않는다. 지속되는 기록을 주고, 그 기록이 실제로 읽혔는지 확인한다.

내 일에 AI 에이전트를 들이면서 배운 것을 정리하는 시리즈의 5편이다. 4편은 일을 맡길 때 에이전트에게 맥락을 주는 이야기였다. 이번 글은 일이 끝난 뒤에 남는 것에 관한 이야기다.

기록이 에이전트의 기억이다

새 세션은 어제 회의에 없었던 아주 유능한 신입처럼 대하는 게 맞다. 기록을 건네지 않으면 세상 일반은 알아도 우리 시스템은 거의 모른다. 테이블 이름이 왜 그렇게 이상한지, 진짜 상태 값이 어느 컬럼에 있는지, 지난주에 빠졌던 함정이 무엇인지. 대신 읽는 건 잘한다. 글로 남긴 기록이 있으면 다음 세션은 같은 것을 다시 알아내는 대신 찾아서 참고할 수 있다.

그러니 질문은 “에이전트가 기억하게 하려면?”이 아니다. “우리는 무엇을 적어 뒀나?”다.

기록이 에이전트의 기억이다: 일한다 → 적는다 → 다음 세션은 기록에서 시작한다 → 같은 실수가 줄어든다

이 고리는 한 바퀴 돌 때마다 다음 바퀴를 가볍게 만든다. “적는다”를 건너뛰면 고리가 끊긴다. 세션마다 앞 세션이 배운 것을 다시 알아내야 하고, 새로 온 동료도 마찬가지다.

문서 허브를 하루에

9월 17일, 문서를 어디에 둘지 정했다. 선택지 세 개를 적었다.

  • 저장소마다 문서를 채운다. 코드와 가깝지만, 가장 값진 사실인 서비스끼리 어떻게 이어지는지를 적을 곳이 없다. “이 API가 저 API를 부른다”는 어느 쪽 저장소에 적어도 절반만 맞다. 결국 두 번 적게 되고, 둘은 갈라진다.
  • 위키. 고치기 쉽지만 코드와 떨어져 있어 빨리 낡는다. 위키는 별도의 조회 경로가 필요하다. 저장소라면 에이전트가 이미 쓰는 파일 도구로 읽을 수 있었다.
  • 문서만 모으는 별도 저장소, 허브. 서비스 사이의 사실이 자리 잡을 곳이 생기고, 에이전트가 코드를 읽는 바로 그 도구로 읽을 수 있다. 이걸 골랐다.

허브에는 어느 한 저장소에도 속하지 않는 것을 둔다. 서비스 사이의 연결, 데이터베이스, 운영, 결정 기록이다. 실행 방법이나 API 명세처럼 코드 옆에 있어야 하는 문서는 각 저장소에 남긴다. 그리고 에이전트에게 코드를 읽게 하면서 같이 썼다. 첫날 문서 63편과 에이전트를 허브로 안내하는 첫 규칙 파일들을 만들었다. 지금은 문서가 모두 100편을 넘는다.

그날 내린 결정 중 두 가지가 생각보다 중요했다.

  • 사람이 이미 아는 것을 다시 쓴다. 누군가 운영 스크립트를 모아 둔 저장소에, 개발자라면 찾아가지 않을 곳에 훌륭한 데이터베이스 레퍼런스를 써 두었다. 그중 가장 값진 부분은 함정들이었다. 비슷한 테이블 이름 둘 중 어느 쪽이 진짜인지, 진짜 상태 값은 어느 컬럼에 있는지. 코드를 읽어서는 나오지 않는 지식이다. 이걸 허브로 옮기고, 이제부터는 허브가 원본이라고 못 박았다. 사본 둘이 서로 갈라지는 대신 원본 하나만 남게 했다.
  • 큰 파일은 쪼갠다. 그 레퍼런스는 895줄짜리 문서 하나였다. 도메인별로 나눴다. 파일이 크면 에이전트가 필요한 부분과 함께 필요 없는 부분까지 읽기 때문이다.

문서가 낡지 않게

문서 허브에는 뻔한 약점이 있다. 코드가 아니니 낡을 수 있다. 네 가지로 막는다.

문서가 정직하게 남는 방법: 문서마다 출처를 적고, 저장소마다 규칙 파일을 두고, Slack 에이전트가 불일치를 알리면 사람이 고치고, 현재 동작은 확인되지 않은 문서보다 코드가 우선한다

  • 문서마다 출처를 적는다. 문서 머리에 그 문서가 설명하는 코드 경로와 마지막으로 확인한 날짜를 적는다. 작은 점검 스크립트가 그 날짜와 해당 코드의 마지막 변경을 비교해, 낡은 문서를 표시한다.
  • 저장소마다 규칙 파일을 둔다. 구조를 바꿨다면 문서도 고친다. 이 규칙을 누군가의 기억이 아니라 에이전트가 가장 먼저 읽는 파일에 걸었다.
  • 에이전트가 불일치를 알려 준다. Slack 에이전트가 질문에 답하다가 문서가 코드와 다르다는 걸 발견하면, 묻는 사람과 따지지 않는다. 로그에 한 줄 남기고, 정해진 작업이 그걸 나에게 보낸다. Slack 에이전트는 문서를 직접 고치지 못한다. 불일치를 보고하면 내가 처리하고, 문서는 내가 고친다.
  • 현재 동작은 코드가 우선한다. 규칙에는 문서와 코드가 다르면 지금 어떻게 동작하는지는 코드가 맞다고 적혀 있다. 그래서 에이전트는 확인되지 않은 문서를 눈앞의 코드보다 믿지 않는다. 그 동작이 맞는지는 별도로 판단한다.

이 중 두 가지는 배울 게 많은 방식으로 실패했다.

  • 신선도는 갱신 경로가 정한다. 처음 며칠 동안 에이전트가 도는 머신은 문서 허브를 아예 받아 오지 않았다. “최신 문서로 답한다”는 규칙은 최신 문서가 도착하지 않으면 아무 의미가 없다. 알아차린 뒤, 허브를 그 머신이 계속 갱신하는 저장소 목록에 넣었다.
  • 보고가 사라질 수 있다. 불일치 보고 하나가 지나치게 예민한 안전 점검에 막혔다. 따옴표 안 문장의 마침표가 파일 경로처럼 보였던 것이다. 에이전트는 다시 시도하지 않았고, 보고는 나에게 닿지 않았다. 사흘 뒤 안전 장치가 막은 기록을 점검하다가 발견해, 점검 규칙과 문서를 둘 다 고쳤다. 그 점검 이야기는 이 블로그의 첫 글에 썼다.

grep에서 질문 한 번으로

문서는 “이게 뭐지?”에는 잘 답했다. 하지만 “이걸 바꾸면 뭐가 깨지지?”는 여전히 느렸다. 에이전트는 허브에서 시작해 문서가 가리키는 코드 경로로 가고, 다시 코드를 검색했다. 빠뜨리는 게 있었고, 코드를 많이 열수록 Slack에 코드를 인용할 위험도 커졌다.

10월 말, 에이전트들을 메타데이터 그래프에 연결했다. 데이터베이스 스키마, 코드, 라우트, 정해진 작업, 문서로 만든 그래프다. 이제 규칙은 “그래프에 먼저 묻고, 그래프가 가리킨 파일과 줄만 연다”다. “이 테이블에 쓰는 코드는?”, “이 값을 바꾸면 어디가 영향을 받을 수 있지?” 같은 질문이 한두 번의 조회로 끝나고, 답에는 파일과 줄 범위가 근거로 붙는다.

대가도 적어 뒀다. 그래프는 손으로 다시 만들어야 해서 코드보다 늦을 수 있다. 오래된 코드 중에는 쿼리를 조립하는 방식 때문에 추출하지 못한 곳이 있다. 영향 범위는 넓게 잡힌다. 그래서 에이전트는 “영향”이 아니라 “가능한 영향”이라고 말한다.

에이전트도 자기 기록을 남긴다

에이전트 구성 자체도 같은 방식으로 기록한다. 거의 매일 바뀌기 때문이다.

  • 일지. 최신 항목이 맨 위에 오고, 날짜에 묶인 사실만 적는다. 더하기만 하고 고치지 않는다.
  • 교훈 파일. 항목마다 관찰과 교훈을 적는다. 지금 서른 개가 넘는다.
  • 결정 기록. 10월 17일부터 11월 11일까지 36개. 각각 맥락, 검토한 선택지, 결정, 그리고 감수한 대가를 담는다.

서류가 목적이 아니다. 다음 세션이, 나든 에이전트든, 무엇이 왜 이렇게 됐는지를 읽을 수 있게 하는 것이 목적이다.

전부 다시 세운 날

10월 31일, 에이전트가 도는 머신을 처음부터 다시 설치했다. 다음 날이 끝날 무렵 전부 돌아와 있었다. 에이전트들, 조사 담당이 쓰는 마스킹된 시험 환경, 읽기 전용 데이터 창구, 2편의 감시 체계까지. 세 단계로 나눠 올렸고, 단계마다 확인한 뒤 다음으로 넘어갔다.

설치 절차와 규칙과 그 이유가 전부 글로 남아 있었기에 가능했다. 하는 김에 설치 안내서도 다음번을 위해 고쳐 뒀다.

문서의 한계도 그날 드러났다. 감시 하나의 이력은 그 머신의 로컬 데이터베이스에만 있었고, 그건 사라졌다. 문서는 무언가가 어떻게 돌아가는지를 다시 세우게 해 준다. 데이터를 돌려주지는 않는다. 다시 세우는 법은 적어 두고, 다시 만들 수 없는 것은 백업한다.

프로젝트가 아니라 습관

이 모든 게 거창한 문서화 작업을 요구하지 않는다. 일 하나가 끝날 때의 습관이면 된다. 내 가이드에서는 세션을 마칠 때 에이전트에게 이렇게 시키라고 권한다.

  1. 작업 일지에 몇 줄 더한다. 무엇을 했고, 결과가 어땠고, 무엇이 남았는지.
  2. 오늘 바로잡은 것 중 다음에도 지켜야 할 것을 규칙 파일에 더한다.
  3. 다음에 이어서 할 때 첫 요청으로 붙여 넣을 문장을 제안한다.

가장 쓸모 있는 건 세 번째다. 다음 세션이 다시 알아내는 대신, 이번 세션이 멈춘 자리에서 시작한다.

적지 말아야 할 것도 짧게 적어 둔다. 대화 전체(아무도 다시 읽지 않는다. 결론만 남긴다), 개인정보나 비밀 값, 그리고 이미 다른 곳에 있는 것의 사본. 사본은 반드시 갈라진다. 원본으로 가는 링크를 남긴다.

여기서 얻은 것

  • 기록이 에이전트의 기억이다. 다음 세션이 이번 맥락을 갖고 있다고 가정하지 말고, 적어 두고 실제로 읽히는지 확인한다.
  • 시스템을 가로지르는 사실에는 따로 집을 준다. 시스템끼리 어떻게 이어지는지는 어느 한 저장소의 것이 아니다.
  • 사람이 이미 써 둔 지식을 다시 쓴다. 값진 건 함정이고, 함정은 코드가 알려 주지 않는다.
  • 낡은 것을 보이게 만든다. 문서마다 출처와 마지막 확인 날짜를 적고, 스크립트가 불평하게 둔다.
  • 문서로 돌아오는 고리를 닫는다. 에이전트가 발견한 틀린 점을 알려 주게 하고, 그 보고가 실제로 도착하는지 확인한다.
  • 다시 세우는 법은 적고, 다시 만들 수 없는 것은 백업한다.

시리즈 목차

  1. 직접 하던 사람에서 맡기는 사람으로
  2. 판정은 코드가, 설명은 LLM이
  3. 내가 절대 어기지 않는 규칙
  4. 맥락이 실력이다
  5. 에이전트는 잊는다, 그래서 적는다 (이 글)
  6. kenny: 내 일을 대신하는 에이전트
  7. Hermes: 확인할 일을 챙겨 주는 리마인더
  8. 2주 만에 시작하는 법

여러분의 시스템에서, 누군가(또는 무언가)가 매번 코드를 처음부터 읽어야만 답할 수 있는 질문은 무엇인가?



이전 글
맥락이 실력이다