잘 굴러가게, 그리고 안전하게

깃과 버전관리

에이전트에게 코드를 맡기기 전에 가장 먼저 깔아야 할 건 멋진 기능이 아니다. 언제든 되돌아갈 수 있는 ‘세이브 지점’이다.

1모듈에서 ‘되돌릴 수 있으면 과감해진다’고 했다. 깃은 그 되돌리기를 코드 세계에서 가능하게 만드는 장치다.

깃은 파일의 시간여행 장치에 가깝다. 작업이 일정 단계에 이를 때마다 도장을 찍어 두면, 나중에 어느 도장이든 골라 그 시점으로 통째로 돌아갈 수 있다. 그 도장 하나하나를 커밋(commit)이라 부른다.

에이전트가 한 번에 수십 개 파일을 고치는 시대에는 이 도장이 안전벨트가 된다. 마음에 안 들면 통째로 직전 커밋으로 되돌리면 그만이기 때문이다.

네 동작이면 충분하다

깃의 명령어는 수십 개지만, 에이전트와 일할 때 실제로 쓰는 건 손에 꼽는다. 흐름만 머리에 넣으면 된다.

• 상태 보기(status). 지금 무엇이 바뀌었는지부터 확인한다. 모든 일은 여기서 시작한다.
• 담기(add). 이번 도장에 포함할 변경을 고른다. 관련 없는 변경을 섞지 않는 게 핵심이다.
• 도장 찍기(commit). 고른 변경에 ‘무엇을 왜 바꿨는지’ 한 줄을 붙여 박제한다.
• 되돌리기(restore · revert). 도장을 잘못 찍었거나 길을 잘못 들었을 때 안전하게 과거로 돌아간다.

클로드 코드는 이 흐름을 알아서 처리한다. “지금까지 작업 커밋해줘”라고만 해도 바뀐 파일을 살펴 적절한 메시지로 도장을 찍는다. 다만 무엇을 커밋에 담을지는 사람이 정해 주는 편이 안전하다.

❯ 지금까지 바뀐 거 확인하고, 로그인 관련 변경만 커밋해줘

# 클로드 코드가 스스로 한 일
  ✓ git status — 변경 파일 5개 확인
  ✓ 로그인 관련 2개만 선택: git add auth.js login.html
  ✓ git commit -m "로그인 입력값 검증 추가"
  # 나머지 3개(실험용 파일)는 커밋에서 제외함

❯ 방금 커밋 메시지가 애매해. 메시지만 다시 써줘
  ✓ git commit --amend — "로그인: 빈 값·공백 입력 차단"

지금 변경사항을 커밋해줘.
- 먼저 git status로 무엇이 바뀌었는지 목록으로 보여줘
- 관련 없는 변경은 한 커밋에 섞지 말고, 주제별로 나눠서 커밋해줘
- 커밋 메시지는 한국어로 "무엇을 왜" 한 줄씩
- 커밋 전에 어떤 파일을 어느 커밋에 담을지 계획을 먼저 보여주고,
  내가 "진행"이라고 답하면 그때 커밋해줘

디버깅·에러 해결

에러 메시지는 욕설이 아니라 단서다. 그리고 에이전트는 그 단서를 사람보다 끈질기게 따라간다.

문제는 ‘에러를 없애는 능력’이 아니라 ‘왜 났는지 정확히 짚는 능력’이다. 원인을 모른 채 고치면 다른 곳이 터진다.

초보일수록 에러 창을 보면 곧장 코드를 바꾸고 싶어진다. 하지만 좋은 디버깅은 손이 아니라 눈에서 시작한다. 먼저 재현하고, 다음에 원인을 좁히고, 마지막에 고친다. 이 순서를 건너뛰면 ‘고친 것 같은’ 착각만 쌓인다.

에이전트에게 디버깅을 맡기는 법

핵심은 에이전트에게 ‘답’이 아니라 ‘증상’을 주는 것이다. 무엇을 했고, 무엇을 기대했고, 실제로 뭐가 나왔는지 — 이 세 가지를 던지면 추적이 시작된다.

