AI 드리븐

지도 위치 : 3일차 · 신뢰와 운영 · 변경을 기록하고, 검사하고, 되돌리기 | 이전: 17차시 자동화된 테스트 | 다음: 19차시 자동화 파이프라인 ① 키워드 : 변경 이력 관리 흐름, 커밋 단계 자동 검사, 되돌리기

이 차시를 다 읽으면

1. Git · 커밋 · 브랜치 · PR 을 유와 종차로 정의하고, Git과 GitHub를 ④ 로컬 ↔ 원격 축으로 가를 수 있다.
2. "기능 하나 = 브랜치 하나 = PR 하나"와 작은 커밋 규칙이 AI와 일할 때 특히 중요한 이유를 말할 수 있다.
3. pre-commit 검사 를 정의하고, 에이전트 안의 훅 · 권한과 적용 범위 가 어떻게 다른지 설명할 수 있다.
4. 커밋 검사가 왜 빨라야 하고, 왜 우회될 수 있으며, 그래서 무엇으로 보강하는지 말할 수 있다.
5. 되돌리기 다섯 가지를 상황별로 고르고, revert ↔ reset 을 "기록을 덧붙이나, 고쳐 쓰나"로 가를 수 있다.
6. Git이 되돌려 주지 못하는 것을 댈 수 있다.

---

0. 이 차시의 판별 축

이 차시가 답하는 질문은 AI에게 과감하게 맡겨도 되는 근거는 무엇인가 입니다. 답은 "언제든 돌아갈 수 있다"(축 1)와 "들어가기 전에 막힌다"(축 4)입니다. 앞에서 배운 훅과 권한 (2, 12, 14차시)은 에이전트 안 의 강제 장치였습니다. 이 차시에서 처음으로 장치가 에이전트 밖 으로 나옵니다(축 5).

---

1. Git과 GitHub — 무엇에 속하는가

1.1 정의

버전 관리 — [파일 관리 방식]인데, [ 변경을 단위마다 이름표(메시지)와 함께 기록해 두고 어느 시점으로든 돌아갈 수 있게 한다 ]는 점에서 마지막 상태만 남기는 일반 저장과 구별된다.

1.2 경계 — Git ↔ GitHub (④ 로컬 ↔ 원격)

⚠️ Git은 GitHub 없이도 쓸 수 있지만, 이 과정의 강제 장치 중 상당수(PR 필수, 검사 통과 필수, CODEOWNERS)는 GitHub 쪽에 있습니다. 내 컴퓨터는 내가 마음대로 할 수 있는 곳이라 강제가 약하고, 공유된 곳일수록 강제를 걸 수 있습니다.

1.3 반례 — 이건 버전 관리가 아닙니다

---

2. ⭐ 변경 이력 흐름 — 작게 기록하기

main (항상 배포 가능한 상태)
  │
  ├── feature/reservation-cancel   ← 기능 하나당 브랜치 하나
  │     ├── 커밋: 취소 API 추가
  │     ├── 커밋: 취소 기한 검사
  │     └── 커밋: 취소 테스트 추가
  │
  └── PR(병합 요청) → 리뷰 + 자동 검사(19차시) → main에 병합

🔍 읽는 포인트 : main에서 갈래가 나갔다가 PR을 거쳐서만 돌아온다는 모양만 보면 됩니다.

⭐ 작은 커밋은 개발자보다 AI에게 맡기는 사람에게 더 중요합니다. 에이전트가 한 번에 파일 20개를 바꿨는데 뭔가 망가졌다고 해 봅시다. 커밋이 하나뿐이면 "20개 전부 되돌리기"밖에 선택지가 없습니다. 커밋이 다섯 개로 나뉘어 있으면 "세 번째만 빼기"가 가능합니다. 코드를 읽어서 원인을 찾을 수 없다면, 되돌릴 수 있는 단위가 작을수록 원인을 좁히기 쉽습니다.

커밋 메시지 형식 예 (Conventional Commits라는 널리 쓰이는 약속):

