모든 작업을 자동커밋하려다, 체크포인트와 Git 커밋의 역할을 나눠 설계했습니다

한 줄 요약
파일을 되돌리기 위한 촘촘한 저장은 Hermes 체크포인트에 맡기고, 사람이 읽을 프로젝트 이력은 검증된 작업 단위의 Git 커밋으로 남기도록 역할을 분리한 배포 전 운영안으로 정리했습니다.

검증 상태
현재 설정·CLI 점검과 격리 Git canary만 PASS입니다. 실제 사용자 저장소의 자동커밋 hook 설치, Hermes checkpoint 복원, checkpoint prune·용량 cap 작동 시험, 원격 push·PR 자동화는 모두 NOT RUN입니다. 외부 launchd·cron·IDE 자동화는 NOT INSPECTED입니다.

처음에는 “모든 세션이 알아서 커밋하면 편하지 않을까?”라고 생각했습니다

AI 에이전트와 여러 프로젝트를 오가다 보면 이런 걱정이 생깁니다.

• 세션이 갑자기 끊기면 방금 수정한 파일은 어떻게 복구할까?

• 다음 세션이 이전 작업을 제대로 이어받을 수 있을까?

• 프로젝트가 많아져도 빠뜨리지 않고 변경 이력을 남길 수 있을까?

그래서 처음 떠올린 해법은 간단했습니다.

어떤 프로젝트에서 어떤 세션으로 작업하든 자동으로 git commit하게 만들자.

그런데 바로 다음 질문에서 문제가 드러났습니다.

커밋이 너무 많이 쌓이면 오히려 불편하지 않을까?

결론부터 말하면 그렇습니다. 매 수정이나 매 대화 턴을 정식 커밋으로 남기면 복구 지점은 많아지지만, 프로젝트 역사는 빠르게 읽기 어려워집니다.

이번 사례에서는 “더 많이 저장하는 방법”보다 서로 다른 저장 수단에 서로 다른 책임을 맡기는 방법을 배포 전 운영안으로 설계했습니다.

먼저 구분한 것: Git 커밋과 Hermes 체크포인트는 목적이 다릅니다

Git 커밋은 프로젝트의 공식 이력입니다. 다만 파일 내용, commit object, branch reference는 서로 다른 층에 저장됩니다.

작업 파일
  ↓ git add
blob object + 스테이징 영역(index)
  ↓ git commit
tree object + commit object
  ↓
브랜치 reference가 새 commit을 가리킴

git add는 파일 내용을 blob object로 기록하고 index에 다음 스냅샷을 준비합니다. git commit은 그 스냅샷의 tree를 가리키는 commit object를 만듭니다.

commit object 자체에는 다음 정보가 들어갑니다.

• 최상위 tree object의 hash

• 부모 commit hash

• 작성자·커미터와 각각의 시각

• 커밋 메시지

파일 내용은 별도의 blob object, 디렉터리 구조는 tree object에 저장됩니다. 브랜치는 논리적으로 refs/heads/<branch>가 새 commit을 가리키는 구조이며, 실제 저장은 loose ref 파일 또는 packed-refs일 수 있습니다.

즉, Git 커밋은 “언제든 되돌릴 수 있는 저장점”인 동시에 다른 사람이 읽고 이해해야 하는 프로젝트 기록입니다.

반면 Hermes 체크포인트는 에이전트가 파일을 바꾸기 직전에 만드는 복구용 스냅샷입니다. 공식 문서에 따르면 체크포인트는 하나의 공유 shadow Git 저장소를 사용하며, 실제 프로젝트의 .git은 건드리지 않습니다.

그림 1. 실제 Hermes 공식 문서 캡처. 복구용 checkpoint store와 프로젝트의 실제 .git이 분리돼 있다.

이를 표로 정리하면 차이가 더 선명합니다.

여기서 운영 원칙이 나왔습니다.

체크포인트는 촘촘하게, 커밋은 의미 있게.

말로만 설계하지 않고 현재 상태부터 확인했습니다

2026년 8월 10일 18:39 KST 기준으로 Hermes 설정과 CLI 상태를 직접 점검했습니다.

확인한 범위는 다음과 같습니다.

• 체크포인트 설정의 선택된 키

• hermes checkpoints status

• hermes hooks list

• 활성화된 plugin 이름

• 사용자 hook/plugin 코드 안의 Git 자동커밋 관련 패턴