1. 증상을 정확히 전달한다“안 돼요”는 단서가 아니다. 실행한 명령, 기대한 결과, 실제로 나온 에러 메시지를 그대로 붙여넣는다.
2. 가설부터 세우게 한다곧장 고치게 하지 말고 “원인 후보를 가능성 순으로 나열해줘”라고 한다. 추측이 아니라 추적이 되도록.
3. 가장 작은 재현을 만든다문제를 일으키는 최소한의 조건으로 좁힌다. 범위가 줄면 원인은 저절로 드러난다.
4. 고치고, 다시 깨지지 않게 못 박는다같은 에러가 재발하지 않도록 검증(테스트)을 하나 남긴다.

❯ 결제 버튼을 누르면 화면이 멈춰. 콘솔에 이 에러가 떠:
  TypeError: Cannot read properties of undefined (reading 'total')

# 클로드 코드가 스스로 한 일
  ✓ 원인 후보 3개 제시 (장바구니 비어있음 / 응답 지연 / 필드명 오타)
  ✓ 재현: 빈 장바구니에서만 에러 발생 확인
  ✓ 원인 확정 — cart가 undefined일 때 total 접근
  ✓ cart?.total ?? 0 으로 방어 코드 추가
  ✓ 빈 장바구니 케이스 테스트 1개 추가

코드리뷰·검증 자동화

에이전트가 짠 코드를 또 다른 에이전트에게 검수시킨다. 만든 사람과 보는 사람을 나누는 순간, 품질이 한 단계 올라간다.

사람 세계에서도 자기가 쓴 글의 오타는 잘 안 보인다. 코드도 같다. 그래서 ‘짠 쪽’과 ‘보는 쪽’을 분리한다.

이걸 11모듈의 ‘적대적 검증’과 같은 원리로 보면 된다. 한 에이전트가 코드를 만들면, 역할이 다른 에이전트(또는 같은 에이전트의 ‘리뷰어 모드’)가 트집을 잡는 눈으로 다시 읽는다. 칭찬이 아니라 결함을 찾는 게 임무다.

여기에 더해, 사람이 매번 확인하기 번거로운 검사는 자동으로 굴러가게 만든다. 커밋할 때마다 테스트가 돌고, 형식이 점검되고, 위험한 패턴이 걸러지게 해두는 것이다.

두 층의 안전망

• 리뷰 — 사람·에이전트의 눈. 의도가 맞는지, 빠뜨린 경우가 없는지, 읽기 쉬운지를 본다. 기계가 못 잡는 ‘판단’의 영역이다.
• 검증 — 기계의 손. 테스트 통과·형식 점검·금지 패턴 차단처럼 규칙으로 못 박을 수 있는 건 자동으로 돌린다. 사람의 피로에 의존하지 않는다.

9모듈에서 배운 훅(hook)이 여기서 빛난다. “커밋 직전에 테스트를 돌리고, 실패하면 커밋을 막아라” 같은 규칙을 훅으로 걸어 두면, 깜빡해서 깨진 코드를 올리는 사고가 구조적으로 사라진다.

❯ 방금 짠 결제 코드를 리뷰어 입장에서 트집 잡아줘.
  잘한 점 말고 위험한 점·놓친 경우만.

# 리뷰어 모드 에이전트의 지적
  [높음] 금액이 음수일 때 검증이 없음 — 환불 악용 가능
  [높음] 외부 응답을 신뢰 — 실패 응답 처리 누락
  [중간] 같은 요청 두 번 시 중복 결제 가능 (멱등성 없음)
  → 자동 검증 제안: 음수·0원 입력 테스트 2개 추가했습니다

