Ledger and Snapshots: The Debt AI Owes and the Regret Medicine Left for You

CodeSmith의 원본 버전: v0.5.0 (커밋 3a74c82f). 모든 경로는 리포지토리 루트를 기준으로 하며, 줄 번호는 이 버전을 참조합니다.
예상 독자층: AI가 리팩토링한 모듈을 물려받았거나, 밤중에 롤백하고 싶었지만 어느 단계로 되돌릴지 알 수 없는 사용자.

AI 코딩 도구를 사용하는 모든 사용자가 본능적으로 아는 두 순간으로 시작합니다.

첫 번째 순간: 3주 후, AI가 리팩토링한 모듈을 열어봅니다. 그 안에는

AI 에이전트들은 작업을 수행한 후 종종 눈에 보이지 않는 '슬롭(slop)'을 남깁니다. 여기에는 호환성 심(compatibility shims), 마이그레이션되지 않은 호출자(unmigrated callers), 중복된 개념, 명명 드리프트(naming drift), 오래된 문서/테스트(stale docs/tests), 의심되는 데드 코드(suspected dead code), 그리고 도구 격차(tool gaps) 등이 포함됩니다.

슬롭 레저(Slop Ledger)는 이러한 잔여물을 가시적이고 쿼리 가능하게 만들어 다음 에이전트(또는 인간)가 이를 재발견하거나, 증폭시키거나, 의도된 아키텍처로 오해하는 것을 방지합니다.

마지막 부정사구에 주목하세요: 의도된 아키텍처로 오해한다(mistake it for intended architecture). 즉, 고의적인 것이라고 착각하는 것입니다. 이것이 첫 번째 순간의 질병의 근원입니다. AI가 남긴 잔여물은 서명(signature)이나 출처(provenance), 회계 장부(bookkeeping)를 가지고 있지 않기 때문에, 다음 지능체—인간이든 기계든—는 '이것은 설계로 간주된다'와 '이것은 지난번 급하게 처리한 작업의 쓰레기물이다'를 구분할 방법이 없습니다. 그리하여 그 쓰레기가 상속되고, 증폭되며, 결국 화석화됩니다.

'슬롭(slop)'이라는 단어는 의미상으로도 적절하고 정확한 선택입니다. 업계에서 사용하는 전문 용어는 '부채(debt)'인데, 이는 이자나 상환 일정이 있다는 금융적 은유입니다. 하지만 AI가 남기는 것들은 종종 '부채'로조차 분류되지 않습니다. 아무도 그것을 갚으려 하지 않으며, 때로는 존재 자체를 모르는 경우도 있습니다. 이것은 슬롭—문자 그대로 조립 라인의 침전물(swill)이라는 뜻입니다—이며, 유일한 진짜 문제는 아무도 이를 청소하지 않는다는 것입니다.

레저의 골격 (The Skeleton of the Ledger)

