내가 모든 프로젝트에 적용하는 Claude Code Hooks: 6가지 패턴

• 브랜드 체크 (Brand-check) 훅은 초안이 완성되기 전 금지된 단어를 잡아냅니다.

• 간격(Spacing) 및 폰트(Font) 훅은 40개 이상의 템플릿에서 발생하는 레이아웃 어긋남을 수정합니다.

• 접근성 (A11y) 및 SEO 훅은 잘못된 대체 텍스트 (alt text)와 누락된 메타 데이터를 차단합니다.

• 게시 후 검증 (Post-publish verify)은 라이브 URL이 올바르게 렌더링되는지 확인합니다.

내가 손대는 모든 프로젝트에는 6개의 훅 (hooks)이 실행됩니다. 이 훅들은 초안이 이미 라이브로 올라간 뒤 3일 후에나 발견했을 법한 실수들을 잡아냅니다. 각 훅이 무엇을 하는지, 그리고 어떤 실패를 방지하는지 소개합니다.

왜 훅 (Hooks)이 메모리 파일 (Memory Files)보다 나은가

나는 약 130개의 메모리 파일 (memory files)이 있는 워크스페이스를 운영합니다. 각 파일에는 규칙이 담겨 있습니다: 피해야 할 브랜드 단어, 간격 토큰 (spacing tokens), 폰트 스택 (font stacks), 메타 설명 (meta descriptions)을 작성하는 방식 등입니다. 한동안 나는 Claude가 이 파일들을 모두 읽고 규칙을 따를 것이라고 가정했습니다. 하지만 그렇게 작동하지 않습니다. 메모리 파일은 참조 자료일 뿐, 강제 수단이 아닙니다. Claude는 필요한 것만 읽고 나머지는 건너뛰는데, Claude가 건너뛰는 규칙들이 바로 내가 가장 중요하게 생각하는 규칙들입니다.

훅 (Hooks)은 Claude가 규칙을 기억하든 못하든 이벤트가 발생할 때 실행되기 때문에 이 문제를 해결합니다. 훅은 도구 호출 (tool call) 전후에 실행되는 작은 스크립트입니다. 이는 긴 세션 동안 모델이 집중력을 유지하는지에 의존하지 않습니다. 훅은 매번 실행되며, 통과 (pass) 또는 실패 (fail)를 반환하고, 문제가 있을 경우 작업을 차단합니다. 이 차이는 생각보다 훨씬 중요합니다. 4시간의 세션 동안 모델은 세션 시작 시 완벽하게 따랐던 규칙을 잊어버릴 수 있습니다. 하지만 훅은 잊지 않습니다.

훅이 주는 또 다른 이점은 명확한 실패 메시지입니다. 브랜드 체크 (brand-check) 훅이 특정 단어를 차단할 때, 단순히 "안 됩니다"라고 말하지 않습니다. 어떤 단어인지, 어느 줄인지, 그리고 대신 무엇을 사용해야 하는지를 알려줍니다. 이를 통해 모호한 수정 사항이 한 줄짜리 해결책으로 바뀝니다. 수백 번의 편집 과정에서 이는 실질적인 시간 절약으로 이어집니다.

나는 각 훅을 작고 단일 목적 (single purpose)으로 유지합니다. 하나의 훅은 하나의 것만 확인합니다. 검사가 실패하면 어떤 훅이 왜 실행되었는지 정확히 알 수 있습니다. 모든 것을 다 하는 거대한 훅은 그것이 잡으려 했던 버그보다 디버깅하기가 더 어렵습니다. 6개의 작은 훅은 내가 지금까지 작성한 그 어떤 프롬프트 지시문 (prompt instruction)보다 더 많은 실제 문제들을 잡아냈습니다.

이 훅들이 포함된 전체 설정(full setup)을 확인하고 싶다면, Claude Blueprint에서 제가 구축하는 워크스페이스 구조를 자세히 살펴볼 수 있습니다. 아래의 훅들은 명확한 메모리 파일(memory files), 정의된 출력 형식(output format), 그리고 가로챌 수 있는 발행 단계(publish step)와 같은 기반이 갖춰져 있다고 가정합니다.