관찰 결과는 예상보다 흥미로웠습니다.

1. 체크포인트는 이미 켜져 있었습니다.

2. 프로젝트 자동커밋은 점검한 Hermes hook/plugin 경로에 구성돼 있지 않았습니다.

3. checkpoint base 총합은 당시 4.1GB, 프로젝트 루트 497개였습니다. 세부 표시는 store/ 4.0GB와 legacy-* 107.9MB였습니다.

4. 설정에는 max_total_size_mb: 500과 auto_prune: false가 함께 기록돼 있었습니다.

그림 2. 2026년 8월 10일 18:39 KST의 데이터 파생 증거 카드. checkpoint base 총 4.1GB는 shared store 4.0GB와 legacy 107.9MB를 합친 반올림 값이다. 점검한 Hermes hook/plugin 경로에는 자동커밋이 구성돼 있지 않았고, 외부 launchd·cron·IDE 자동화 및 용량 cap 작동 원인은 검사하지 않았다.

여기서 중요한 운영 점검 항목도 발견했습니다.

공식 문서는 auto_prune: false이면 수동으로 hermes checkpoints prune을 실행할 때까지 저장소가 계속 커질 수 있다고 설명합니다. 다만 설정값 500MB와 관찰된 shared store 4.0GB의 차이만으로 원인을 단정할 수는 없습니다. 기존 누적분, cap 적용 시점, 실제 prune 실행 여부를 구분하려면 별도의 작동 시험이 필요하며, 이번 사례에서는 그 시험을 실행하지 않았습니다.

ALT

WordPress 페이지의 스크린샷

그림 3. 실제 Hermes 공식 문서 캡처. 체크포인트를 넓게 사용할수록 저장 정책도 함께 설계해야 한다.

자동커밋만 고민하다가, 오히려 이미 작동 중인 checkpoint base의 유지관리 상태를 별도로 검증해야 한다는 과제가 먼저 보인 셈입니다.

배포 전 운영 설계안: 세 단계로 나눴습니다

1단계 — 파일을 바꾸기 직전에는 체크포인트

Hermes가 write_file, patch 또는 파괴적 터미널 명령을 실행하기 직전에 체크포인트를 만듭니다.

이 단계의 목적은 하나입니다.

방금 에이전트가 만든 변경을 빠르게 되돌릴 수 있게 한다.

체크포인트는 복구 수단이므로 커밋 메시지를 아름답게 만들 필요가 없습니다. 대신 다음 운영 조건이 필요합니다.

• 저장소 크기와 프로젝트 수를 주기적으로 확인

• auto_prune 또는 수동 prune 정책 결정

• 복구 전에 /rollback diff <N>으로 변경 범위 확인

• 체크포인트가 실제 프로젝트 Git 이력을 대신한다고 오해하지 않기

2단계 — 긴 작업 중간에는 세션 전용 worktree와 WIP 커밋

한 세션이 길거나 여러 에이전트가 같은 저장소에서 병렬로 작업한다면 세션별 worktree와 브랜치를 사용합니다. 아래 hermes/<session-id>는 이 사례에서 제안한 이름 규칙이며, Hermes의 내장 hermes -w는 기본적으로 hermes/hermes-<hash> 형태의 브랜치를 만듭니다.

main
└── hermes/<session-id>  ← 세션 전용 worktree
    ├── wip(agent): 단계 1
    ├── wip(agent): 단계 2
    └── wip(agent): 단계 3

WIP 커밋은 다음 조건을 만족할 때만 만듭니다.

• Git 저장소 안에서 작업 중일 것

• 에이전트가 이번 작업에서 바꾼 경로만 stage할 것

• 기존에 사용자가 수정해 둔 파일을 섞지 않을 것

• 충돌, 중단, 실패 상태가 아닐 것

• 비밀정보나 대용량 생성물이 포함되지 않을 것

• 보호 브랜치에 직접 커밋하지 않을 것

중요한 점은 매 대화 턴마다 무조건 커밋하지 않는 것입니다. “논리적으로 되돌릴 가치가 있는 중간 단계”만 WIP로 남깁니다.

3단계 — 작업이 검증되면 의미 있는 커밋 하나로 정리

테스트와 검토가 끝나면 WIP 여러 개를 main에 그대로 쏟아붓지 않습니다.

검증 성공
  ↓
