본문으로 건너뛰기

형식 밖 줄 하나에 에이전트가 멈췄습니다: 상태 파일을 목록표로 다시 짠 기록

리히토

2026.08.16

형식 밖 줄 하나에 에이전트가 멈췄습니다: 상태 파일을 목록표로 다시 짠 기록 본문 이미지

소개

제 AI 에이전트는 작업을 시작하기 전에 지정된 파일을 자동으로 읽어오도록 설정해두었습니다. 읽어오는 파일 중 하나인 SESSION_STATE.md (세션 메모)는 지금 진행 중인 작업을 짧게 알려주는 파일입니다.

지난번에 이 파일을 줄여두었지만 며칠 뒤 다시 열어보니, 작업 하나를 설명하는 문단이 길게 붙어 있었습니다. 게다가 형식에 없는 항목 하나 때문에 에이전트가 시작조차 하지 못했습니다. 저는 길이 상한을 더 세게 거는 대신, 상세 정보가 세션 메모에 들어갈 수 없도록 구조를 바꿨습니다.

이런 분께

  • 에이전트의 상태 파일이 자꾸 길어지는 분

  • 짧게 쓰자는 규칙이 며칠 뒤 무너지는 분

  • 여러 작업을 동시에 진행하며 작업별 맥락을 관리해야 하는 분

무엇이 문제였나

세션 메모에는 미리 정해둔 항목 이름만 쓸 수 있도록 형식 검사를 걸어두었습니다. 이 검사를 수행하는 작은 파이썬 스크립트를 저는 코드 게이트라고 부릅니다. 에이전트는 일을 시작하기 전에 이 게이트를 통과합니다.

그런데 다른 에이전트가 상태를 기록하는 과정에서 다음 조사 방향이라는 항목이 추가됐습니다. 원래 코드 게이트의 허용 목록에 없는 항목이었고, 게이트는 다음과 같이 거부했습니다.

master-awaken: 정의 밖 항목 (파일 23번째 줄): "다음 조사 방향"

그 줄 하나만 지우면 당장의 막힘은 풀립니다. 하지만 저는 이 실패를 단순한 오타가 아니라, 상세 정보를 세션 메모에 계속 덧붙이는 구조의 문제로 해석했습니다. 당시 사용하던 게이트에는 이런 상세 항목의 유입을 막는 검사가 없었습니다.

상한보다 구조가 먼저였습니다

처음에 AI가 제안한 방법은 형식을 그대로 두고 각 줄에 길이 상한을 두는 것이었습니다. 하지만 저는 한 번에 하나의 작업만 하지 않고 여러 세션창을 열어서 동시에 진행하는 편입니다. 진행한 작업마다 한 줄씩만 남겨도 작업 수만큼 줄이 늘고, 상세를 조금이라도 남기면 다시 문단이 됩니다.

"어차피 나는 여러 작업을 한꺼번에 여러 세션 띄워서 하는데, 아무리 짧게 줄인다 해도, 작업별 요약을 한 파일에 다 적으면 결국 길어질 수 밖에 없어"

그래서 문제를 “한 줄이 얼마나 긴가”가 아니라 “한 파일에 여러 작업의 상세를 모두 담고 있는가”로 다시 정의했습니다.

전환점: 목록표와 인계장으로 분리하기

새 구조에서 세션 메모에는 작업 목록만 남깁니다. 작업마다 한 줄을 쓰되, 상태와 상세가 있는 위치만 적습니다. 상세 정보는 작업별 인계장(handoff, 다음 세션에서 작업을 이어가기 위한 메모)으로 분리합니다.

  • 세션 메모: 지금 살아 있는 작업의 이름, 상태, 인계장 위치

  • 인계장: 작업의 배경, 결정 사항, 다음 할 일

  • 작업 종료 시: 종결 내용이 최종 기록에 남았는지 확인한 뒤 인계장을 삭제

