커밋 히스토리가 곧 작업 기록이다

이 프로젝트에서 넉 달간 내가 남긴 커밋은 201건이다. 그중 185건, 92%에 AI 도구 트레일러가 붙어 있다.

두 도구를 성격에 따라 나눠 썼다. Cursor는 파일이 눈에 보이고 편집 범위가 좁은 작업 — 마이그레이션 SQL 작성, DTO 추가, 매퍼 쿼리 수정 같은 것들. Claude Code는 여러 파일에 걸친 탐색과 판단이 필요한 작업. 인덱스가 왜 안 먹는지 추적해 130개소를 일괄 전환한 커밋에 1M 컨텍스트 모델이 붙어 있는 게 그 예다.

흥미로운 건 도구 비율이 아니라 커밋이 남긴 워크플로의 모양이다.

스펙 → 자기검토 → 플랜 → 구현

2026년 4월 9일, 조직 재배정 엑셀 업로드 기능을 만들면서 남긴 커밋 순서다.

25b3093  docs: 단말 조직 재배정 엑셀 일괄 업로드 기능 스펙 작성
9df64ba  docs: 단말 조직 재배정 스펙 자기검토 수정
         (OrgResolutionModal 노출, MyBatis 쿼리 방식 명확화)
fa3cbc4  docs: 조직 선택 모달 완전 독립 방식으로 스펙 수정
         (사이드 이펙트 차단)
455cabf  docs: 단말 조직 재배정 구현 플랜 작성

여기까지가 전부 docs:다. 코드는 한 줄도 없다. 구현 커밋은 이 다음에 나온다.

각 단계에서 실제로 한 일은 이렇다.

1. 스펙 작성 (25b3093) — 무엇을 만들 건지 문서로 먼저 쓰게 한다. 이 단계의 산출물은 코드가 아니라 합의 대상이다.

2. 자기검토 (9df64ba) — 방금 쓴 스펙을 다시 읽고 구멍을 찾게 한다. 새 대화, 새 컨텍스트에서 “이 스펙의 문제를 찾아라”라고 시키는 게 핵심이다. 같은 세션에서 이어서 물으면 방금 쓴 걸 변호하려 든다.

이 커밋이 잡아낸 건 두 가지였다. 모호성 해소 모달을 어느 시점에 노출할지가 스펙에 안 적혀 있었고, MyBatis 쿼리를 어떤 방식으로 짤지가 애매하게 남아 있었다. 둘 다 구현 중에 만났으면 되돌아와야 했을 종류의 공백이다.

3. 재검토 (fa3cbc4) — 한 번 더 돌렸더니 더 큰 게 나왔다. 조직 선택 모달이 기존 모달 흐름에 얹히는 구조였는데, 그러면 기존 매핑 화면에 사이드 이펙트가 생긴다. 완전히 독립된 모달로 방향을 바꿨다. 설계 변경을 코드 0줄 상태에서 한 것이다.

4. 플랜 작성 (455cabf) — 확정된 스펙을 구현 순서로 쪼갠다.

구현은 극도로 잘게 쪼갠다

플랜이 나온 뒤의 구현 커밋들은 feat: DTO 추가, feat: 파서 추가, feat: DAO 추가 수준으로 잘다. 커밋 메시지가 A-3, C-2, D-1, Phase 0~3 같은 계획 항목 ID를 참조하는 것도 이 때문이다. 플랜의 항목 하나가 커밋 하나에 대응한다.

이렇게 하는 이유는 AI 산출물의 검토 가능성 때문이다. 한 커밋이 15개 파일 600줄을 건드리면 사람이 읽지 못한다. 읽지 못하면 승인이 아니라 통과가 된다. DTO 하나짜리 커밋은 30초면 확인된다.

실패 모드도 히스토리에 남아 있다

정직하게 쓰자면, 이 워크플로가 완벽하지 않다는 증거도 같은 날짜에 있다.

d66883d  fix: validateDeviceOrgRemap currentOrgName 조회 누락 보완
00ad85e  fix: DeviceOrgRemapRowDto rowIndex 주석 수정
         (시트 행 번호 기준 명확화)

구현 직후에 붙은 후속 수정 커밋이다. 스펙을 쓰고, 두 번 자기검토하고, 플랜까지 짰는데도 필드 하나를 안 채운 채로 커밋이 나갔다.

여기서 볼 수 있는 AI 코드 생성의 전형적인 실패 모드는 이런 것들이다.

• 주변부 누락 — 메인 로직은 맞는데 표시용 필드 하나를 안 채운다. 컴파일도 되고 테스트도 통과한다. 화면에서 빈칸을 봐야 안다.
• 주석과 코드의 불일치 — rowIndex가 0-based인지 시트 행 번호인지가 주석에 애매하게 적혀 있었다. 코드는 동작하지만 다음 사람이 잘못 읽는다.
• 자기검토의 한계 — 자기검토는 설계 수준의 공백(사이드 이펙트, 모호한 방식)은 잘 잡는데, 필드 하나 빠뜨린 것 같은 세부는 잘 못 잡는다. 층위가 다르기 때문이다.

그러니까 이 워크플로가 준 건 “버그 없는 코드”가 아니다. 버그의 종류를 바꿔준 것에 가깝다. 구조를 잘못 잡아 되돌아가는 일은 줄었고, 대신 잔손질 커밋이 늘었다. 되돌리는 비용이 훨씬 크니 남는 장사다.

남는 교훈

스펙을 커밋한다는 게 핵심이다. 채팅창 안에서만 오간 설계는 다음 세션에서 사라진다. docs: 커밋으로 저장소에 박아두면 다음 대화의 입력으로 그대로 쓸 수 있고, 나중에 “왜 이렇게 만들었나”에 대한 답도 된다.

자기검토는 반드시 컨텍스트를 끊고 시켜야 한다. 방금 스펙을 쓴 세션에서 “문제 없나?”라고 물으면 대체로 “없다”는 답이 온다. 문서만 던져주고 새로 시작해야 fa3cbc4 같은 방향 전환이 나온다.

AI를 쓴다고 리뷰 부담이 줄지 않는다. 오히려 커밋을 더 잘게 쪼개야 한다. 생성 속도가 빨라질수록 사람이 읽을 수 있는 단위로 끊는 규율이 더 중요해진다. 92%가 AI 트레일러라는 건 92%를 검토해야 한다는 뜻이기도 하다.