커밋(Commit)이란 무엇인가

코드 한 줄을 잘못 지우고 두 시간을 흘려보낸 적이 있다면 — 커밋의 가치는 설명할 필요가 없어요. 없다면 한 번 겪어보면 다시는 안 잊어요. 본문 §7 원칙 6 "대규모 작업은 체크리스트로 격파하라"에서 "항목 하나 완료하면 체크 표시 후 커밋" 이라고 말한 그 커밋이에요. 짧지만 에이전트 워크플로우의 안전벨트 역할이라, 단독 부록으로 풀어둘게요.

한 줄 요약

커밋은 "지금 이 상태를 저장한다"는 스냅샷이에요.

작업하던 파일들의 변경 내용을 묶어서, 이름(메시지)을 붙여 기록하는 행위예요. 한 번 커밋된 내용은 나중에 언제든 되돌아볼 수 있고, 이전 상태로 복구할 수도 있어요.

비유로 이해하기

게임의 세이브 포인트와 같아요.

게임에서 중요한 지점마다 저장해두면, 실수하거나 다른 시도를 해보고 싶을 때 그 지점으로 돌아올 수 있어요.
커밋도 마찬가지예요. 코드(또는 문서) 작업 중 "여기까지는 확실히 동작한다"는 시점에 커밋해두면, 이후에 무언가 잘못되더라도 이 지점으로 되돌릴 수 있어요.

게임의 세이브와 한 가지 결정적 차이는 — 여러 갈래를 동시에 시도해볼 수 있다는 점이에요. 같은 세이브 포인트에서 출발해 "리팩토링 시도 A" 와 "다른 접근 B" 를 각각 별도 브랜치로 진행하다, 마음에 드는 쪽만 본선에 합치는 방식이 일상적이에요. 게임으로 치면 같은 세이브에서 다섯 개의 평행 우주를 띄워놓고 그중 가장 잘된 결말만 정사로 채택하는 셈이에요.

Git과 커밋의 관계

커밋은 Git이라는 버전 관리 시스템의 핵심 개념이에요. Git은 파일의 변경 이력을 커밋 단위로 쌓아두는 도구예요.

flowchart TD C1["commit 1: 첫 초안 (first draft)"] C2["commit 2: 2장 추가 (add chapter 2)"] C3["commit 3: 오탈자 수정 (fix typo) ← 현재 위치 (current)"] C1 --> C2 --> C3

이 커밋들이 쌓인 공간을 저장소(repository, 줄여서 repo) 라고 해요.

기술적으로는 각 커밋이 그 시점의 모든 파일에 대한 해시 스냅샷 을 가지고 있어요. "이전 커밋 대비 변경분(delta)" 을 저장하는 게 아니라, 커밋마다 전체 트리의 SHA-1 해시를 따로 기록합니다 — 그래서 어느 커밋으로든 즉시 점프할 수 있고, 중간 커밋을 잃어도 다른 커밋이 망가지지 않아요. delta 저장은 디스크 효율을 위한 백엔드 최적화일 뿐, 개념적 모델은 "스냅샷의 연속" 이에요.

로컬 커밋 vs 푸시(Push)

커밋은 기본적으로 내 컴퓨터 안에만 저장돼요.

다른 사람과 공유하거나 GitHub 같은 원격 저장소에 올리려면 푸시(push) 라는 별도 동작이 필요해요.

flowchart LR subgraph Local["내 PC / 로컬 (My PC / local)"] L1["commit 1"] L2["commit 2"] L3["commit 3 (신규 / new)"] L1 --> L2 --> L3 end subgraph Remote["GitHub / 원격 (GitHub / remote)"] R1["commit 1"] R2["commit 2"] R1 --> R2 end Local -->|"푸시 (push)"| Remote

로컬 커밋은 언제든 되돌리거나 수정할 수 있어서 부담이 없어요. 푸시는 공유 공간에 올라가는 것이라 신중하게 합니다.

이 둘의 비대칭성은 시간축으로 보면 더 명확해요.

flowchart LR subgraph Free["편집 영역 / 로컬, 자유롭게 amend / reorder / rebase / drop (editing zone, local, free to amend)"] direction LR T0(("t")) C1(("commit")) C2(("commit")) C3(("commit")) C4(("commit")) C5(("commit")) C6(("commit")) T0 --> C1 --> C2 --> C3 --> C4 --> C5 --> C6 end Push["푸시 (Push)<br/>발행 (publish)<br/>= 되돌릴 수 없는 지점 (point of no return*)"] C6 --> Push Note["* 되돌릴 수 없음 (no return) = 팀 규율 기준.<br/>force-push 로 원격을 다시 쓸 수는 있지만<br/>다른 사람의 clone 을 깨뜨려요."] Push -.-> Note