git merge --squash hermes/<session-id>
  ↓
feat: 세션 이어받기와 복구 정책을 분리한다

원격 push와 PR 생성은 별도 단계로 둡니다. 자동저장과 외부 공유를 한 번에 묶으면, 잘못된 변경까지 원격 저장소로 전송될 수 있기 때문입니다.

실제로 worktree와 squash가 이력을 정리하는지 격리 저장소에서 시험했습니다

운영안을 실제 프로젝트에 바로 설치하지 않고, 별도의 로컬 canary 저장소를 만들었습니다.

실행한 순서는 다음과 같습니다.

1. main에 baseline 커밋 1개 생성

2. hermes/demo-session worktree 생성

3. 세션 브랜치에 WIP 커밋 3개 생성

4. main에서 git merge --squash 실행

5. 의미 있는 최종 커밋 1개 생성

6. 양쪽 작업 트리의 clean 상태와 원격 저장소 부재 확인

결과는 다음과 같았습니다.

• 세션 브랜치: baseline 1개 + WIP 3개

• main: baseline 1개 + 최종 커밋 1개

• main의 WIP 제목: 0개

• 격리 canary 검사: 8/8 PASS — WIP 수·양쪽 커밋 수·main의 WIP 제목 0개·양쪽 clean 상태·최종 tree 일치·remote 없음·worktree 정리 확인

• 사용자 저장소 변경: 없음

• 원격 push: 없음

• 자동커밋 hook 설치: 없음

ALT

wp 메일, 메일, smtp, smtp, smtp, smtp

그림 4. 실행 영수증 기반 데이터 파생 카드. 격리 canary에서 세션 브랜치의 WIP 3개를 main의 의미 있는 커밋 1개로 정리하는 Git 동작을 확인했다. 실제 production 자동커밋 hook, checkpoint 복원, 원격 push·PR 자동화는 모두 실행하지 않았다.

이 시험으로 확인한 것은 “자동커밋 시스템 전체가 완성됐다”는 사실이 아닙니다. 확인한 범위는 worktree에서 만든 WIP 이력을 squash로 정리할 수 있다는 Git 동작입니다.

자동커밋을 실제로 붙일 때 필요한 안전장치

실제 Hermes 자동커밋 기능을 구현한다면 단순히 아래 명령을 모든 세션 끝에 실행해서는 안 됩니다.

git add -A
git commit -m "auto commit"

이 방식은 에이전트가 건드리지 않은 기존 변경까지 함께 커밋할 수 있습니다.

보다 안전한 구조는 다음과 같습니다.

세션 시작
  ├─ 현재 branch·HEAD 기록
  ├─ 기존 dirty 파일 목록과 hash 기록
  └─ 보호 브랜치 여부 확인

파일 변경
  ├─ Hermes checkpoint 생성
  └─ 이번 세션에서 바뀐 경로만 추적

세션 작업 성공
  ├─ 실패·중단·충돌 여부 검사
  ├─ secret·대용량 파일·.gitignore 검사
  ├─ 허용된 경로만 stage
  └─ 세션 브랜치에 WIP commit

작업 검증 완료
  ├─ 테스트·lint·문서 링크 검사
  ├─ squash
  └─ 의미 있는 최종 commit

외부 공유
  └─ 명시적 승인 뒤 push 또는 PR

특히 다음 조건에서는 자동커밋을 건너뛰어야 합니다.

• Git 저장소가 아닌 디렉터리

• merge conflict가 남아 있는 상태

• detached HEAD

• 사용자가 이미 수정 중이던 파일과 경로가 겹친 상태

• 테스트 또는 검증 실패

• 세션 중단·타임아웃

• 비밀정보 후보 파일 발견

• main, master, 배포 브랜치 등 보호 대상에 직접 기록하려는 상태

처음 구상과 배포 전 설계안의 차이

처음 구상

모든 수정
→ 자동 git commit
→ 커밋 수가 많을수록 안전

검증 후 설계안

모든 위험한 파일 변경 전
→ Hermes checkpoint

긴 세션의 의미 있는 중간 단계
→ 세션 worktree의 WIP commit

테스트·검토가 끝난 논리적 작업
→ squash 후 semantic commit

외부 공유가 필요할 때
→ 승인 후 push/PR

목표는 저장 횟수를 줄이는 것이 아니라, 복구 기록과 공식 기록의 통로를 분리하는 것입니다.

