훅과 자동 검증

02이 차시를 마치면

• 1.CLAUDE.md 같은 '부탁하는 규칙'과 훅 같은 '강제하는 장치'의 차이를 설명할 수 있다.
• 2.커밋 전에 린트/포맷/테스트를 자동으로 강제하는 훅을 만들 수 있다.
• 3..env 등 민감 파일에 대한 접근을 차단하는 훅을 만들 수 있다.
• 4.테스트를 먼저 정의하고 AI에게 구현을 맡기는 테스트 주도 방식으로 작업할 수 있다.
• 5.GitHub Actions 등으로 같은 검증이 CI에서도 자동 실행되게 만들 수 있다.

03왜 필요한가

CLAUDE.md에 '커밋 전에는 항상 린트를 돌리고, .env 파일은 절대 읽거나 수정하지 마세요'라고 적어뒀다고 해보자. 대부분의 세션에서는 이 규칙이 잘 지켜진다. 그런데 대화가 길어지고 맥락이 쌓이다 보면, 어느 순간 AI가 린트 없이 바로 커밋을 하거나, 디버깅을 하다 무심코 .env 파일을 열어 내용을 출력해버리는 순간이 온다. 규칙을 안 지킨 게 아니라, 그 규칙이 있다는 사실 자체를 대화 맥락 어딘가에서 놓친 것이다.

• ·규칙을 아무리 자세히 적어도, 긴 세션에서는 맥락이 밀려나며 지켜지지 않는 순간이 온다.
• ·규칙 위반이 실제로 사고(비밀 유출, 깨진 빌드)로 이어진 뒤에야 발견된다.
• ·'완료했습니다'라는 말을 믿고 넘어가면, 테스트 없이 넘어간 기능이 나중에 조용히 망가진다.
• ·나 혼자 지키는 규칙은 팀원의 세션에는 적용되지 않아, 사람마다 결과물의 품질이 들쭉날쭉하다.

04개념 설명

05실습 가이드

1. 1. 훅의 실행 시점 이해하기

   • -지금 프로젝트(또는 실습용 저장소)에 이미 걸려 있는 훅이 있는지 AI에게 확인해달라고 요청한다.
   • -훅이 하나도 없다면, 어떤 시점에 어떤 훅을 걸 수 있는지 현재 사용 중인 Claude Code 버전 기준으로 목록을 받아본다.

   예상 결과 — 사용 가능한 훅 시점 목록과, 현재 프로젝트에 걸려 있는 훅 유무를 파악한다.

   안 될 때 — 목록이 너무 많아 헷갈리면 이번 차시에서 다룰 두 가지(커밋 전, 파일 접근 시)만 우선 짚어달라고 범위를 좁혀 요청한다.

2. 2. 커밋 전 린트/포맷 강제 훅 만들기

   • -P6-1 프롬프트로 커밋 전에 린트와 포맷 검사를 자동으로 실행하고, 실패하면 커밋을 막는 훅을 요청한다.
   • -AI가 안내한 대로 설정 파일을 만들거나 수정한다.

   예상 결과 — 설정이 적용됐다는 안내와 함께, 어떤 명령이 커밋 전에 실행되는지 확인된다.

   안 될 때 — 설정 파일 위치를 못 찾겠으면, 현재 프로젝트에 이미 있는 설정 파일 구조를 AI에게 먼저 보여주고 그 안에 맞춰 추가해달라고 요청한다.

3. 3. 훅이 실제로 막는지 확인하기

   • -일부러 린트 규칙을 어기는 코드 한 줄을 추가한다(예: 세미콜론 생략, 사용하지 않는 변수).
   • -커밋을 시도해 정말 막히는지 확인한다.
   • -문제를 고친 뒤 다시 커밋해 이번엔 통과하는지 확인한다.

   예상 결과 — 위반 상태에서는 커밋이 거부되고, 수정 후에는 정상적으로 커밋된다.

   안 될 때 — 위반 코드인데도 커밋이 그냥 되면 훅이 제대로 연결되지 않은 것이다. P6-6(복구 프롬프트)으로 AI에게 설정을 다시 점검받는다.