로컬 커밋 구간은 자유롭게 amend·rebase·drop 으로 다듬을 수 있는 편집 영역 이고, push 이후는 다른 사람의 시계가 동기화되는 발행 영역 이에요. 그래서 좋은 커밋 흐름은 — 작은 커밋을 자주 찍어두고(undo 단위 확보), push 직전에 한 번 정리해서 의미 단위로 묶어 올리는 패턴이에요.

코딩 에이전트에서의 커밋

주요 코딩 에이전트(Claude Code, Codex 등)는 작업이 완료된 시점에 자동으로 커밋을 만들 수 있어요. 본문 §7 원칙 6의 "항목 하나 완료 → 커밋" 워크플로우는 다음을 의미해요:

작업 단위가 명확하게 기록으로 남아요.
무언가 잘못됐을 때 직전 커밋으로 즉시 되돌릴 수 있어요.
세션이 바뀌어도 어디까지 했는지 커밋 이력으로 확인할 수 있어요 — 다음 세션에서 git log 한 줄이면 맥락이 복원됩니다.

자동 커밋의 트리거는 두 갈래예요.

명시 요청: "커밋해줘" / "이 단계까지 커밋해줘" 같이 사용자가 직접 지시하는 경우. 가장 흔하고 안전해요.
체크리스트 완료 신호: 본문 §7 원칙 6 처럼 "체크리스트 항목 N 완료 시 커밋" 을 CLAUDE.md 나 스킬에 박아두면, 항목 종료를 감지해 자동으로 커밋이 찍혀요. 한 흐름의 작업을 N개의 작은 커밋으로 쪼개주는 효과가 있어요.

깜짝 한 가지 — 코딩 에이전트가 사람보다 더 자주 커밋을 권해요. 사람은 보통 하루 1~3회, 어느 정도 완성됐을 때 몰아 찍는 습관이 있지만, 에이전트는 모든 작은 단위(파일 한 개 추가, 함수 한 개 변경)마다 커밋을 제안하는 쪽으로 기울어 있어요. 처음에는 답답해 보일 수 있지만 — 작은 단위 커밋은 LLM 이 검토할 수 있는 안전 그물이에요. 한 커밋의 변경량이 작을수록 사람이든 다른 에이전트든 그 결과물을 빠르게 훑고 합격·반려를 결정할 수 있어요. 에이전트가 자기가 한 일을 되돌릴 줄 안다는 건, 곧 사용자가 자율을 더 길게 줘도 안전하다는 뜻이기도 해요.

세이브 없이 긴 게임을 하다 죽으면 처음부터인 것처럼, 커밋 없이 긴 작업을 하다 실수하면 되돌릴 지점이 없어요.

자동 커밋은 단순한 편의 기능이 아니라 에이전트 신뢰의 기초예요. 되돌릴 수 있어야 자율을 줄 수 있고, 자율이 있어야 에이전트가 한 흐름의 작업을 깊게 진행할 수 있어요. 커밋 단위가 잘게 쪼개져 있으면 — 잘못된 결정 한 번이 전체 작업을 무효화하지 않아요.

세션 인수인계는 커밋 이력 + CONTINUE.md 패턴 두 축으로 설계돼요. 커밋이 "코드의 기록" 이라면 CONTINUE.md는 "의도·다음 단계의 기록" 이에요.

비유의 한계

세이브 포인트 비유는 직관적이지만 — 게임 세이브와 달리 커밋은 자동 저장이 없어요. 작업 중 컴퓨터가 꺼지면 마지막 커밋 이후 작업은 그냥 날아가요. 그래서 "잠깐 점심 먹고 올 건데 아직 커밋할 만큼 정리되지 않았다" 같은 상황을 위해 git stash (임시 보관함) 같은 보조 도구가 따로 있어요. 또 한 가지 — 게임 세이브는 "시점 이동" 에 가깝지만, 커밋은 "이력 보존" 에 가까워요. 직전 커밋으로 돌아간다고 해서 그 사이에 만든 다음 커밋들이 사라지는 게 아니라, 내가 그 옛 시점을 가리키는 새 분기를 하나 더 만드는 식으로 동작합니다.

되돌리기 — 일상의 세 가지

커밋이 무서운 이유 중 하나는 "실수하면 되돌릴 수 없을 것 같다"는 느낌 때문이에요. 실제로는 대부분의 실수가 몇 분 안에 복구 가능해요. 일상 작업의 90%는 아래 세 명령으로 해결돼요.

상황 1. 파일을 저장만 하고 커밋은 아직 안 했는데, 변경을 되돌리고 싶을 때

git restore <파일경로>

