[에이전트] 12. 회고 : 8일 45커밋이 남긴 것 — 제약이 설계를 만든다

(폐쇄망 사내 에이전트 ⑫) 회고

8월 1일 첫 커밋부터 8월 16일 문서 커밋까지, 45커밋 · TypeScript 565파일 · 테스트 2,289개 통과가 이 프로젝트의 물리적 크기다. 마지막 편은 커밋 날짜를 다시 펼쳐놓고, 이 8일이 남긴 것을 정리한다.

리듬 — 몰아치고, 비우고, 다시 몰아친다

08-01  ██ 2            — 시작 (Java)
08-02  ███████████ 11  — TS 전면 재작성, 인프로세스 전환
08-03  ████████████ 12 — 컨텍스트 사투, revert
(12일 공백)
08-15  ██████████████████ 18 — 하드닝 폭발
08-16  ██ 2            — 승인 규칙·문서 정리

이 그래프에서 배운 게 둘이다. 하나, 초반 사흘의 밀도가 프로젝트의 골격(분리 설계·승인 게이트·인프로세스)을 전부 세웠다 — 골격은 몰아칠 때 세워진다. 둘, 12일의 공백이 죽은 시간이 아니었다. 그 사이 실사용이 쌓였고, 8월 15일의 18커밋은 전부 그 실사용이 잡아낸 것들(구형 CPU 사고, 지연 로딩, 압축 판정 보정)이다. 만들고 → 실제로 쓰고 → 그 로그로 다시 만드는 사이클이 커밋 밀도에 그대로 찍혀 있다.

이 레포에서 확립된 작업 관행

• 실기 검증까지가 구현이다 — 기능을 넣으면 실모델로 돌려 감사 DB·로그에서 증거를 잡은 뒤 커밋한다. 45커밋 대부분에 ‘실측’이라는 단어와 수치가 있다.
• 커밋 메시지에 무엇을·왜·근거를 적는다 — 이 시리즈가 커밋만으로 쓰일 수 있었던 이유. 미래의 나에게 보내는 문서다.
• 실패를 지우지 않는다 — 하루 만의 revert(9편)도 ‘무엇이 왜 틀렸는지’와 함께 남겼다. 문서도 지우는 대신 낡음 배너를 단다.
• 안전 표면은 동결한다 — tools/ 수정은 건별 해제(5편), 감사 상태 구분은 불가침(6편), 정책 DENY는 무엇으로도 못 뒤집는다(7편).
• 캐시 앞부분은 성역이다 — 프롬프트 앞부분을 매 턴 바꾸는 설계 금지. 실측 36배가 걸려 있다(4·9편).

클로드 코드에게 배운 것들

이 프로젝트는 클로드 코드의 폐쇄망 번역이기도 하다. 권한 모드(6편), 승인 규칙(7편), 도구 지연 로딩(8편), “상시로 줄이지 않는” 압축과 잘린 원문의 파일 보관(9편) — 전부 클로드 코드가 먼저 밟은 길을 4B와 폐쇄망이라는 제약에 맞게 옮긴 것이다. 다만 옮기며 확인한 게 있다. 좋은 에이전트 설계는 모델 크기와 무관하게 성립한다는 것. 오히려 모델이 작을수록 그 설계가 성능의 더 큰 몫을 차지했다.

숫자로 남은 것, 숫자 밖에 남은 것

실측	값
웜 캐시 prefill	20,769ms → 567ms (36.6배)
대화 컨텍스트 여유	28% → 73% (지연 로딩)
파일 158개 이동	승인 158회 → 1회
세션당 메모리	388 MiB (실측으로 기본값 재설정)
테스트	1,385 → 2,289 pass (8일간)