브랜드 체크(Brand-Check)와 비용이 발생하는 단어들

브랜드 체크(brand-check) 훅은 제가 절대 빼놓고 배포할 수 없는 요소입니다. 이 훅은 Claude가 파일에 쓰려는 모든 텍스트를 읽어 금지된 단어 및 문구 목록을 스캔합니다. 이 목록은 제 작업에 특화되어 있습니다. 스튜디오 이름의 철자, 통화 형식, 금지된 비교 표현, 그리고 가벼운 블로그 포스트에는 포함되지 않기를 바라는 법적 의미를 유출할 수 있는 단어들이 포함됩니다.

이 훅이 무엇을 잡아내는지 실제 사례를 들어보겠습니다. 저는 가격을 공백을 포함한 "33 EUR" 형식으로 작성합니다. 모델은 대신 통화 기호(currency symbols)를 사용하거나 숫자 뒤에 기호를 붙이는 것을 매우 좋아합니다. 훅은 모든 변형을 잡아내며, 형식이 올바르게 맞을 때까지 파일 쓰기를 차단합니다. 엠 대시(em dashes)도 마찬가지입니다. 저는 이를 사용하지 않습니다. 하지만 대부분의 학습 데이터(training text)에 엠 대시가 가득하기 때문에 모델은 이를 끊임없이 생성합니다. 훅은 모든 엠 대시를 표시하고 해당 줄을 지목합니다.

가장 비용이 많이 발생하는(중요한) 포착 대상은 법적 문제와 인접한 것들입니다. 반품이나 보증에 관한 특정 문구들은 블로그 포스트에서 제가 구속력 있게 약속할 수 없는 의미를 담고 있습니다. 훅은 이러한 문구 목록을 보유하고 있으며, 이를 통과시키지 않습니다. 저는 제가 책임질 수 없는 약속을 담은 문장을 발행하느니, 차라리 초안 단계에서 체크를 통과하지 못하게 하는 쪽을 택하겠습니다.

이 목록은 시간이 지남에 따라 늘어납니다. 제가 수동으로 잘못된 단어를 잡아낼 때마다, 다시는 수동으로 잡는 일이 없도록 훅에 추가합니다. 그것이 진정한 가치입니다. 훅은 제가 저질렀던 모든 실수와 다시 반복하지 않기로 결정한 것들의 기록입니다. 1년이 지난 지금, 목록에는 40여 개의 항목이 있으며 약 5개의 초안 중 하나에서 무언가를 차단하고 있습니다.

이를 설정하는 방법은 간단합니다. 훅 (Hook)은 파일 쓰기 (file write) 시점에 실행되어 내용을 읽고, 일련의 패턴 매칭 (pattern matches)을 수행하며, 일치하는 항목이 발견되면 메시지와 함께 0이 아닌 종료 코드 (non-zero exit code)를 반환합니다. Claude는 이 메시지를 읽고 해당 라인을 수정합니다. 주고받는 대화나 재프롬프팅 (re-prompting)이 필요 없습니다. 수정은 동일한 편집 사이클 (edit cycle) 내에서 이루어집니다. 저는 더 광범위한 워크스페이스 로직 (workspace logic)을 Claude Blueprint에서 다루었으며, 브랜드 체크 (brand-check) 훅은 그 위에 가장 먼저 추가하는 요소입니다.

간격 및 글꼴 훅은 레이아웃 드리프트 (Layout Drift)를 방지합니다