feat: 예약 취소 API 추가
fix: 동시 예약 시 초과 예약되는 문제 수정
test: 결제 금액 위조 테스트 추가
docs: ADR-0004 취소 정책 기록

🔍 읽는 포인트 : 콜론 앞의 한 단어가 변경의 종류 입니다. feat(기능) · fix(수정) · test(테스트) · docs(문서). 커밋 목록에서 test:가 fix:와 같은 PR에 섞여 있으면 17차시의 "테스트를 고쳐서 통과"를 의심해 볼 자리입니다.

에이전트에게는 지침 파일로 알려 줍니다.

작업 단위가 끝날 때마다 위 형식으로 커밋한다. main에서는 작업하지 않는다.

이 문장은 부탁 입니다. 실제로 막는 것은 3절의 커밋 검사와 19차시의 브랜치 보호입니다.

---

3. 커밋 단계 자동 검사 (pre-commit)

3.1 정의와 경계

pre-commit 검사 — [강제 장치]인데, [ 커밋이 만들어지는 순간 Git이 실행하고, 실패하면 커밋 자체를 막는다 ]는 점에서 특정 에이전트 도구 안에서만 작동하는 훅과 구별된다.

⭐ 0절 축 5의 핵심이 이 표입니다. 에이전트 안의 장치는 누가 어떤 도구로 만들었는지 에 따라 빠질 수 있습니다. 커밋 검사는 사람이 직접 커밋해도, 다른 AI 도구를 써도 적용됩니다.

3.2 무엇을 검사하나

설정 도구: JavaScript 쪽은 husky + lint-staged, 언어와 상관없이는 pre-commit 프레임워크가 흔히 쓰입니다(설정 방법은 공식 문서 확인).

3.3 빨라야 하고, 우회될 수 있다

빨라야 합니다. 커밋 한 번에 몇 분씩 걸리면 사람도 에이전트도 우회하기 시작합니다. 통합 테스트처럼 느린 검사는 커밋 검사에 넣지 않고 CI(19차시)로 보냅니다.

우회될 수 있습니다. 커밋 검사는 git commit --no-verify로 건너뛸 수 있습니다. 내 컴퓨터는 결국 내가 마음대로 할 수 있는 곳(④의 로컬 쪽)이기 때문입니다. 그래서 세 겹으로 막습니다.

{ "permissions": { "deny": ["Bash(git commit --no-verify:*)", "Bash(git push --force:*)"] } }

🔍 읽는 포인트 : deny 목록에 검사 건너뛰기 (--no-verify)와 강제 푸시 (--force)가 있다는 것만 보면 됩니다. 정확한 패턴 문법은 도구 버전마다 다르니 공식 문서를 확인하세요.

⚠️ 이런 권한 규칙은 보통 명령의 앞부분이 일치할 때 막습니다. 옵션의 위치를 바꾸면(git commit -m "..." --no-verify) 빠져나갈 수 있습니다. 그래서 2겹으로 끝내지 않고 3겹째(CI)가 반드시 필요 합니다.

앞으로 다시 만납니다 — 19차시에서 3겹째를 세웁니다. 그리고 그 CI 관문 자체를 에이전트가 낮추지 못하게 하는 장치는 20차시(CODEOWNERS)입니다.

---

4. ⭐ 되돌리기

4.1 상황별 다섯 가지

4.2 revert ↔ reset — 기록을 덧붙이나, 고쳐 쓰나

git revert — [되돌리기 방법]인데, [ 원래 커밋을 지우지 않고 그 반대 내용의 새 커밋을 덧붙인다 ]는 점에서 기록 자체를 과거로 고쳐 쓰는 git reset과 구별된다.

git reset — [되돌리기 방법]인데, [ 브랜치가 가리키는 시점을 과거로 옮겨 이후 커밋을 이력에서 없앤다 ]는 점에서 기록을 남기는 git revert와 구별된다.

⭐ 공유된 브랜치에서는 revert, 혼자 쓰는 브랜치에서만 reset. 이것만 기억해도 사고를 대부분 피합니다. 공유 브랜치에서 reset --hard 후 강제 푸시하는 것이 가장 흔한 대형 사고입니다.

