소개
제 AI 에이전트는 작업을 시작하기 전에 지정된 파일을 자동으로 읽어오도록 설정해두었습니다. 읽어오는 파일 중 하나인 SESSION_STATE.md (세션 메모)는 지금 진행 중인 작업을 짧게 알려주는 파일입니다.
지난번에 이 파일을 줄여두었지만 며칠 뒤 다시 열어보니, 작업 하나를 설명하는 문단이 길게 붙어 있었습니다. 게다가 형식에 없는 항목 하나 때문에 에이전트가 시작조차 하지 못했습니다. 저는 길이 상한을 더 세게 거는 대신, 상세 정보가 세션 메모에 들어갈 수 없도록 구조를 바꿨습니다.
이런 분께
에이전트의 상태 파일이 자꾸 길어지는 분
짧게 쓰자는 규칙이 며칠 뒤 무너지는 분
여러 작업을 동시에 진행하며 작업별 맥락을 관리해야 하는 분
무엇이 문제였나
세션 메모에는 미리 정해둔 항목 이름만 쓸 수 있도록 형식 검사를 걸어두었습니다. 이 검사를 수행하는 작은 파이썬 스크립트를 저는 코드 게이트라고 부릅니다. 에이전트는 일을 시작하기 전에 이 게이트를 통과합니다.
그런데 다른 에이전트가 상태를 기록하는 과정에서 다음 조사 방향이라는 항목이 추가됐습니다. 원래 코드 게이트의 허용 목록에 없는 항목이었고, 게이트는 다음과 같이 거부했습니다.
master-awaken: 정의 밖 항목 (파일 23번째 줄): "다음 조사 방향"그 줄 하나만 지우면 당장의 막힘은 풀립니다. 하지만 저는 이 실패를 단순한 오타가 아니라, 상세 정보를 세션 메모에 계속 덧붙이는 구조의 문제로 해석했습니다. 당시 사용하던 게이트에는 이런 상세 항목의 유입을 막는 검사가 없었습니다.
상한보다 구조가 먼저였습니다
처음에 AI가 제안한 방법은 형식을 그대로 두고 각 줄에 길이 상한을 두는 것이었습니다. 하지만 저는 한 번에 하나의 작업만 하지 않고 여러 세션창을 열어서 동시에 진행하는 편입니다. 진행한 작업마다 한 줄씩만 남겨도 작업 수만큼 줄이 늘고, 상세를 조금이라도 남기면 다시 문단이 됩니다.
"어차피 나는 여러 작업을 한꺼번에 여러 세션 띄워서 하는데, 아무리 짧게 줄인다 해도, 작업별 요약을 한 파일에 다 적으면 결국 길어질 수 밖에 없어"
그래서 문제를 “한 줄이 얼마나 긴가”가 아니라 “한 파일에 여러 작업의 상세를 모두 담고 있는가”로 다시 정의했습니다.
전환점: 목록표와 인계장으로 분리하기
새 구조에서 세션 메모에는 작업 목록만 남깁니다. 작업마다 한 줄을 쓰되, 상태와 상세가 있는 위치만 적습니다. 상세 정보는 작업별 인계장(handoff, 다음 세션에서 작업을 이어가기 위한 메모)으로 분리합니다.
세션 메모: 지금 살아 있는 작업의 이름, 상태, 인계장 위치
인계장: 작업의 배경, 결정 사항, 다음 할 일
작업 종료 시: 종결 내용이 최종 기록에 남았는지 확인한 뒤 인계장을 삭제
코드 작업의 종결 내용은 깃허브 커밋 메시지에 남기고, 인계장은 살아 있는 동안에만 유지합니다. 삭제는 자동으로 맡기지 않고 제가 확인합니다. 끝난 작업을 치우는 것은 여전히 제 몫입니다.
예를 들면 목록표는 다음처럼 유지합니다. 아래는 구조를 보여주기 위한 예시입니다.
## 진행 중 작업
- 사례글 도구 개선: 승인 대기 -> HANDOFF-사례글-도구개선.md
- 컨텍스트 감시: 1차 관측 완료 -> HANDOFF-컨텍스트감시.md작업이 여러 개면 목록표의 줄 수는 늘어납니다. 다만 한 작업의 상세가 세션 메모 안에서 문단째 커지는 방식은 피할 수 있습니다. 이번 변경으로 실제로 필요한 작업의 인계장만 열 수 있게 운영했습니다. 여러 세션 뒤에도 이 방식이 얼마나 잘 유지되는지는 아직 장기적으로 측정하지 않았습니다.
게이트도 새 구조에 맞게 바꿨습니다
구조를 정한 뒤, 구현은 다른 AI에게 맡겼습니다. 게이트의 역할도 “조금만 어긋나면 시작을 차단하는 장치”에서 “필수 형식은 확인하고 운영상 문제는 경고하는 장치”로 바꿨습니다.
[전에는]
허용 목록 밖 항목 하나 추가 -> 게이트 거부 -> 에이전트 시작 중단
[이제는]
작업 목록을 읽어 출력
+ 인계장 파일이 있는지 확인
+ 끝난 작업의 인계장이 남아 있는지 확인
-> 운영상 문제는 경고하고 시작은 계속이번에 정한 원칙은 다음과 같습니다.
게이트 자체를 실행할 수 없을 정도로 필수 형식이 깨지면 차단합니다.
파일이 조금 길거나 인계장이 하나 비는 문제는 경고하고 통과시킵니다.
경고를 없애고 실제 정리하는 일은 사람이 확인해 처리합니다.
이렇게 한 이유는 고치러 들어가야 할 상태 파일 때문에 에이전트의 시작 자체가 막히는 상황을 피하기 위해서입니다.
구현과 검수는 나누었습니다
구현이 끝난 뒤에는 다른 AI에게 검수를 맡겼습니다. 구현과 검수를 분리해, 만든 결과를 그대로 통과시키는 위험을 줄이려 했습니다.
검수 과정에서 작업 이름이 빈칸인 줄이 통과되는 문제가 발견됐습니다. 실제로 재현해보니 형식 위반인데도 통과했고, 구현 AI에게 해당 부분을 수정하게 했습니다. 같은 검수 AI에게 다시 확인받아 수정 사항을 닫았습니다.
결과: 무엇을 확인했나
게이트의 형식 판정과 오류 처리를 확인하는 자동 시험 234개가 수정 후 모두 통과했습니다.
검수에서 발견된 작업 이름 누락 문제 1건을 수정하고 재확인했습니다.
실제 세션 메모에 대고 에이전트 시작을 실행했을 때, 더 이상 문턱에서 멈추지 않고 작업 목록을 출력하며 통과했습니다.
세션 메모에서 작업별 상세 문단을 분리하고, 작업 목록 중심의 형태로 바꿨습니다.
다만 234개 시험은 게이트가 규칙대로 동작하는지를 확인한 결과입니다. 여러 세션 뒤에도 파일 길이가 유지되는지, 실제 컨텍스트 사용량이나 처리 시간이 줄었는지는 이 글에서 측정하지 않았습니다.
배운 점과 한계
“짧게 쓰자”는 규칙만으로는 에이전트 컨텍스트에 들어오는 '세션 상태'를 반영하는 노트가 금세 길어지는 것을 막지 못했습니다. 이번에 바꾼 것은 길이 상한이 아니라 상세 내역이 머무는 위치였습니다. 세션 노트의 목록표는 세션 상태와 인계장 위치만 보여주고, 작업의 맥락은 인계장으로 보냅니다.
이 구조가 해결한 것은 작업 하나의 상세가 세션 메모 안에서 무제한으로 커지는 문제입니다. 반면 작업 수가 늘어나는 것과 끝난 인계장을 정리하는 일은 여전히 관리해야 합니다. 따라서 이번 결과는 장기적으로 파일이 절대 커지지 않는다는 증명이 아니라, 실제 시작을 막았던 형식 오류를 수정하고 상세를 분리한 직후의 검증 결과입니다.
한국 비즈니스 프로세스 흐름도
마무리
형식 밖 줄 하나 때문에 에이전트가 멈췄을 때, 처음에는 그 줄만 지우면 된다고 생각했습니다. 하지만 더 오래 남는 해결책은 상세가 세션 메모에 눌러앉을 자리를 없애는 것이었습니다. 구조는 작업별 상세의 무제한 유입을 제한하고, 끝난 작업을 치우는 일은 사람이 맡는 방식입니다.