레저는 JSON 파일(~/.codesmith/slop_ledger.json)이며, 각 기록은 SlopEntry (slop_ledger.rs:179-209)입니다. 이 항목에는 분류 버킷(classification bucket), 심각도(severity), 신뢰도(confidence), 소유자(owner)(사람, 팀 또는 `

이 버킷들 중 세 가지는 그 자체로 충분히 의미가 있습니다. SuspectedDeadCode — 'suspected'라는 단어에 주목하세요. 독립적인 신뢰도(confidence) 필드를 사용하는 것과 관련하여, 모델이 판단한 '아무도 이 코드를 사용하지 않는다'는 것은 종종 틀리기 때문에 항목은 그 불확실성을 함께 지니고 있어야 합니다; 이것이 '죽은 코드 삭제'와 같은 고위험 정리 작업에 할당된 브레이크입니다. ToolGaps — 에이전트(Agent)가 작업을 수행하던 중

다음 지능체(인간이든 기계든)는 당신이 이미 배운 것을 다시 발견할 필요가 없어야 합니다.

Slop Ledger는 이 조항을 회계 장부 형태로 구현한 것입니다. 이는 '다음 지능체가 재발견해서는 안 될 것'이라는 개념을 구전 전통에서 쿼리 가능한 데이터 구조로 바꿉니다. 공정하게 말하자면, 헌법 자체가 매 턴마다 원장(ledger) 항목 생성을 강제하지는 않습니다 (이는 명령이 아닌 도구의 표면적인 기능입니다). 하지만 '다음 지능체를 위해 남겨진 장부'와 '다음 지능체를 위한 깔끔한 작업 공간'은 명백히 같은 세계관을 두 번 구현한 것입니다.

2. side-git 스냅샷: 매 턴마다의 후회 치료제

두 번째 메커니즘은 순간 두 가지를 다룹니다. 모듈 문서를 열어보면 (crates/agent-runtime/src/snapshot/mod.rs:1-13):

매 턴 엔진은 사용자의 작업 공간에 대한 pre-turn:<seq> 스냅샷을 ~/.codesmith/snapshots/<project_hash>/<worktree_hash>/.git의 side git 저장소로 생성하고, 턴이 끝나면 일치하는 post-turn:<seq> 스냅샷을 생성합니다. 사용자는 /restore N (슬래시 명령어)를 통해 되돌릴 수 있으며, 모델이 '방금 한 편집 취소' 의도를 인식하면 revert_turn 도구를 사용합니다.

롤백의 운영 비용은 얼마나 낮을까요? 당신은 심지어 명령어를 기억할 필요조차 없습니다 — 에이전트에게

1. 사용자의 .git 디렉터리는 절대 건드리지 않습니다. 모든 git 호출은 --git-dir과 --work-tree를 한 쌍으로 설정하며 — 문서에서는 이 '단일 불변성(single invariant)'이 스냅샷과 사용자 레포지토리를 완전히 독립적으로 유지하는 핵심이라고 강조합니다. 사용자의 브랜치, 스테이징 영역, 리프로그: 스냅샷 시스템은 그 어떤 것도 건드리지 않습니다.
2. git을 사용하지 않는 워크스페이스도 스냅샷을 얻습니다. 스냅샷은 git 레포지토리만을 위한 특권이 아닙니다.
3. git 자체의 중복 제거(deduplication) 기능이 디스크를 제어합니다. 콘텐츠 주소 지정 저장소(Content-addressed storage)는 '100 MB 워크스페이스 × 12 턴' 시나리오를 10~30배 줄여줍니다.

엔지니어링 상세 정보의 밀도가 바로 이 '단순 기능(plain feature)'이 가진 클래스를 보여줍니다: 기본적으로 7일간 보존되며 (세션 시작 시 정리됨), 사이드 레포지토리에서 gc.auto = 0으로 설정되어 — 배경에서 gc가 갑자기 중간에 작동하는 것을 방지합니다 — 그 후 명시적인 git gc --prune=now를 실행하여 정리하고; 중단된 패킹 작업(pack operations)이 남긴 tmp_pack_* 임시 파일에는 전용 시작 스윕(startup sweep)이 적용됩니다; 워크스페이스당 최대 50개의 스냅샷을 유지하며, 제한 초과 시 가장 오래된 것이 먼저 삭제됩니다 (snapshot/mod.rs:44-46, #1112). 이 모든 작은 결정 뒤에는 실제 충돌 방지(crash) 메커니즘이 숨어 있습니다.

실패 모델: 게이트가 아닌 안전망

하지만 이 모듈에 가장 개성을 부여하는 것은 바로 그 실패 모델(snapshot/mod.rs:29-37)입니다:

턴 전후 스냅샷 호출은 치명적이지 않습니다(non-fatal). git이 없거나, 디스크가 가득 찼거나, 워크스페이스가 읽기 전용 파일 시스템에 있는 경우에도 턴은 진행되며 엔진은 경고를 기록합니다. 스냅샷은 정확성 게이트(correctness gate)가 아니라 안전망입니다.

이 문장을 Article 4의 용량 제어기(capacity controller) 옆에 배치하면 일관된 질서감을 볼 수 있습니다. 즉, 용량 제어기는 역사를 재작성하고 캐시를 손상시키므로 아무리 정교하게 만들어져도 꺼진 상태로 유지되어야 합니다. 반면 스냅샷 시스템은 실패할 경우 단순히 존재하지 않게 됩니다. 사용자의 길을 막기보다는 아예 없는 것이 낫습니다. 서로 반대 방향을 가리키는 두 가지 트레이드오프(trade-off)가 있지만, 원칙은 하나입니다. 보조 메커니즘이 장애물이 될 수는 없다는 것입니다. 하우징(harness)에서 모든 구성 요소는 자신이 어떤 종류의 시민인지 정확히 알아야 합니다. 메인 루프(main loop)는 헌법적 보호를 받는 일급 시민이며, 나머지는 모두 봉사하기 위해 존재하는 것들입니다.

pre/post 더블 스냅샷의 계산 (The Calculus of the pre/post Double Snapshot)

왜 한 번이 아니라 트ิร์น당 두 개의 스냅샷이 필요한가요? pre-turn은 보험이며, post-turn은 증거입니다. 무언가 잘못되었을 때 돌아갈 방법이 두 가지 있습니다. 특정 트ิร์น 전으로 (그 트ิร์널 발생하지 않은 것으로 취급) 되돌아가거나, 후로 (그 트ิร์널 유지하고 그 이후의 트ิร์널들을 되돌리는 것) 갈 수 있습니다. 단일 스냅샷은

지금까지의 불신 목록은 세 가지 항목으로 구성되어 있습니다. 출력에 대한 불신(Article 1, 위조된 호출 제거), 코드에 대한 불신(Article 6, 자식 모델 고정), 그리고 정리 과정에 대한 불신(이번 편: 레저와 스냅샷)입니다. Article 1에서는 좋은 하네스가 명확하게 작성된 불신의 목록이라고 말했고, 앞으로 두 가지 항목이 더 남았습니다. 판단에 대한 불신(Article 13, 골키퍼처럼 작성된 비즈니스 규칙)과 주장(Article 15, 조정하기 위해 '모든 테스트가 녹색'을 재현하는 것)입니다. 이 목록을 마지막 페이지로 넘기면 오직 하나의 질문만 남습니다.

이 시스템에서 당신을 신뢰하는 것은 있습니까?

네. 헌법 제3조는 '사용자가 세션의 주권자'라고 말합니다. 전체 커스터마이징 시스템은 그 신뢰가 건설되는 현장이며, Article 2는 이미 그것을 한 번 분해했습니다. 다음 네 편에서는 컨텍스트에 대해 다루며 방향을 바꿉니다. 하네스는 단순히 모델을 제약하는 것이 아니라, 모델의 **시야(field of vision)**까지 통제해야 합니다.