상태 파일 관리의 핵심 요약
지난번에는 에이전트 세션 메모(SESSION_STATE)를 144줄에서 22줄로 줄였습니다. 이번에는 그 원리를 상태 파일 전체로 넓히려 했지만, 실제로 매번 자동으로 읽히는 파일과 필요할 때만 여는 파일을 나눠 보니 관리가 필요한 대상은 STATUS 하나였습니다. 검사기를 구현하는 과정에서 5,000이라는 상한의 단위가 바이트가 아니라 글자 수로 잘못 적용된 사실도 발견했고, 글자 수 기준 2,500자로 다시 정했습니다.
이번에 확인한 것은 상태 파일 자체가 짧아졌다는 결과가 아니라, 초과 파일을 탐지하고 정리를 요구하는 장치가 작동하기 시작했다는 사실입니다.
이런 분께 추천하는 이유
- AI 에이전트에게 매번 현재 상황을 알려주는 상태 파일이 자꾸 길어지는 분
- 오래된 메모가 다음 작업을 헷갈리게 할까 걱정되는 분
- 기준 숫자를 정해놓고 단위까지 확인하지 않은 경험이 있는 분
- 아직 에이전트용 상태 파일을 쓰지 않는 분께는 조금 이른 내용입니다.
상태 파일 관리의 배경
저는 프로젝트마다 폴더를 하나씩 나눠 쓰고, 이를 ‘작업방’이라고 부릅니다. 유튜브 요약 프로젝트의 방, 자료 조사 프로젝트의 방처럼 나뉘어 있고, 방마다 현재 상태를 적는 STATUS 파일이 하나씩 있습니다. 현재 작업방은 6개입니다.
에이전트가 일을 시작할 때 자동으로 읽는 파일은 SESSION_STATE와 STATUS입니다. SESSION_STATE는 지금 어떤 임무를 수행하는지 적은 공통 세션 메모이고, STATUS는 각 작업방의 현재 상태 파일입니다. 반면 BACKLOG의 상세 본문은 필요할 때만 여는 파일입니다.
저는 이를 각각 ‘가방’과 ‘창고’로 구분했습니다.
- 가방: 세션 시작 때마다 자동으로 읽는 파일
- 창고: 필요할 때만 여는 파일
가방이 무거우면 매 세션 읽는 양이 늘어납니다. 오래된 정보가 현재 사실처럼 읽혀 오판할 위험도 생깁니다. 지난 세션에서는 SESSION_STATE를 144줄에서 22줄로 줄였고, 이번에는 STATUS에도 같은 원리를 적용해 보려 했습니다.
상태 파일 최적화 방법
1. 세 파일을 모두 줄이려던 계획을 다시 검토했습니다
처음에는 상태 성격의 파일 세 개에 같은 상한을 걸려고 했습니다. 하지만 검토 과정에서 두 가지 문제가 드러났습니다.
첫째, 상한을 넘으면 일을 시작하지 못하게 막는 방식은 이미 큰 파일을 고치러 들어가는 것 자체를 막을 수 있었습니다. 그래서 최종 구현에서는 상한 초과를 ‘알림’으로 처리하고, 일은 계속하도록 했습니다.
둘째, 가장 큰 파일인 BACKLOG 상세 본문은 매번 자동으로 읽히는 파일이 아니었습니다. 창고가 큰 것은 필요할 때 여는 비용이지, 모든 세션에 반복되는 비용은 아니었습니다.
다시 나눠 보니 당시 판정은 다음과 같았습니다.
파일별 판정
- SESSION_STATE: 자동으로 읽는 파일. 약 4,000바이트. 이미 짧게 유지되고 있어 이번에는 보류했습니다.
- STATUS: 자동으로 읽는 파일. 프로젝트 방마다 약 1,000~26,000바이트. 유지 장치가 없어 관리 대상으로 정했습니다.
- BACKLOG 상세 본문: 필요할 때만 여는 파일. 약 28,000바이트지만 매 세션 반복 비용이 아니므로 급하지 않다고 판단했습니다.
당시 측정값은 바이트 기준이었습니다. STATUS를 다시 확인하니 현 상태만 적힌 다른 방들은 2,700바이트 아래였고, 결정 이력이 쌓인 한 방만 26,000바이트대로 커져 있었습니다. 그래서 계획은 ‘세 파일에 일괄 규칙 적용’에서 ‘STATUS에만 상한과 구조 규칙 적용’으로 좁혀졌습니다.
2. STATUS를 읽는 두 지점에 검사기를 넣었습니다
제가 확인한 환경에서는 STATUS가 읽히는 경로가 두 곳이었습니다.
검사 지점별 동작
- 작업 시작 시: 현재 작업방의 STATUS를 검사합니다. 상한을 넘으면 정리 알림 후 작업을 계속하고, 구조 위반이면 상태 파일 읽기를 거부합니다.
- 하루 한 번 순찰할 때: 모든 작업방의 STATUS를 검사합니다. 상한을 넘은 방을 로그에 기록하고 같은 기준으로 표시합니다.
작업 시작 시 검사기에는 두 가지 규칙을 넣었습니다.
- 본문이 상한을 넘으면 “정리하세요”라는 알림만 띄우고 작업은 계속합니다.
- ‘결정 이력’, ‘히스토리’처럼 과거의 경위를 상태 파일에 계속 쌓는 구조는 거부합니다. 결정의 이유는 결정 기록 문서로, 작업 과정은 일지로 보내는 방식입니다.
역사 정보가 쌓이면 상태 파일이 비대해질 위험이 커지므로, 이 구조에서는 상태 파일에 넣지 않기로 했습니다.
하루 한 번 모든 방을 도는 순찰에는 기존의 ‘오래 활동하지 않은 방’ 점검에 ‘본문 상한을 넘은 방’ 점검을 추가했습니다. 실제 실행 결과 문제의 방이 정리된 것이 아니라, 정리 대상이라는 알림으로 바로 탐지됐습니다.
출력은 다음과 같은 형태였습니다.
상태 파일 본문 크기 위반 1개 — 예산 초과:3. 5,000의 단위를 다시 확인했습니다
출력에는 26,000바이트로 기록된 파일이 14,390자로 표시됐습니다. 구현하던 AI가 확인해 보니 문서에 적힌 26,045라는 값은 글자 수가 아니라 바이트였습니다.
한글이 포함된 문서에서는 저장 용량을 나타내는 바이트 수와 사람이 읽는 글자 수가 달라집니다. 영문·숫자·기호가 섞인 이 파일에서는 바이트 수가 글자 수보다 약 1.8배 컸습니다.
문제는 상한을 정할 때 측정 기준과 검사 기준의 단위가 달랐다는 점입니다. 표본을 바이트로 측정해 5,000이라는 상한을 정했는데, 검사기에는 글자 수 5,000으로 적용했습니다. 한글이 많은 문서일수록 의도보다 느슨한 상한이 된 셈입니다.
그래서 단위를 먼저 정했습니다. 사람에게 보이는 분량과 가깝고, 이 시스템의 다른 상한과도 맞추기 위해 글자 수를 사용하기로 했습니다.
단위별 측정값
- 건강한 방의 최대값: 2,700바이트 / 1,729자
- 문제가 된 방: 26,045바이트 / 14,390자
- 상한: 바이트 기준으로 측정한 5,000을 잘못 적용했다가, 글자 수 기준 2,500자로 다시 정했습니다.
2,500자는 당시 측정된 건강한 파일 1,729자와 문제가 된 파일 14,390자 사 이에서, 건강한 파일은 통과시키고 큰 파일은 걸러내도록 정한 운영 기준입니다. 보편적으로 최적이라는 뜻은 아닙니다.
이번 표본에서는 바이트 기준과 글자 수 기준으로 판정이 뒤집힌 파일이 없었습니다. 하지만 임계값 근처의 파일이 있었다면 단위 착오만으로도 잘못된 판정이 날 수 있었습니다. 이번 결과는 측정 방법이 안전했다는 증거가 아니라, 표본 간격이 넓어 문제가 드러나지 않았던 결과에 가깝습니다.
검사기에는 2,500자면 통과하고 2,501자면 걸리는 경계 테스트도 추가했습니다.
4. 상한이 실제 개선인지 확인할 방법을 남겼습니다
마지막으로 ‘상한을 걸었더니 파일이 상한 아래에 있다’를 성과로 세면, 검사기가 만든 결과를 같은 검사기로 확인하는 데 그칠 수 있다는 문제가 남았습니다. 장치가 작동한다는 증거와, 그 장치가 좋은 개선을 만들었다는 증거는 다릅니다.
그래서 거창한 측정 체계 대신 매일 도는 순찰이 요약 한 줄을 날짜와 함께 로그에 쌓도록 했습니다.
2026-08-16 · 검사한 방 6개 · 크기 위반 1개
이 기록은 당장 개선을 증명하지는 않습니다. 다만 몇 달 뒤 위반 추세를 확인할 자료가 됩니다. 어느 방이 알림을 받고 며칠 만에 정리했는지까지 보려면 상세 알림 기록과 대조해야 하고, 그 작업은 아직 하지 않았습니다.
결과와 배운 점
이번에 실제로 달라진 것은 다음과 같습니다.
- STATUS에 글자 수 상한 2,500자를 적용했습니다.
- 상한 초과는 알림으로, 상태 파일에 결정 이력이나 히스토리를 쌓는 구조 위반은 거부로 구분했습니다.
- 제가 확인한 두 검 사 지점에 같은 상한을 적용했습니다.
- 상태 파일 본문을 ‘자유롭게 작성’하던 규칙을 ‘정해진 예산 안에서 자유롭게 작성’으로 바꿨습니다.
- 하루 한 번 순찰 결과를 날짜별 한 줄 로그로 쌓기 시작했습니다.
비즈니스 프로세스의 흐름도
반대로 아직 확인하지 않은 것도 분명합니다.
- 문제가 된 STATUS 파일 자체를 실제로 줄였는지
- 자동으로 읽는 분량이 줄었는지
- 오래된 정보로 인한 오류가 감소했는지
- 몇 달 동안 위반 수가 줄어드는지
실제 저 글자수 상한이 적절한지.
이번 사례에서 가장 시도하고 배운 점은 두 가지입니다.
첫째, 매번 자동으로 읽는 파일만 먼저 크기를 줄입니다. 필요할 때만 여는 파일까지 무조건 줄이려 하면 관리 비용만 늘고, 정작 반복 비용이 큰 파일을 놓칠 수 있습니다.
둘째, 숫자를 실측에서 뽑았어도 단위를 확인하지 않으면 아직 제대로 잰 것이 아닙니다. 이번에는 바이트로 측정한 값을 글자 수 상한에 적용하는 실수가 구현 단계에서 드러났습니다. 특히 한글처럼 바이트 수와 글자 수가 크게 달라질 수 있는 환경에서는 숫자와 단위를 한 묶음으로 기록해야 합니다.
또 하나의 운영 원칙도 남았습니다. 상태나 라벨을 새로 만들 때는 실제로 계속 갱신되는지 확인할 장치를 함께 만들어야 합니다. 유지되지 않는 라벨은 오히려 낡은 정보를 현재 사실처럼 믿게 만들 수 있기 때문입니다. 이 원칙을 다시 확인하는 데에는 이전 글에 달린 피드백도 도움이 됐습니다.