4. 4. 민감 파일 접근 차단 훅 만들기

   • -P6-2 프롬프트로 .env 등 민감한 파일을 AI가 읽거나 수정하지 못하도록 차단하는 훅을 요청한다.
   • -어떤 파일 패턴을 차단 대상으로 넣을지 프로젝트 상황에 맞게 함께 정한다.

   예상 결과 — 차단 대상 파일 목록과 적용된 설정 내용을 확인한다.

   안 될 때 — 너무 광범위하게 막아 정상 작업까지 걸리면, 차단 대상 패턴을 좁혀서 다시 설정한다.

5. 5. 차단 훅 검증하기

   • -AI에게 일부러 .env 파일 내용을 보여달라거나 수정해달라고 요청해본다.
   • -요청이 거부되거나 차단되는지 확인한다.

   예상 결과 — 민감 파일에 대한 접근 요청이 실제로 차단된다.

   안 될 때 — 차단되지 않으면 파일 경로 패턴이 실제 파일 위치와 다를 수 있다. 정확한 경로를 다시 확인해 설정한다.

6. 6. 테스트 주도로 기능 하나 만들어보기

   • -이전 차시들에서 만든 기능 중 하나(또는 간단한 새 기능)를 골라, P6-3 프롬프트로 먼저 실패하는 테스트부터 작성해달라고 요청한다.
   • -테스트가 실패하는 것을 직접 확인한 뒤, 이 테스트를 통과시키는 구현을 요청한다.
   • -테스트가 통과하는지 다시 확인한다.

   예상 결과 — 테스트 작성(실패 확인) → 구현 → 테스트 통과의 순서로 진행된다.

   안 될 때 — 테스트가 처음부터 통과해버리면 테스트 자체가 아무것도 검증하지 않는 것이다. 실패해야 할 상황을 다시 짚어 테스트를 고친다.

7. 7. GitHub Actions CI 워크플로 만들기

   • -P6-4 프롬프트로 push나 PR 생성 시 자동으로 린트·포맷·테스트를 실행하는 CI 워크플로를 요청한다.
   • -안내에 따라 워크플로 설정 파일을 만들고 저장소에 커밋해 올린다(push).

   예상 결과 — GitHub 저장소의 Actions(또는 동등 화면)에서 방금 올린 커밋에 대해 검사가 자동 실행된 것이 보인다.

   안 될 때 — 워크플로가 실행되지 않으면 파일 위치나 트리거 조건(언제 실행할지) 설정이 잘못됐을 가능성이 높다. P6-6으로 복구한다.

8. 8. CI가 실제로 막는지 확인하기

   • -일부러 실패할 변경사항(예: 린트 위반 코드)을 담아 새 브랜치로 푸시하거나 PR을 올려본다.
   • -CI 결과가 실패로 표시되는지, 그 실패가 PR 화면에 명확히 보이는지 확인한다.

   예상 결과 — 의도적으로 만든 실패가 CI에서 잡히고 PR 화면에 실패 표시가 뜬다.

   안 될 때 — 실패가 안 잡히면 로컬 훅과 CI 설정이 서로 다른 검사를 하고 있을 수 있다. 두 설정이 같은 명령을 쓰는지 비교해달라고 AI에게 요청한다.

06실전 프롬프트

커밋하기 전에 항상 린트와 포맷 검사를 자동으로 돌리고,
실패하면 커밋 자체가 안 되게 만들고 싶어.

지금 이 프로젝트에서 쓰는 린트/포맷 명령이 뭔지 먼저 확인하고,
그 명령을 커밋 전에 자동 실행하는 훅을 만들어줘.

설정 파일을 어디에 만드는지, 내용이 뭘 의미하는지도
하나씩 설명해줘.