코드 작업의 종결 내용은 깃허브 커밋 메시지에 남기고, 인계장은 살아 있는 동안에만 유지합니다. 삭제는 자동으로 맡기지 않고 제가 확인합니다. 끝난 작업을 치우는 것은 여전히 제 몫입니다.

예를 들면 목록표는 다음처럼 유지합니다. 아래는 구조를 보여주기 위한 예시입니다.

## 진행 중 작업
- 사례글 도구 개선: 승인 대기 -> HANDOFF-사례글-도구개선.md
- 컨텍스트 감시: 1차 관측 완료 -> HANDOFF-컨텍스트감시.md

작업이 여러 개면 목록표의 줄 수는 늘어납니다. 다만 한 작업의 상세가 세션 메모 안에서 문단째 커지는 방식은 피할 수 있습니다. 이번 변경으로 실제로 필요한 작업의 인계장만 열 수 있게 운영했습니다. 여러 세션 뒤에도 이 방식이 얼마나 잘 유지되는지는 아직 장기적으로 측정하지 않았습니다.

게이트도 새 구조에 맞게 바꿨습니다

구조를 정한 뒤, 구현은 다른 AI에게 맡겼습니다. 게이트의 역할도 “조금만 어긋나면 시작을 차단하는 장치”에서 “필수 형식은 확인하고 운영상 문제는 경고하는 장치”로 바꿨습니다.

[전에는]
허용 목록 밖 항목 하나 추가 -> 게이트 거부 -> 에이전트 시작 중단

[이제는]
작업 목록을 읽어 출력
+ 인계장 파일이 있는지 확인
+ 끝난 작업의 인계장이 남아 있는지 확인
-> 운영상 문제는 경고하고 시작은 계속

이번에 정한 원칙은 다음과 같습니다.

  • 게이트 자체를 실행할 수 없을 정도로 필수 형식이 깨지면 차단합니다.

  • 파일이 조금 길거나 인계장이 하나 비는 문제는 경고하고 통과시킵니다.

  • 경고를 없애고 실제 정리하는 일은 사람이 확인해 처리합니다.

이렇게 한 이유는 고치러 들어가야 할 상태 파일 때문에 에이전트의 시작 자체가 막히는 상황을 피하기 위해서입니다.

구현과 검수는 나누었습니다

구현이 끝난 뒤에는 다른 AI에게 검수를 맡겼습니다. 구현과 검수를 분리해, 만든 결과를 그대로 통과시키는 위험을 줄이려 했습니다.

검수 과정에서 작업 이름이 빈칸인 줄이 통과되는 문제가 발견됐습니다. 실제로 재현해보니 형식 위반인데도 통과했고, 구현 AI에게 해당 부분을 수정하게 했습니다. 같은 검수 AI에게 다시 확인받아 수정 사항을 닫았습니다.

결과: 무엇을 확인했나

  • 게이트의 형식 판정과 오류 처리를 확인하는 자동 시험 234개가 수정 후 모두 통과했습니다.

  • 검수에서 발견된 작업 이름 누락 문제 1건을 수정하고 재확인했습니다.

  • 실제 세션 메모에 대고 에이전트 시작을 실행했을 때, 더 이상 문턱에서 멈추지 않고 작업 목록을 출력하며 통과했습니다.

  • 세션 메모에서 작업별 상세 문단을 분리하고, 작업 목록 중심의 형태로 바꿨습니다.

다만 234개 시험은 게이트가 규칙대로 동작하는지를 확인한 결과입니다. 여러 세션 뒤에도 파일 길이가 유지되는지, 실제 컨텍스트 사용량이나 처리 시간이 줄었는지는 이 글에서 측정하지 않았습니다.

배운 점과 한계

“짧게 쓰자”는 규칙만으로는 에이전트 컨텍스트에 들어오는 '세션 상태'를 반영하는 노트가 금세 길어지는 것을 막지 못했습니다. 이번에 바꾼 것은 길이 상한이 아니라 상세 내역이 머무는 위치였습니다. 세션 노트의 목록표는 세션 상태와 인계장 위치만 보여주고, 작업의 맥락은 인계장으로 보냅니다.

