본문으로 건너뛰기

Claude Code 하네스 1주차: CLAUDE.md에 부탁하지 말고 훅으로 강제하기

SOMEEYOON

2026.10.07

이번 기수 메인 스터디로 Claude Code 하네스 스터디(MVP공장 CTO)를 신청했다. 요즘 클라이언트 작업이든 내 작업이든 Claude Code한테 맡기는 일이 계속 늘고 있다. 그런데 맡길수록 이상하게 불안한게 내가 의도한 대로 하고 있는 건지, 그냥 그럴듯하게 해놓은 건지 매번 다시 들여다봐야 했다. 결국 일을 덜 하려고 쓴 건데 검수하는 일이 생긴 셈이었다.

1주차 첫마디가 "큰 자유에는 큰 책임이 따른다"였다. 고급 스터디라서 알아서 공부하고 알아서 나누는 방식이라는 얘기였는데, 듣다 보니 그 말이 그대로 오늘 주제이기도 했다. 에이전트한테도 자유를 줘야 일을 잘한다. 다만 정해진 범위 안에서.

아직 직접 세팅까지는 못 했고 우선은 1주차에 배운 걸 내 식으로 정리해 두는 기록이다.

진행 방법 (1주차에 배운 것)

1. .md랑 .json은 읽는 주체가 다르다

생각해 본 적 없던 부분이었다. .md는 마크다운 기호로 구조를 잡아놓은 문서라서 사람도 읽고 AI도 읽는다. .json은 사람보다는 프로그램이나 AI가 읽고 고치는 쪽이 메인이다.

그래서 AI한테 모든 판단을 넘기지 않고 내가 통제하고 싶다면 .md 파일은 내가 꼼꼼히 읽어야 한다. 거기에 내 의도가 제대로 들어가 있어야 AI도 그걸 바탕으로 움직인다. 생각해 보니 지금까지 CLAUDE.md를 AI가 써준 그대로 대충 넘겼던 적이 꽤 많다.

2. 왜 하네스인가: 추론적 센서와 연산적 센서

강아지한테 하네스를 씌우는 건 미워서가 아니다. 차에 치이거나 사람을 물지 않게 하려는 거다. 에이전트도 똑같다. 자유를 줘야 일을 잘하는데, 자유만 주면 무너진다.

여기서 센서를 두 가지로 나눴다.

  • 추론적 센서: 규칙을 알려주고 에이전트가 판단해서 지키게 하는 것. CLAUDE.md나 rules가 여기에 해당한다.

  • 연산적 센서: 허락하지 않은 작업은 에이전트가 하고 싶어도 못 하게 막는 것. hook이 여기에 해당한다.

대부분 추론적 센서에만 기대는데 그게 문제라고 했다. 부탁은 무시될 수 있다. 강제는 무시할 수 없다.

3. CLAUDE.md는 200줄 안쪽으로

CLAUDE.md가 몇천 줄이 되는 경우가 많다고 한다. 뜨끔했다. 매 세션 열릴 때 꼭 필요한 사실만 적으면 된다고 했다.

  • 파일 트리처럼 계속 변하는 건 통째로 넣지 않는다.

  • 대신 "작업 전에 ○○를 먼저 조회해라" 같은 규칙을 넣는다.

  • 이렇게 최적화하면 200줄 내외로 줄어든다고 한다.

그럼 프론트, 백엔드, DB까지 있는 큰 프로젝트는 어떻게 하냐는 질문이 나왔고, 답은 .claude/rules/였다. 경로(path)별로 룰을 쪼개 두면 해당 작업을 할 때만 그 룰이 로드된다. 에이전트는 컨텍스트를 많이 쓸수록 성능이 떨어지니까, 쪼개 놓고 필요할 때만 불러오게 해야 추론적 센서도 제대로 일한다는 얘기다.

세팅도 그냥 Claude한테 시키면 된다고 했다. "이 프로젝트에서 이 경로에는 이런 룰이 적용되게 해줘"라고 하면 해준다. "지금 세팅된 룰 알려줘"라고 하면 정리해서 보여준다. 다만 .md 파일이니까 내 의도가 다 들어가 있는지는 결국 내가 읽어봐야 한다.

4. 에이전트의 자기확신은 서브에이전트로 잡는다

에이전트는 자기가 작업한 컨텍스트에 대해서는 옳다고 믿는 경향이 있다. 그래서 다른 컨텍스트에서 결과물을 다시 봐야 한다.