레이아웃 드리프트 (Layout drift)는 서서히 발생하는 버그입니다. 단 한 번의 편집으로 무언가 망가지는 것은 아닙니다. 하지만 40개의 템플릿과 수백 번의 작은 변경 사항이 쌓이다 보면, 간격이 서서히 일치하지 않게 됩니다. 어떤 섹션은 24px 간격을 사용하고, 다른 섹션은 20px을 사용하며, 세 번째 섹션은 토큰 (token)으로 사용했어야 할 픽셀 값을 하드코딩합니다. 이를 인지했을 때쯤이면, 수정 작업은 수십 개의 파일을 일일이 훑어야 하는 지루한 작업이 되어 버립니다.

간격 체크 (spacing-check) 훅은 이를 근본적으로 차단합니다. 이 훅은 모든 스타일 또는 마크업 (markup) 변경 사항을 읽고 마진 (margin), 패딩 (padding), 간격 (gap) 값을 제가 승인한 스케일 (scale)과 대조하여 확인합니다. 저는 고정된 간격 토큰 (spacing tokens) 세트를 사용합니다. 값이 스케일에 없으면 훅이 이를 표시합니다. 모델에게는 가공되지 않은 픽셀 값 대신 토큰 이름을 사용하도록 지시하며, 훅이 이를 강제합니다. 이는 엄격하게 들릴 수 있습니다. 실제로 엄격하며, 그것이 바로 핵심입니다. 엄격한 간격이야말로 사이트가 40명이 무작위로 패치한 결과물이 아니라, 한 사람이 의도적으로 만든 것처럼 보이게 만드는 요소입니다.

글꼴 체크 (font-check) 훅도 타이포그래피 (typography)에 대해 동일한 방식으로 작동합니다. 저는 정의된 폰트 스택 (font stack)과 정의된 크기 및 굵기 세트를 가지고 있습니다. 훅은 타이포그래피를 건드리는 모든 변경 사항을 읽고 승인된 값을 사용하는지 확인합니다. 이 훅이 잡아내는 전형적인 실패 사례는 모델이 고립된 상태에서는 합리적으로 보인다는 이유로 임의로 만들어낸 엉뚱한 폰트 패밀리 (font-family) 선언입니다. 고립된 상태에서는 합리적일 수 있습니다. 하지만 다른 39개의 템플릿과 일치하지 않기 때문에, 문맥 (context)상으로는 틀린 것입니다.

이 두 가지 훅(hook)에서 제가 좋아하는 점은 인간 리뷰어가 거의 항상 놓치는 문제들을 잡아낸다는 것입니다. 아무도 20px의 간격을 눈으로 훑으면서 "이건 24px이어야 해"라고 생각하지 않습니다. 두 섹션이 나란히 놓여 있어 약간 어색해 보일 때 비로소 알아차리게 되는데, 그때가 되면 이미 어떤 것이 올바른 것인지에 대한 맥락(thread)을 놓친 상태입니다. 훅이 진실의 원천(source of truth)을 유지해주기 때문에 제가 직접 그럴 필요가 없습니다.

이 두 가지를 함께 사용함으로써 아마 다른 어떤 쌍보다 더 많은 정리 작업을 아낄 수 있었을 것입니다. 일관된 레이아웃은 제대로 작동할 때는 보이지 않지만, 그렇지 않을 때는 눈에 확 띕니다. 훅은 레이아웃이 보이지 않게 유지해 줍니다.

A11y, SEO, 그리고 사용자가 실제로 체감하는 체크 항목들

a11y-check 훅은 마크업(markup)을 읽고 접근성(accessibility)의 기본 사항이 갖춰져 있는지 확인합니다. 이 훅이 잡아내는 가장 흔한 문제는 누락되었거나 성의 없는 대체 텍스트(alt text)입니다. 모델은 기꺼이 alt="image"라고 작성하거나 빈칸으로 남겨두곤 하는데, 이 두 가지 모두 쓸모가 없습니다. 훅은 설명적인 대체 텍스트가 없는 모든 이미지와 접근 가능한 레이블(accessible label)이 없는 모든 대화형 요소(interactive element)를 차단합니다. 또한 헤딩(heading) 순서도 확인하는데, H2에서 H4로 건너뛰는 것은 스크린 리더(screen reader) 탐색을 방해하며, 모델은 예상보다 자주 이런 실수를 저지르기 때문입니다.