이번 사례에서 얻은 교훈

1. 자동저장과 버전 관리는 같은 문제가 아닙니다

자동저장은 “잃어버리지 않는 것”이 목표입니다. 버전 관리는 “왜 바뀌었는지 설명하는 것”까지 포함합니다.

2. 커밋이 많다고 반드시 안전한 것은 아닙니다

작고 원자적이며 검증 가능한 커밋은 오히려 리뷰와 git bisect에 도움이 됩니다. 문제가 되는 것은 빌드가 깨졌거나 검증되지 않은 WIP 커밋을 main의 공식 이력에 그대로 섞는 경우입니다.

3. 복구 수단에도 보존 정책이 필요합니다

공식 문서상 auto_prune을 끄면 수동 정리 전까지 저장소가 커질 수 있습니다. 이번 점검에서는 설정 기준 500MB와 shared store 관찰값 4.0GB가 달랐지만, 그 차이의 원인은 검증하지 않았습니다. prune과 용량 cap이 언제 작동하는지 별도 시험해야 합니다.

4. 병렬 작업의 핵심은 자동커밋보다 격리입니다

같은 working tree를 여러 세션이 공유하면 어떤 변경이 누구의 것인지 구분하기 어렵습니다. 세션별 worktree와 브랜치가 먼저이고, 자동커밋은 그 위에 올라가는 기능입니다.

5. 자동 push는 자동 commit과 분리해야 합니다

로컬 복구와 원격 공개는 위험 수준이 다릅니다. 커밋은 자동화할 수 있어도 push는 명시적으로 승인하는 편이 안전합니다.

바로 적용할 수 있는 체크리스트

체크포인트

• 체크포인트가 필요한 프로필에서만 활성화했는가?

• hermes checkpoints status로 실제 저장량을 확인했는가?

• auto_prune, retention, 크기 기준을 함께 정했는가?

• 복원 전 /rollback diff를 확인하는가?

Git 커밋

• 한 커밋이 한 가지 논리적 변경을 설명하는가?

• 에이전트가 바꾸지 않은 기존 파일을 stage하지 않는가?

• 테스트·lint·문서 링크 검사를 통과했는가?

• 비밀정보와 생성물을 제외했는가?

병렬 세션

• 세션별 worktree와 브랜치를 사용하는가?

• WIP 커밋은 세션 브랜치에만 남기는가?

• main에 합칠 때 squash 또는 정리된 rebase를 사용하는가?

• 자동 push를 분리했는가?

검증 경계

이 글은 검증 완료 범위와 미실행 범위를 분리해 기록했습니다.

따라서 이 사례의 정확한 상태는 “현재 상태를 검증하고, 격리 canary로 운영 구조를 확인한 배포 전 설계”입니다.

마무리

처음에는 “모든 세션이 자동으로 커밋하면 가장 안전하겠다”고 생각했습니다.

점검하고 시험해 보니 더 나은 답은 조금 달랐습니다.

파일 변경 전에는 체크포인트로 복구 가능성을 확보하고,
작업이 설명 가능한 단위로 끝났을 때만 Git 커밋을 남긴다.

그리고 여러 세션이 동시에 움직인다면 worktree로 격리하고, WIP 이력은 마지막에 squash합니다.

이 구조가 목표하는 것은 저장은 촘촘하게 유지하면서도 프로젝트 역사는 읽을 수 있게 만드는 것입니다. 실제 production 자동커밋 hook, checkpoint 복원, 원격 push·PR 자동화는 모두 실행하지 않았고, 외부 launchd·cron·IDE 자동화도 검사하지 않았습니다. 사용자 저장소에 적용하기 전에는 자동커밋 hook, 복원, 실패·중단 경계를 별도 canary로 검증해야 합니다.

참고한 공식 문서

• Hermes Agent — Checkpoints and /rollback
  https://hermes-agent.nousresearch.com/docs/user-guide/checkpoints-and-rollback

• Hermes Agent — Git Worktrees
  https://hermes-agent.nousresearch.com/docs/user-guide/git-worktrees

• Hermes Agent — Hooks
  https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks

• Git — Git Objects
  https://git-scm.com/book/en/v2/Git-Internals-Git-Objects

• Git — Git References
  https://git-scm.com/book/en/v2/Git-Internals-Git-References

• Git — git commit documentation
  https://git-scm.com/docs/git-commit