지금부터 너는 깐깐한 시니어 리뷰어다. 방금 변경된 코드를 검수해줘.
- 칭찬은 생략하고, 결함·위험·놓친 경우만 지적해줘
- 각 지적에 심각도(높음/중간/낮음)를 붙여줘
- 보안·경계값(빈 값, 음수, 아주 큰 값)·실패 처리를 특히 집중해서 봐줘
- 마지막에, 사람이 매번 확인하기 번거로운 검사는
  어떤 자동 검증(테스트·훅)으로 못 박을지 제안해줘

보안 점검

사고의 90%는 화려한 해킹이 아니라, 실수로 흘린 비밀번호 한 줄에서 시작된다.

에이전트가 코드를 빠르게 만들수록, 사람이 미처 못 본 ‘새는 구멍’도 빠르게 늘어난다. 그래서 속도에 안전 점검을 한 박자 끼워 넣어야 한다.

가장 흔한 사고는 어렵지 않다. API 키나 비밀번호를 코드에 그대로 적어 두고, 그걸 깃에 커밋해 버리는 것이다. 한 번 올라간 비밀은 지워도 기록에 남는다. 그래서 비밀은 코드에 넣지 않고, 따로 보관한다(환경변수·비밀 저장소).

에이전트는 이런 점검을 지치지 않고 반복하는 데 강하다. “민감정보가 노출된 곳, 검증 없이 외부 입력을 믿는 곳을 찾아라”라고 시키면 코드 전체를 훑어 목록을 만든다.

가장 자주 새는 네 구멍

비밀 노출

API 키·비밀번호·토큰을 코드에 직접 적음. 환경변수로 빼고, 실수로 올렸으면 즉시 폐기·재발급.

입력 미검증

사용자·외부가 준 값을 그대로 믿음. 빈 값·이상한 값·악의적 값을 거른 뒤 사용.

과한 권한

필요 이상으로 넓은 접근 권한. 9모듈의 권한 사다리대로 ‘딱 필요한 만큼만’.

의존성 위험

가져다 쓴 외부 라이브러리에 알려진 취약점. 정기적으로 점검·갱신.

❯ 커밋하기 전에 민감정보 노출·입력 미검증부터 점검해줘

# 클로드 코드가 스스로 한 일
  [위험] config.js 12행 — API 키가 코드에 직접 박혀 있음
  → 환경변수 API_KEY로 분리, .env는 .gitignore에 추가 제안
  [위험] upload.js — 파일 크기·형식 검증 없이 저장
  → 허용 형식·최대 크기 검증 추가 제안
  ✓ 점검 결과를 위험도 순으로 정리했습니다 (수정은 승인 후)

모델 선택 전략

택배 한 상자 옮기는 데 트럭을 부르지 않고, 이삿짐을 자전거에 싣지 않는다. 모델 선택도 똑같다 — 일의 무게에 맞춰 고른다.

가장 똑똑한 모델을 늘 쓰는 게 정답 같지만, 실무에서는 ‘과하지도 모자라지도 않게’ 고르는 감각이 더 중요하다. 속도·비용·정확함은 함께 가지 않기 때문이다.

클로드 모델은 크게 세 결로 나뉜다. 가장 깊이 생각하는 Opus, 균형이 좋은 Sonnet, 빠르고 가벼운 Haiku다. 이름은 바뀔 수 있어도 ‘무거운 추론 · 균형 · 경량 속도’라는 세 자리는 그대로다.

요령은 단순하다. 까다로운 설계·복잡한 디버깅·중요한 의사결정처럼 ‘틀리면 비싼’ 일에는 가장 강한 모델을. 분류·요약·간단한 변환처럼 ‘많고 가벼운’ 일에는 빠른 모델을. 그 사이의 일상 작업 대부분은 균형 모델로 충분하다.

한 작업 안에서도 섞어 쓴다

11모듈의 오케스트레이션을 떠올려 보자. 전체를 지휘하는 ‘대장’ 에이전트는 강한 모델로 두되, 잘게 쪼개 병렬로 돌리는 ‘일꾼’들은 빠른 모델로 두는 식이다. 비싼 두뇌를 꼭 필요한 자리에만 배치하는 것이다.