이것들은 예외적인 사례(edge cases)가 아닙니다. 약 5명 중 1명은 스크린 리더, 키보드 탐색, 고대비 모드와 같이 이러한 세부 사항에 의존하는 방식으로 웹을 사용합니다. 빈 alt 속성은 이러한 사용자들에게 벽과 같습니다. 훅은 그 벽이 배포되는 것을 불가능하게 만듭니다.

SEO-check 훅은 메타데이터(metadata) 계층을 처리합니다. 이 훅은 모든 페이지가 검색 결과에 깔끔하게 표시되는 길이 내의 제목(title)을 가지고 있는지, 적절한 범위의 메타 설명(meta description)이 있는지, 그리고 정확히 하나의 H1을 가지고 있는지 확인합니다. 또한 설명이 제목의 중복이 아닌지, 비어 있지는 않은지 확인합니다. 아울러 페이지 속도를 느리게 만들 정도로 이미지가 큰 경우에도 경고를 보냅니다. 페이지 무게(page weight)는 페이지의 순위와 체감 속도에 영향을 미치기 때문입니다.

두 후크(hook)의 공통점은 일반적인 검토로는 드러나지 않는 문제들을 잡아낸다는 것입니다. 페이지는 브라우저에서 볼 때는 헤딩 순서(heading order)가 깨져 있거나 메타 설명(meta description)이 누락되었더라도 멀쩡해 보입니다. 스크린 리더(screen reader) 사용자가 페이지에 접속하거나 검색 엔진이 빈 요약문을 인덱싱하기 전까지는 괜찮아 보이죠. 이 후크들은 인간이 건너뛰는 계층을 점검합니다.

저는 이를 단순히 게시할 때뿐만 아니라, 모든 페이지를 작성할 때마다 실행합니다. 페이지가 빌드되는 과정에서 누락된 설명을 잡아내는 데는 단 한 줄의 코드만 들지만, 게시 후에 이를 발견하면 파일을 다시 열고, 게시 단계를 다시 실행하고, 다시 검증해야 합니다. 이 페이지들과 함께 올라가는 소셜 카피(social copy)의 경우 Buffer를 통해 예약하는데, 여기서도 동일한 원칙이 적용됩니다. 메타데이터를 하류(downstream)의 다섯 군데에서 수정하는 것이 아니라, 소스(source)에서 한 번에 수정하는 것입니다. 점검이 일찍 실행될수록 수정 비용은 저렴해집니다. 이것이 후크(hook)의 논리를 한 문장으로 요약한 것입니다.

Post-Publish Verify: 루프를 완성하다

처음 다섯 개의 후크는 무언가가 배포(ship)되기 전에 실행됩니다. 여섯 번째는 배포 후에 실행됩니다. Post-Publish Verify 후크는 게시 단계가 완료되면 라이브 URL을 가져와 페이지가 실제로 렌더링(render)되었는지 확인합니다. 페이지가 200 상태 코드를 반환하는지, 라이브 HTML의 제목이 제가 작성한 제목과 일치하는지, 메인 콘텐츠가 존재하며 반쯤 비어 있는 템플릿은 아닌지, 그리고 본문에 명백한 에러 문자열이 나타나지 않는지를 확인합니다.

이 후크는 제가 계속해서 맞닥뜨렸던 특정한 실패 사례 때문에 만들어졌습니다. 게시 단계는 성공했다고 보고합니다. 파일은 업로드되었고, 플랫폼은 이를 수락했으며, 모든 로컬 점검(local check)도 통과했습니다. 하지만 캐싱(caching) 문제나 렌더링 시에만 나타나는 템플릿 오류 때문에 라이브 페이지는 어쨌든 깨져 있었습니다. 아무도 저에게 확인하라고 알려주지 않았기 때문에 저는 몇 시간, 때로는 며칠 동안 이를 알아차리지 못했습니다. 성공 메시지가 거짓말을 했던 것입니다.