이 프로젝트에서 절대 읽거나 수정하면 안 되는 파일이 있어.
[.env, .env.local, 비밀키가 담긴 파일 등]

이 파일들에 접근하려는 시도 자체를 차단하는 훅을 만들어줘.
CLAUDE.md에 '읽지 마세요'라고 적어두는 것과는 다르게,
판단과 무관하게 아예 막히는 방식으로 만들어줘.

어떤 파일 패턴을 등록했는지도 알려줘.

[기능 이름, 예: 담당자별 합계 계산 함수]을 만들려고 해.

코드를 먼저 짜지 말고,
이 기능이 무엇을 만족해야 완료인지 확인하는
테스트 코드부터 작성해줘.

테스트를 먼저 실행해서 지금은 당연히 실패하는 걸 보여주고,
그다음에 이 테스트를 통과시키는 구현을 만들어줘.

이 저장소에 push하거나 PR을 만들 때마다
자동으로 린트, 포맷 검사, 테스트를 실행하는
GitHub Actions 워크플로를 만들어줘.

로컬에서 커밋 전에 돌리는 검사와 같은 명령을 쓰게 해줘서
로컬과 CI 결과가 서로 다르게 나오지 않게 해줘.

워크플로 파일을 어디에 만들고, 결과는 어디서 확인하는지도 알려줘.

우리 프로젝트에 지금 훅이나 CI가 하나도 없어.

린트/포맷 검사, 민감 파일 차단, 테스트 강제, CI 워크플로 중에서
지금 상태로 봤을 때 뭐부터 만드는 게 좋을지
이유와 함께 우선순위를 매겨줘.

각각 만드는 데 시간이 얼마나 걸릴지도 대략 알려줘.

방금 만든 [훅 또는 CI 워크플로 이름]이
이런 상황에서 이상하게 동작해.

[막혀야 할 게 안 막히거나, 반대로 정상 작업까지 막힌 상황을 그대로 설명]

내가 설정한 내용: [설정 파일 내용 또는 실행한 순서]

지금 설정이 뭘 잘못 판단하고 있는지 먼저 짚어주고,
의도한 대로만 걸리도록 고쳐줘.

07이것만은 주의

08자가 점검

09과제

자신의 프로젝트(또는 실습 저장소)에서 가장 자주 어겨질 만한 규칙 하나를 골라, CLAUDE.md의 '부탁' 대신 훅의 '강제'로 옮겨본다. 예를 들어 특정 폴더의 파일은 리뷰 없이 수정 금지, 특정 명령 실행 전 반드시 백업 등 자신의 상황에 맞는 규칙을 하나 정해 훅으로 구현하고, CI에도 동일한 검증을 반영한다.

제출 형식 — ① 새로 만든 훅과 CI 워크플로 설정 파일 ② 훅이 위반 상황을 막는 것을 보여주는 스크린샷 또는 로그 ③ 어떤 규칙을 왜 강제로 옮겼는지 한 문단 설명을 정리해 제출한다.

10더 알아보기

• Claude Code 공식 문서 — 훅 — 실행 시점 종류와 설정 문법의 최신 사양 확인용
• GitHub Actions 공식 문서 — 워크플로 문법과 무료 실행 한도 확인용

훅(Hook)

— 작업 흐름의 특정 시점에 판단과 무관하게 강제로 실행되는 자동화 장치.

테스트 주도 개발(TDD)

— 기능을 구현하기 전에 완료 조건을 검증하는 테스트를 먼저 작성하는 개발 방식.

CI(지속적 통합)

— 코드를 저장소에 올릴 때마다 정해진 검증(빌드·테스트·린트 등)을 자동으로 실행하는 체계.

다음 차시 예고 — 다음 차시에서는 MCP를 이용해 사내 시트·데이터베이스·이슈트래커 같은 실제 업무 시스템을 AI 도구에 직접 연결하는 방법을 다룹니다.