Claude Code의 PostToolUse hook을 사용하여 저장 시 문체 NG 단어를 경고하도록 설정하기

기술 기사를 작성하다 보면, 공개 전 리뷰 단계에서 정형화된 맺음말이나 과도한 강조 표현을 삭제하는 작업이 발생합니다.

리뷰 시에 한꺼번에 찾아내어 수정할 수도 있지만, 저장할 때 바로 알아차릴 수 있다면 수정 범위(差し戻し)를 줄일 수 있습니다. 그래서 Claude Code의 PostToolUse hook을 사용하여, 기사 파일을 저장한 직후에 문체 NG 단어를 경고하는 메커니즘을 만들었습니다.

이 기사에서는 Write|Edit 이후에 Bash 스크립트를 실행하여, 대상이 articles/*.md일 때만 grep을 수행하는 최소 구성을 정리합니다.

설정 파일에서는 Write|Edit 이후에 체크용 스크립트를 호출합니다.

{
"hooks": {
"PostToolUse": [
...

스크립트 측에서는 tool input으로부터 file_path를 추출하여 기사 파일만을 대상으로 합니다.

input=$(cat)
file=$(printf '%s' "$input" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^" ]*\)".*/\1/p' | head -n1)
case "$file" in
...

실제 코드에서는 NG_WORD_1 부분에 프로젝트의 문체 규칙에서 금지하는 어구를 | 구분자로 나열합니다. Qiita 본문에는 해당 어구 자체를 직접 나열하지 않음으로써, 공개 전 체크 시 오검출되지 않도록 하고 있습니다.

처음에는 공개 전 리뷰만으로도 충분하다고 생각했습니다.

하지만 기사를 여러 편 작성하다 보니, 리뷰 시마다 매번 같은 표현을 찾게 됩니다. 문체 NG 단어는 내용의 판단이 아니라 기계적으로 검출할 수 있습니다. 사람이나 별도의 에이전트(Agent)의 리뷰 시간을 기술 설명이나 기밀 유지 리스크 확인에 더 많이 사용하고 싶은 상태였습니다.

한편, 모든 Markdown 파일에 hook을 실행하면 방해가 됩니다. README.md나 handoff에는 일시적인 메모가 들어가는 경우가 있어, 기사 본문과 동일한 엄격함으로 경고하면 노이즈가 증가합니다.

hook은 Write|Edit 전체에 대해 발화합니다. 따라서 스크립트 서두에서 articles/*.md로만 범위를 좁힙니다.

case "$file" in
*articles/*.md|*articles\\*.md) ;;
*) exit 0 ;;
...

Windows와 Unix 스타일 경로를 모두 상정하여, 슬래시(/)와 백슬래시() 중 어느 것이든 통과하도록 했습니다.

설정 측에서는 2>/dev/null || true를 붙였습니다.

"command": "bash .claude/hooks/check-article-style.sh 2>/dev/null || true"

문체 체크는 보조적인 역할이므로, grep이나 JSON 분석이 실패했다는 이유만으로 기사 편집을 중단시켜서는 안 됩니다. 경고할 수 있을 때만 경고하고, 실패 시에는 조용히 통과시키는 설계로 했습니다.

검출되었을 때만 Claude Code가 읽을 수 있는 JSON을 반환합니다.

escaped=$(printf '%s' "$hits" | sed 's/\\/\\\\/g; s/"/\\"/g' | awk '{printf "%s\\n", $0}')
printf '{"systemMessage":"[문체 규칙 위반 단어 있음]\n%s→ /article-review 로 모든 항목을 체크하거나, 다른 표현으로 수정해 주세요."}\n' "$escaped"

행 번호를 포함하면 다음 편집 시 수정할 위치를 알 수 있습니다.

이 hook이 공개 전 리뷰를 완전히 대체할 수는 없습니다.

검출할 수 있는 것은 미리 나열한 문체 NG 단어뿐입니다. 기밀 유지 의무, 사실 오인, 코드 블록의 언어 지정, Qiita / Zenn의 프론트매터(Frontmatter)는 별도의 리뷰를 통해 확인해야 합니다.

hook은 '빨리 알아차리는 메커니즘'이지, '공개 여부를 판단하는 메커니즘'이 아닙니다. 공개 전에는 별도의 에이전트 리뷰와 기사 리뷰 체크리스트를 거칩니다.

또한, NG 단어 리스트를 writing-style.md와 스크립트 양쪽에 두면 차이가 발생할 수 있습니다. 운영 시에는 규칙 변경 시 hook의 pattern도 동시에 확인하기로 했습니다.

저장 시의 문체 경고는 작은 자동화이지만, 기사 리뷰의 노이즈를 줄일 수 있었습니다.

PostToolUse에서 Write|Edit

나중에 스크립트를 실행한다 - 스크립트 측에서
articles/*.md

대상으로 한정한다 - 실패하더라도 편집을 중단하지 않고, 히트(hit)했을 때만
systemMessage

를 반환한다

사람이나 다른 에이전트(Agent)의 리뷰는 기계가 잡아낼 수 있는 표현이 아니라, 논리성과 사실 정합성(Fact consistency)을 확인하는 데 사용하는 것이 더 효과적이었습니다.

harness17/zenn-articles - 본 기사에서 다룬 기사 리포지토리 (Repository)

• .claude/settings.json - Claude Code 측 hook 설정
• .claude/hooks/check-article-style.sh - 문체 체크 스크립트