전은성 Dev
AI

AI에게 스펙을 쓰게 하고, 자기검토를 시키고, 그 다음 구현하기

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

  • 기간: 넉 달
  • 커밋마다 어떤 도구로 작업했는지 트레일러를 남겼다
    — Made-with: Cursor, Co-Authored-By: Claude <모델>

트레일러를 남긴 덕에 나중에 “이 코드를 어떤 방식으로 짰더라”를 되짚을 수 있었다.
집계해 보니 두 도구를 성격에 따라 나눠 쓰고 있었다:

  • Cursor — 파일이 눈에 보이고 편집 범위가 좁은 작업
    • 마이그레이션 SQL 작성
    • DTO 추가
    • 매퍼 쿼리 수정
  • Claude Code — 여러 파일에 걸친 탐색과 판단이 필요한 작업
    • 예: 인덱스 미적용 원인 추적 후 130개소 일괄 전환 (1M 컨텍스트 모델)
  • 주목할 지점: 도구 비율이 아니라 커밋이 남긴 워크플로의 모양

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

2026년 4월 9일, 조직 재배정 엑셀 업로드 기능 작업의 커밋 순서:

docs: 단말 조직 재배정 엑셀 일괄 업로드 기능 스펙 작성
docs: 단말 조직 재배정 스펙 자기검토 수정
      (OrgResolutionModal 노출, MyBatis 쿼리 방식 명확화)
docs: 조직 선택 모달 완전 독립 방식으로 스펙 수정
      (사이드 이펙트 차단)
docs: 단말 조직 재배정 구현 플랜 작성
  • 여기까지 전부 docs: — 코드 0줄
  • 구현 커밋은 이 다음

각 단계에서 실제로 한 일:

1. 스펙 작성

  • 무엇을 만들 건지 문서로 먼저 작성
  • 산출물은 코드가 아니라 합의 대상

2. 자기검토

  • 방금 쓴 스펙을 다시 읽고 구멍 탐색

  • 핵심 조건: 새 대화 · 새 컨텍스트에서 “이 스펙의 문제를 찾아라”

  • 같은 세션에서 이어 물을 경우: 방금 쓴 걸 변호하려는 경향

이 커밋이 잡아낸 것:

  • 모호성 해소 모달의 노출 시점 미기재

  • MyBatis 쿼리 작성 방식 애매

  • 둘 다 구현 중 발견 시 되돌아와야 했을 종류의 공백

3. 재검토

  • 문제: 조직 선택 모달이 기존 모달 흐름에 얹히는 구조
  • 위험: 기존 매핑 화면에 사이드 이펙트
  • 조치: 완전히 독립된 모달로 방향 전환

설계 변경을 코드 0줄 상태에서 한 것이다.

4. 플랜 작성

  • 확정된 스펙을 구현 순서로 분할

구현은 극도로 잘게 쪼갠다

플랜이 나온 뒤의 구현 커밋 단위:

  • feat: DTO 추가
  • feat: 파서 추가

  • feat: DAO 추가

  • 커밋 메시지가 A-3, C-2, D-1, Phase 0~3 같은 계획 항목 ID를 참조하는 이유
  • 대응 관계: 플랜 항목 1개 = 커밋 1개

이렇게 하는 이유는 AI 산출물의 검토 가능성:

  • 한 커밋이 15개 파일 600줄 → 사람이 읽지 못함
  • 읽지 못하면 승인이 아니라 통과
  • DTO 하나짜리 커밋 → 30초면 확인

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

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

fix: validateDeviceOrgRemap currentOrgName 조회 누락 보완
fix: DeviceOrgRemapRowDto rowIndex 주석 수정
     (시트 행 번호 기준 명확화)
  • 성격: 구현 직후에 붙은 후속 수정 커밋
  • 스펙 작성 + 자기검토 2회 + 플랜까지 거친 뒤에도 필드 하나 미기입 상태로 커밋 유출

여기서 볼 수 있는 AI 코드 생성의 전형적인 실패 모드:

  • 주변부 누락 — 메인 로직은 정상, 표시용 필드 하나 누락. 컴파일도 되고 테스트도 통과. 화면에서 빈칸을 봐야 인지 가능
  • 주석과 코드의 불일치 — rowIndex가 0-based인지 시트 행 번호인지 주석에 애매하게 기재. 코드는 동작하지만 다음 사람이 오독
  • 자기검토의 한계 — 설계 수준 공백(사이드 이펙트, 모호한 방식)은 포착. 필드 누락 같은 세부는 미포착. 층위가 다름

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

남는 교훈

스펙을 커밋한다는 게 핵심이다.

  • 채팅창 안에서만 오간 설계는 다음 세션에서 소멸
  • docs: 커밋으로 저장소에 보관 → 다음 대화의 입력으로 재사용
  • “왜 이렇게 만들었나”에 대한 답으로도 기능

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

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