숫자 밖에 남은 건 확신이다. 폐쇄망이라는 제약은 처음엔 벽이었지만, 지나고 보니 설계를 강제로 좋게 만드는 조건이었다. 반출이 안 되니 감사가 생겼고, 모델이 작으니 런타임이 정직해졌고, 인터넷이 없으니 배포가 검증됐다. 제약 없는 환경이었으면 대충 넘어갔을 것들이다.

커밋 유형으로 본 8일

유형	수	비고
feat	18	절반이 8/15 하드닝 날
fix	7	전부 실사용·실측이 잡음
docs	3	재대조 ·정본화
revert	1	방향 수정 — 지우지 않고 남김
무접두(초기)	15	규약 정착 전 Java 시절

fix 7건의 공통점이 재밌다 — 단 하나도 코드 리뷰에서 나오지 않았다. 전부 실사용 로그(무한 목록 조회), 실기기(구형 CPU), 실모델 완주 테스트(압축 판정)가 잡았다. 이 규모의 1인 프로젝트에서 리뷰어는 결국 현실이고, 현실을 자주 만나는 구조(실기 검증 관행)가 리뷰 프로세스를 대신했다.

만약 다시 시작한다면

정직한 회고에는 ‘다르게 할 것’이 있어야 한다. 세 가지다.

1. Java로 시작하지 않는다 — 폐쇄망 배포가 요구사항이면 단일 바이너리 스택을 첫날 골랐어야 했다. 배포 요구를 ‘나중 문제’로 미룬 대가가 하루 반이었다.
2. 컨텍스트 계측을 먼저 만든다 — 도구 정의가 71%를 먹는 걸 2주차에야 쟀다. air doctor의 ‘컨텍스트 예산’ 항목을 첫 주에 만들었다면 지연 로딩이 훨씬 일찍 나왔다.
3. KV 실토큰 로그를 처음부터 남긴다 — 압축 판정 오차 20%는 판정 로그를 신설하고서야 보였다. 보이지 않는 것은 고칠 수 없다.

공통 교훈은 하나로 접힌다 — 계측이 설계보다 먼저다. 8일 중 잘 굴러간 날은 전부 숫자를 먼저 잰 날이었고, 되돌린 결정(9편의 revert)은 재지 않고 커밋한 유일한 날이었다.

✅ 확인

• 커밋 메시지만 읽고 이 시리즈를 재구성할 수 있는가 — 그게 커밋 메시지의 품질 기준이다.
• 프로젝트에 ‘다르게 할 것’ 목록이 있는가 — 없다면 회고가 아니라 자랑이다.
• 실패(revert·오진)가 기록으로 남아 있는가 — 지운 실패는 반복된다.

시리즈는 여기까지다. 로드맵에는 아직 남은 항목이 줄지어 있고(세션 이어가기, 감사 로그 조회, 대량 작업 개선…), 그건 이 물건이 죽지 않고 쓰이고 있다는 뜻이라 나쁘지 않다. 폐쇄망에서 비슷한 걸 만들고 있다면 — 1편부터의 커밋 썰이 지도까지는 아니어도 이정표는 될 것이다. 에이전트 일반론이 궁금하면 컨텍스트 엔지니어링과 MCP 시리즈가 좋은 짝이다.

자주 묻는 질문 (FAQ)

혼자 8일에 이 규모가 가능한가요?

AI 코딩 도구의 도움을 받으며 진행했고, 그래서 더더욱 실기 검증과 감사 기록을 커밋의 전제로 삼았습니다. 생성은 빨라도 검증은 사람이 해야 하고, 그 검증 흔적(실측 수치·테스트 수)이 커밋마다 남아 있는 이유입니다.

폐쇄망 에이전트를 시작한다면 뭐부터 해야 하나요?

모델보다 실행기부터입니다. ① 도구 실행을 정책·승인·감사로 감싸는 구조를 먼저 세우고 ② 작은 모델의 한계를 계측으로 확인하며 런타임이 메우고 ③ 배포·반입 절차를 깨끗한 환경에서 검증하는 순서를 권합니다.