방법은 서브에이전트다. 읽기(read) 권한만 준 리뷰어 역할을 하나 만들어 두고, 작업이 끝날 때마다 리뷰하게 한다. 원래 뭘 하려고 했고 결과가 어떤지 보고, 문제를 심각도(크리티컬/하이/미드)별로 정리하게 하는 식이다. 이것만 해둬도 퀄리티가 확 올라간다고 했다.

다른 모델을 같이 쓴다면 리뷰를 그쪽에 맡기는 게 더 좋다고 한다. Claude Code는 넓게 보고 Codex는 좁고 꼼꼼하게 보는 편이라서.

5. 훅은 진짜로 강제한다

이 부분이 제일 와닿았다. "AI가 짠 코드가 너무 길어서 리뷰하기 힘들다"는 문제를 CLAUDE.md에 적어두면 그건 그냥 부탁이다. 지켜질 수도 있고 아닐 수도 있다.

hook을 걸면 코드 작업이 끝나는 시점에 강제로 붙잡아서 검사할 수 있다. "300자 넘었네? 다시 해" 하고 자동으로 돌려보낸다. stderr가 Claude한테 바로 가니까, 에러 났다고 알려주면 에이전트가 다시 작업한다. 삐끗하면 훅이 잡고, 다시 작업시키고, 그걸 반복한다. 그래서 결국 나한테 오는 건 규칙이 다 지켜진 결과물이다. 에이전트가 스스로 검사하게 하면 비용이 많이 드는데, 훅은 그렇지 않다는 것도 장점이었다.

일 시킬 때 쓰라고 알려준 프롬프트는 이 두 줄이다.

룰로 세팅하는 거 말고 소프트웨어적으로 강제로 세팅할 수 있는 방법 없어? 있으면 훅으로 세팅해줘.
누가 니 작업 체크해? 없으면 서브에이전트 세팅해서 검토해줘.

6. 순서는 훅, 룰, CLAUDE.md

프로젝트를 시작할 때 하네스 구조부터 잡고 들어가는 게 좋다고 했다. 순서는 이렇게 정리했다.

  1. 기술 스택부터 조사한다.

  2. 그 스택에 맞는 훅(린트 체크, 빌드 체크 등)을 먼저 세팅한다.

  3. 훅으로 못 막는 특수한 것들은 룰로 세팅한다.

  4. 마지막으로 전체를 아우르는 CLAUDE.md를 정리한다.

작은 것부터 큰 것 순으로 촘촘하게 막는다는 느낌이다.

훅을 어떻게 만드냐는 질문도 나왔는데 답이 간단했다. 기술 스택 리서치를 시키고, 각 공식 문서에서 추천하는 베스트 프랙티스를 찾아서 훅으로 설정하라고 한다. 훅이 안 되는 건 룰로 세팅하라고 지시하면 된다.

결과와 배운 점

1주차를 듣고 나서 정리된 문장은 이거다. 자유를 주되, 정해진 범위 안에서.

지금까지 내 방식은 거의 다 추론적 센서였다. CLAUDE.md에 "이렇게 해줘"라고 길게 적어두고, 안 지키면 내가 다시 말하고. 그러니 검수가 끝나지 않았던 거다. 막을 수 있는 건 훅으로 막고, 판단이 필요한 건 룰로 나누고, 리뷰는 다른 눈한테 맡기는 구조로 바꿔야겠다는 생각이 들었다.

도움이 필요한 부분도 있다. 웹사이트 작업이 많아서 프론트, 백엔드, CMS가 섞인 프로젝트가 대부분인데, 이런 구조에서 .claude/rules/를 경로별로 어떻게 나누는지 예시가 궁금하다. 스터디장님이 예시를 보여주시긴 했지만 다양한 사례를 보면 공부가 더 될 것 같다. 비슷한 구조로 세팅해 보신 분이 있으면 공유해 주시면 좋겠다.

앞으로 해볼 것:

  • 지금 쓰고 있는 프로젝트 CLAUDE.md부터 다시 읽고 200줄 안쪽으로 줄여보기

  • 프론트/백엔드 경로별로 .claude/rules/ 나눠보기

  • 린트·빌드 체크 훅 하나라도 먼저 걸어보기

  • 작업 끝나면 리뷰하는 읽기 전용 서브에이전트 만들기

도움 받은 글

함께 이야기해요 0

로그인하고 댓글을 남겨 주세요

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기