해당 파일을 마지막 커밋 상태로 되돌려요. 아직 커밋 안 한 내 작업만 사라지고, 이미 기록된 커밋은 건드리지 않아요.

상황 2. 방금 만든 커밋을 취소하고 싶을 때 (메시지가 틀렸거나 파일을 빠뜨렸을 때)

git reset --soft HEAD~1

가장 최근 커밋만 취소해요. 파일 내용은 그대로 유지되고, "아직 커밋 안 한 변경" 상태로 다시 돌아와요. 수정한 뒤 다시 git add → git commit 하면 돼요.

--soft 는 "커밋 기록만 지운다"는 뜻이에요. --hard 는 파일 내용까지 날리는 훨씬 위험한 옵션이니 실수로 치지 않게 조심하세요.

상황 3. 이전 커밋 시점의 코드가 잠깐 보고 싶을 때 (되돌리지는 않고 참고만)

git checkout <commit 해시> -- <파일경로>

그 파일만 예전 상태로 복원해요. 다른 파일은 그대로예요. 참고가 끝났으면 최신 상태로 돌아오면 돼요.

git checkout HEAD -- <파일경로>

체크포인트로서의 커밋 — 에이전트 워크플로우

코딩 에이전트는 작업 단위마다 커밋을 만드는 습관에 특히 잘 맞아요.

체크리스트 단위 커밋

긴 작업을 에이전트가 여러 단계로 쪼갠 뒤, 각 단계 완료 시마다 커밋을 찍어요.

step 1  read auth module         [done]   -->  commit: "read: auth module"
step 2  add input validation     [done]   -->  commit: "feat: add input validation"
step 3  update tests             [done]   -->  commit: "test: add validation tests"

각 커밋이 "여기까지는 확실히 동작" 체크포인트예요. 3번 단계에서 잘못이 드러나도 2번까지만 살리고 다시 시도할 수 있어요.

CONTINUE.md 와 커밋 히스토리

세션 경계에서 CONTINUE.md (다음 세션 지침) 를 남기고 커밋해두면 이런 효과가 있어요.

새 세션 시작 시 @CONTINUE.md 한 마디로 맥락이 복구돼요.
커밋 이력에서 "이번 세션에 어디까지 했는지" 역추적이 가능해요.

세션당 CONTINUE.md 1회 갱신 + 마지막 커밋이 기본 패턴이에요.

Slash Command 로 커밋 자동화

에이전트의 슬래시 커맨드 디렉토리에 commit.md 같은 프롬프트 파일을 두면 /commit 한 번으로 메시지 작성부터 실행까지 맡길 수 있어요. "매번 메시지 어떻게 쓰지?" 고민을 줄여줘요.

Claude Code: .claude/commands/commit.md
Codex: .codex/prompts/commit.md

자세한 설정 방식은 Claude Code 3대 설정 축 과 Codex 사용 가이드 의 슬래시 커맨드 섹션을 참고하세요.

이 레포의 커밋·푸시 정책 (참고 예시)

프로젝트마다 커밋 정책이 다를 수 있다는 걸 보여주는 예시로, 이 레포(llm-field-notes) 의 정책을 잠깐 소개할게요.

로컬 커밋 자유 — 언제든 쌓아도 무방. 되돌릴 수 있어 부담 없어요.
push 는 작업 단위 종료 시 자동 — 이 노트의 특성상 GitHub 에서 바로 확인할 수 있도록 매 단위마다 원격에 반영해요.
Orphan push 방식 — GitHub 에는 커밋 히스토리를 노출하지 않아요. push 할 때마다 히스토리를 초기화한 단일 커밋 상태로 업로드해요.

Orphan push 는 일반적이지 않은 정책이에요. 일반 프로젝트는 표준 git push 로 커밋 이력 전체를 공유하고, 이력 자체가 협업과 디버깅의 자산이에요. 이 노트 특성상 "과정"보다 "현재 상태"만 노출하려는 의도로 이 레포에서만 채택한 예외예요.

정리

커밋 = "이 상태 저장" 세이브 포인트.
로컬에만 쌓는 단계는 언제든 되돌릴 수 있어 부담이 없어요.
push 해서 원격에 올라간 시점부터는 신중해야 해요.
에이전트 워크플로우에서 체크리스트 단위 커밋은 실수 복구의 핵심 장치예요.
비개발자용 3대 복구 명령: git restore, git reset --soft HEAD~1, git checkout <hash> -- <file>.

짝 부록

Claude Code 3대 설정 축 — 체크포인트 워크플로우가 왜 에이전트 통제의 기본인지, .claude/commands/ 슬래시 커맨드 설정 방식
Codex 사용 가이드 — AGENTS.md·config.toml·승인·Skills·Hooks, .codex/prompts/ 슬래시 커맨드 설정 방식