4.3 ⚠️ 반례 — Git이 되돌려 주지 못하는 것

Git이 되돌리는 것은 저장소 안의 파일 뿐입니다. 0절 축 1의 오른쪽(되돌리기 어려움)에 있는 것들은 커밋을 되돌려도 돌아오지 않습니다.

💡 비유는 마지막에 — Git은 문서 편집기의 "변경 내용 추적" 입니다. revert는 "이 수정 취소"라는 새 수정을 덧붙이는 것이고, reset은 원고의 뒷장을 찢어 내는 것 입니다. 혼자 보는 초안이면 찢어도 되지만, 이미 여럿이 나눠 가진 원고를 찢으면 사람마다 원고가 달라집니다.

---

5. PR 화면으로 위험도 읽기

Git은 터미널 명령보다 GitHub 저장소 웹 화면 으로 익히는 편이 쉽습니다. Commits(이력), Branches(갈래), Pull requests(병합 요청) 세 화면이면 충분합니다.

PR 화면의 Files changed 탭에서 어느 폴더의 파일이 바뀌었는지 만 봐도 위험도를 짐작할 수 있습니다. 코드를 읽지 않고 할 수 있는 첫 번째 검수입니다.

앞으로 다시 만납니다 — 이 표의 마지막 두 줄은 20차시에서 CODEOWNERS 로 강제됩니다. "내가 보겠다"는 다짐이 "내가 승인하지 않으면 병합 불가"가 됩니다.

---

6. 클래스온에 적용하면

---

7. 실습 — 맡기고 검수하기

지시

클래스온 저장소에 커밋 단계 자동 검사를 설정해줘.
- 검사: 형식 정리, 정적 분석, 타입 검사, gitleaks 비밀값 스캔. 전체가 10초 안에 끝나게.
- 지침 파일(CLAUDE.md)에 브랜치 · 커밋 규칙(기능마다 브랜치, 작은 커밋, feat/fix/test/docs 형식)을 추가.
- 에이전트 권한에 --no-verify 커밋과 강제 푸시 차단을 추가.
작업 후 아래 두 가지를 실제로 시험하고 각각 출력 원문을 붙여:
  ① 가짜 비밀값 문자열이 든 시험 파일을 커밋 시도 → 막히는지
  ② 형식이 틀린 파일을 커밋 시도 → 막히는지
시험이 끝나면 시험 파일을 지우고 git status 출력 원문을 붙여.
보고 형식: | 검사 | 사용 도구 | 시험 결과(막힘/통과) | 걸린 시간 |
main 브랜치에 직접 커밋, git reset, 강제 푸시는 하지 마. 필요하다고 판단되면 이유를 먼저 보고하고 내 승인을 기다려.

🔍 읽는 포인트 : "실제로 시험하고 출력 원문"이 증거 요구, 마지막 두 줄이 되돌리기 어려운 작업의 사전 승인 입니다.

되돌리기를 맡길 때는 이렇게 실행 전에 설명 을 받습니다.

마지막 PR을 되돌리고 싶어. 실행하기 전에
① 어떤 방법(revert / reset)을 쓸지와 그 이유
② 무엇이 사라지고 무엇이 남는지
③ 되돌린 것을 다시 되돌릴 수 있는지
를 설명해줘. 내가 승인하면 실행해.

받을 증거

• 시험 ①, ②에서 커밋이 거부된 출력 원문 (어느 검사가 막았는지 이름이 보여야 함)
• 검사 전체가 걸린 시간
• 시험 파일 삭제 후 git status 출력 원문
• 되돌리기의 경우: 실행 전 설명 세 항목, 실행 후 GitHub Commits 화면에 생긴 취소 커밋

내가 직접 확인할 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 18차시 노트만 근거로 5문제를 내줘. 비전공자 기준으로.
"에이전트 안의 훅과 커밋 검사의 적용 범위 차이", "revert와 reset을 가르는 기준", "Git이 되돌려 주지 못하는 것"은 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.