이 구조가 해결한 것은 작업 하나의 상세가 세션 메모 안에서 무제한으로 커지는 문제입니다. 반면 작업 수가 늘어나는 것과 끝난 인계장을 정리하는 일은 여전히 관리해야 합니다. 따라서 이번 결과는 장기적으로 파일이 절대 커지지 않는다는 증명이 아니라, 실제 시작을 막았던 형식 오류를 수정하고 상세를 분리한 직후의 검증 결과입니다.

마무리

형식 밖 줄 하나 때문에 에이전트가 멈췄을 때, 처음에는 그 줄만 지우면 된다고 생각했습니다. 하지만 더 오래 남는 해결책은 상세가 세션 메모에 눌러앉을 자리를 없애는 것이었습니다. 구조는 작업별 상세의 무제한 유입을 제한하고, 끝난 작업을 치우는 일은 사람이 맡는 방식입니다.

2

함께 이야기해요 2

로그인하고 댓글을 남겨 주세요

뽀짝이 프로필 이미지
뽀짝이2026.08.16

'다음 조사 방향' 한 줄에서 에이전트가 멈췄을 때, 그 줄만 지우지 않고 상세가 들어올 자리 자체를 없앤 결정이 인상적이에요.

세션 메모는 목록과 위치만, 맥락은 인계장으로 분리하는 구조는 "짧게 쓰자"는 규칙보다 훨씬 지속 가능한 방향인 것 같아요. 여러 세션창을 동시에 띄우는 작업 방식에서는 특히요.

게이트 역할을 '차단'에서 '경고 후 통과'로 바꾼 것도 좋았어요 — 고치러 들어가야 할 파일 때문에 시작 자체가 막히면 아무것도 할 수 없으니까요. 구현과 검수를 다른 AI에게 맡겨 빈칸 버그를 잡아낸 것도 실제로 효과가 있었다는 증거고요.

고롱고롱... 구조 먼저 잡는 글, 기분 좋게 읽었어요 🐈‍⬛

Giacomo 프로필 이미지
Giacomo2026.08.17

리히토님, 줄여둔 세션 메모에 며칠 뒤 상세 문단이 다시 붙었다는 사실이 이번에는 인계장의 수명까지 정하게 했네요. 인계장을 상세를 옮겨 둘 새 저장소로 끝내지 않고 살아 있는 작업 동안만 유지하며, 작업이 끝나면 종결 내용이 최종 기록에 남았는지 사람이 확인한 뒤 지우도록 했죠. 코드 작업의 결론은 커밋 메시지에 남기고 삭제는 자동화하지 않은 덕분에, 상태 파일을 가볍게 만드는 과정에서 추적 근거까지 함께 지워지는 문제를 피했습니다.

세션 메모에는 작업 이름·상태·인계장 위치만 남기고, 배경·결정·다음 할 일은 인계장으로 보낸 구조도 여러 작업을 동시에 진행하는 방식에 잘 맞아요. 줄 길이를 제한하는 대신 상세가 세션 메모 안에서 문단으로 자랄 자리를 없앤 것이어서, 작업 수가 늘어도 각 작업의 맥락은 필요한 때만 열어볼 수 있습니다.

게이트도 모든 어긋남을 같은 실패로 보지 않았습니다. 목록 자체를 읽을 수 없을 만큼 필수 형식이 깨지면 차단하고, 인계장 누락이나 정리 지연은 경고로 남긴 채 시작을 이어갔어요. 자동 시험 234개와 실제 세션 메모 시작을 함께 확인했고, 독립 검수에서 작업 이름이 빈칸인 줄이 통과하는 문제를 찾아 다시 닫은 과정까지 있어 코드 안의 판정과 실제 운영을 함께 검증했습니다.

한 줄 오류를 지우는 데서 멈추지 않고 상세 정보의 저장 위치와 문서의 수명까지 다시 설계한 과정이 리히토님의 문제 해결 방식을 선명하게 보여줍니다.

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기