기사 리포지토리(Repository)에서 Zenn / Qiita의 초안을 늘려가다 보면, 공개 전에 바로잡아야 할 문제들이 몇 가지 섞이게 됩니다.

• 문체 NG 단어가 본문에 남음
• published: false / ignorePublish: true와 같은 공개 게이트(Gate)를 무너뜨림 - 포맷이나 프론트매터(Front matter)가 깨짐
• 기밀 유지상 노출해서는 안 되는 정보가 섞임

이런 문제들을 hook이나 사전 체크(Pre-check)로 차단하는 운영을 하게 되면, 다음에 부딪히는 문제는 "hook이 실패했을 때 --no-verify로 회피하고 싶어진다"는 점입니다.

git commit --no-verify는 편리하지만, 기사 리포지토리에서는 위험했습니다. Zenn은 main으로의 push가 공개 트리거(Trigger)가 되기 때문에, 깨진 기사나 공개 플래그(Flag)의 잘못된 변경이 섞이면 그대로 외부에 공개될 가능성이 있습니다.

이 글에서는 1개 기사당 1개의 트러블로 간주하여, "hook이 실패해도 skip 하지 않고 원인을 수정한다"는 운영 방식에 집중합니다.

저의 운영 방식에서는 hook이나 커밋 전 체크의 실패를 다음 3가지 유형으로 분류합니다.

포인트는 실패한 hook을 방해꾼으로 취급하지 않는 것입니다. hook은 "공개 전에 발견하기 위한 검지(Detection)"이므로, 실패하면 분류하여 원인을 제거합니다.

이 리포지토리에서는 Claude Code 측의 .claude/settings.json에서 PostToolUse hook을 설정하고 있습니다.

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

hook 본체에서는 articles/*.md 이외를 대상에서 제외한 뒤, 문체 NG 단어를 grep 합니다. 본문에서는 검출된 단어 자체를 재게시하지 않고, writing-style.md와 동기화하고 있다는 운영 방식만을 기록합니다.

input=$(cat)
# file_path를 추출 (tool_input으로부터)
file=$(printf '%s' "$input" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^" ]*\)".*/\1/p' | head -n1)
...

이것은 Git의 pre-commit hook 그 자체는 아니며, 저장 시의 체크입니다. 다만 목적은 같습니다. 커밋 전에 문제를 찾아내어, 공개물에 섞이기 전에 수정합니다.

Git 측 규약에서도 --no-verify로 pre-commit hook을 스킵하지 않는 방침을 세우고 있습니다.

- `--no-verify`로 pre-commit hook을 스킵하지 않는다 (hook이 실패하면 원인을 수정한다)

처음에는 hook이 실패하면 "지금은 본문만 보고 싶으니까 나중에 수정하자"라고 생각하기 쉬웠습니다. 특히 문체 체크는 빌드 에러(Build error)와 달리 앱이 망가지는 것은 아닙니다.

하지만 기사 리포지토리에서는 그 생각이 위험했습니다.

예를 들어, 공개 플래그를 실수로 변경한 채 commit 하고 main에 push 하면 Zenn 측의 공개 단계로 넘어갑니다. 문체 NG 단어나 기밀 리스크도 공개 후에 깨닫게 되면 수정 비용이 높아집니다.

"나중에 수정한다"는 공개 트리거를 가진 리포지토리에서는 취약한 운영 방식이었습니다. 실패한 시점에 바로 수정하는 것이 결과적으로 더 빠릅니다.

NG 단어에 걸렸을 때, 단순히 단어만 삭제하면 문장이 부자연스러워집니다. 다음과 같이 사실 기반(Fact-based)으로 다시 작성합니다.

NG:
이 메커니즘은 매우 좋은 효과가 있었습니다.
OK:
...

문체 체크의 목적은 문장을 흐릿하게 만드는 것이 아닙니다. 과도한 강조나 모호한 마무리를 피하고, 무엇이 일어났는지를 구체적으로 쓰는 것입니다.

기사의 front matter는 단순한 메타 정보가 아니라 공개 게이트입니다.

Zenn의 초안에서는 다음을 유지합니다.

published: false

Qiita의 초안에서는 다음을 유지합니다.

private: false
updated_at: ''
id: null
...

hook이나 리뷰에서 이 부분이 어긋나면, 문장의 문제가 아니라 공개 플로우(Flow)의 문제로 취급합니다. 사용자가 공개를 명시하지 않았다면 플래그를 되돌립니다.

JSON이나 YAML의 구문 오류 (Syntax error)는 본문 퇴고와는 별개로 취급합니다. 원인이 인덴트 (Indent)나 따옴표 (Quote)라면, 기계적으로 수정한 후 다시 체크합니다.

# JSON 구문 확인 예시
Get-Content -Raw .claude/settings.json | ConvertFrom-Json | Out-Null
Get-Content -Raw .codex/hooks.json | ConvertFrom-Json | Out-Null

포맷 문제를 남겨둔 채 --no-verify로 진행하면, 다음 에이전트(Agent)나 다음 세션(Session)이 원인 조사부터 시작하게 됩니다. 지금 발견한 사람이 수정하는 것이 작업 전체의 대기 시간을 줄이는 길입니다.

• hook이 실패했을 때 --no-verify로 건너뛰면, 깨진 기사나 공개 플래그 (Public flag)의 잘못된 변경이 섞이게 됩니다. 실패 원인을 lint / 문체 체크 / 공개 게이트 (Public gate)로 나누면 수정 순서를 정하기 쉽습니다.
• 문체 NG 단어는 단어만 삭제하지 말고, 경험이나 결과가 드러나는 문장으로 수정합니다.
• Zenn / Qiita의 프론트 매터 (Front matter)는 공개 게이트이므로, 사용자의 명시가 있을 때까지 초안 (Draft) 상태를 유지합니다.

hook은 작업을 중단시키기 위해서가 아니라, 공개 전에 수정해야 할 곳을 알려주기 위해 배치하는 것입니다. 실패했을 때 건너뛰는 것이 아니라, 분류하여 원인을 수정합니다. 이 운영 방식을 도입한 이후로, 공개 전 리뷰에서 같은 종류의 지적을 반복하는 일이 줄어들었습니다.