게시 후 검증 (Post-publish verify)은 실제 페이지를 가져와 실제 방문자가 보게 될 내용을 읽습니다. 만약 제목이 누락되었거나, 본문이 비어 있거나, 응답이 404라면, 훅 (hook)은 명확하게 실패를 알리고 저는 변경 사항을 여전히 기억하고 있는 동안 즉시 이를 수정합니다. "게시했다"와 "성공했다는 것을 안다" 사이의 간격이 몇 시간에서 몇 초로 줄어들었습니다.

검증 목록은 브랜드 체크 (brand-check) 목록과 동일한 방식으로 늘어납니다. 게시가 새로운 방식으로 실패할 때마다, 저는 그 실패에 대한 체크 항목을 추가합니다. 이제는 구조화된 데이터 (structured data)가 존재하는지, 표준 URL (canonical URL)이 올바른지, 그리고 페이지가 실수로 no-index로 설정되지 않았는지를 확인합니다. 이 각각의 항목들은 제가 무언가 잘못된 것을 배포하고 운 좋게 발견했던 실제 사건들로부터 나왔습니다.

Shopify를 통해 페이지가 게시되는 스토어프런트 (storefront) 측면에서는 이 훅이 훨씬 더 중요합니다. 왜냐하면 망가진 상품 페이지는 망가진 스토어프런트와 같기 때문입니다. 검증 단계는 저에게 한 가지 질문에 대한 정직한 답변을 제공합니다: 내가 게시한 것이 실제로 라이브 상태이며 올바른가.

더 넓은 워크플로우에 대한 배경 지식은 이 훅들을 보호 대상인 게시 파이프라인 (publish pipeline)에 연결하는 Claude Blueprint에 있습니다.

핵심 요약 (Bottom Line)

여섯 개의 훅이 있으며, 각각은 한 가지 작업만 수행합니다. 브랜드 체크 (Brand-check)는 금지된 단어와 잘못된 통화 형식을 차단합니다. 간격 (Spacing) 및 글꼴 (font) 훅은 수십 개의 템플릿 전반에서 레이아웃을 유지합니다. A11y (접근성) 및 SEO (검색 엔진 최적화) 훅은 실제 사용자와 검색 엔진이 느끼지만 일반적인 검토로는 절대 볼 수 없는 것들을 잡아냅니다. 게시 후 검증 (Post-publish verify)은 라이브 페이지가 실제로 라이브 상태이며 올바른지 확인합니다.

이 중 어떤 것도 영리한 방식은 아닙니다. 이들은 이벤트 (event) 발생 시 실행되어 통과 (pass) 또는 실패 (fail)를 반환하는 작은 스크립트들입니다. 이들의 힘은 모델이 긴 세션 동안 규칙을 기억해야 하는 것에 의존하지 않고, 매번 실행된다는 점에 있습니다. 메모리 파일 (memory file)은 제안일 뿐이지만, 훅 (hook)은 관문 (gate)입니다.

하나부터 시작해 보세요. 브랜드 체크 (brand-check) 훅은 구축하기 가장 쉬우며, 가장 당혹스러운 실수들을 잡아냅니다. 수동으로 문제를 발견할 때마다 새로운 패턴을 추가하세요. 그러면 다시는 그 문제를 수동으로 발견할 일이 없을 것입니다. 몇 주 안에 여러분의 작업 방식에 정확히 들어맞는 세트를 갖게 될 것입니다. 이 훅들이 위치하는 워크스페이스 구조를 원하신다면, Claude Blueprint가 제가 모든 프로젝트의 기반으로 삼는 토대를 설명해 줍니다.

이 기사에는 제휴 링크가 포함되어 있습니다. 이 링크를 통해 가입하시면, 귀하에게 추가 비용 부담 없이 저에게 소정의 수수료가 지급될 수 있습니다. (광고)