Claude Code × textlint로 만드는 Zenn 집필 파이프라인

시작하며

AI에게 기술 기사를 쓰게 하면 그럴싸한 문장은 금방 나옵니다. 반면, 과장된 헤드라인이나 근거 없는 숫자, 장황한 문말이 섞여 그대로 공개하면 "AI가 쓴 느낌"을 지울 수 없습니다.

이 기사에서는 제가 운용하고 있는 Zenn 집필 환경을 소개합니다. Claude Code의 스킬 (Skill) 기능으로 집필 프로세스를 언어화하고, textlint로 기계적인 품질 게이트 (Quality Gate)를 거는 구성입니다.

또 하나 전하고 싶은 점은, 이것이 AI에게 모든 것을 떠넘기고 끝나는 구조가 아니라는 점입니다. 스킬을 다시 쓰고 개선할 때마다 자신의 집필 스타일이 언어화되어 갑니다. AI를 위한 규칙이 작성자 자신에게 피드백으로 돌아옵니다.

이 기사에서 알 수 있는 내용:

• 리포지토리(Repository) · 스킬(Skill) · textlint의 3층 구성 역할 분담
• skill-creator를 사용하여 집필 스킬을 만드는 흐름
• 스킬 업데이트가 자신의 집필 기술 정리로도 이어지는 감각

전체상: 3층으로 품질을 가드한다

이 리포지토리(masaki-koide/zenn-content)는 3개의 층으로 구성되어 있습니다.

• zenn-cli의 얇은 토대 — articles/<slug>.md를 작성하여 push하면 Zenn에 반영되는 구성. npm run new로 스캐폴딩(Scaffolding), npm run preview로 로컬 확인.
• Claude Code 스킬 (zenn-article-writer) — 집필 프로세스 그 자체를 모델에게 전달. 의뢰 분류, 구성안 합의, 본문 작성법, 퇴고 절차까지를 Markdown으로 기술.
• textlint — 작성된 Markdown에 대한 기계적인 게이트. AI가 쓰든 사람이 쓰든, 이곳을 통과하지 않으면 완료되지 않음.

스킬은 "어떻게 쓸 것인가"를 담당하고, textlint는 "최종적으로 무엇을 걸러낼 것인가"를 담당합니다. 역할을 나누면 스킬이 비대해지지 않습니다. 스타일 위반은 textlint가 잡아내므로, 스킬 측면에서는 전달하고 싶은 사상이나 판단 기준만을 적을 수 있습니다.

Claude Code의 스킬 기능과 skill-creator

Claude Code의 **스킬 (Skill)**은 .claude/skills/<name>/SKILL.md에 작성한 절차서를 모델에게 읽히는 구조입니다. CLAUDE.md가 리포지토리 전체에 대한 상시 지시인 것에 반해, 스킬은 "특정 태스크일 때만 호출되는 절차서"로서 동작합니다.

스킬 본체는 단순한 Markdown 파일입니다. frontmatter에 트리거(Trigger) 조건을 적고, 본문에 작업 절차를 적습니다.

---
name: zenn-article-writer
description: Zenn의 기술 기사를 작성·퇴고한다. "기사를 써줘", "Zenn 기사"...
...

description 필드가 중요합니다. 여기에 "어떤 의뢰로 호출하고 싶은지"를 구체적으로 적으면, 사용자가 "기사를 써줘"라고 말했을 때 Claude Code가 이 스킬을 자동으로 선택합니다.

스킬은 직접 작성해도 좋지만, Anthropic 공식의 skill-creator 스킬을 사용하면 자연어로부터 스킬의 템플릿을 만들 수 있습니다. "Zenn 기사를 쓰기 위한 스킬이 필요해. frontmatter 규약과, です・ます(데스·마스) 체 스타일 가이드를 포함하고 싶어"라고 전달하면 디렉토리 구조까지 생성해 줍니다.

skill-creator는 어디까지나 템플릿을 만들기 위한 것입니다. 생성된 SKILL.md를 읽고 자신의 암묵지(Tacit Knowledge)에 맞춰 다시 쓰는 작업이 본 작업입니다.

zenn-article-writer 스킬의 내용과 고안점

이 리포지토리에서 실제로 구동하고 있는 스킬에서 고안한 점들을 뽑아보겠습니다.

의뢰를 분류한 뒤 동작하기

스킬 서두에 "먼저 의뢰를 분류한다" 섹션을 두었습니다.

• 구성안만 원하는 것인가
• 신규 드래프트(Draft)를 작성하는 것인가
• 기존 원고의 퇴고인가
• 코드 해설 중심인가

이를 처음에 판단하게 함으로써, 퇴고 의뢰에 대해 갑자기 전체 문장을 다시 쓰기 시작하는 사고를 방지할 수 있습니다.

구성안 게이트로 "갑작스러운 본문 작성"을 금지하기

신규 드래프트 워크플로우에서 중요한 것은, 구성안을 제시하여 사용자의 합의를 얻기 전까지는 본문을 쓰기 시작하지 않는다는 제약입니다.

본문을 쓰기 전에, 텍스트 출력으로 다음 내용을 정리하여 제시합니다.

• 예상 독자와 전제 지식
• 목차 (H2, 필요하다면 H3까지)
• frontmatter 후보 (제목, topics, emoji, type)
• 기사의 규모감
  답변이 올 때까지

npm run new

도 Write도 실행하지 않습니다.

이 과정이 없으면 AI는 눈치껏 긴 문장을 작성해 버립니다. 그러고 나면 "역시 방향성이 다르다"라며, 작성된 수천 자를 통째로 버리는 상황이 발생합니다. 구성안(Outline)뿐이라면 텍스트 출력 1회로 끝나기 때문에, 궤도 수정 비용이 급격히 줄어듭니다.

이 기사도 구성안을 내놓고 승인을 거친 후에 본문에 착수했습니다.

스타일 가이드를 NG 패턴까지 포함하여 언어화하기

캐주얼한 です・ます(데스·마스) 조를 유지하기 위해, 긍정형 규칙뿐만 아니라 NG 패턴을 구체적인 예시와 함께 작성하고 있습니다.

### NG 패턴
- 「〜と言えるでしょう(〜라고 할 수 있겠죠)」「〜ではないでしょうか(〜가 아닐까요)」와 같은 모호한 마무리
→ 단정적으로 말하거나, 근거를 제시할 것
...

"정중하게 써줘"라고만 지시해도 AI는 장황한 경어(敬語)로 흐르기 쉽습니다. 무엇을 피하고 싶은지를 구체적으로 열거하면, 생성 시점에 자연스러운 문체가 됩니다.

퇴고는 Edit로 국소적으로

기존 원고의 퇴고 모드에서는 "전문을 Write로 다시 쓰지 않고, Edit로 국소적으로 수정한다"라고 규칙화했습니다. AI에게 퇴고를 맡기면, 스스로 좋다고 판단하여 전체 구성까지 멋대로 바꿔버리는 것을 방지할 수 있습니다.

textlint를 통한 기계적인 가드

스킬(Skill) 측에서 아무리 노력해도, 최종적으로 남는 표기 불일치(表記ゆれ)나 약한 표현은 사람도 놓치기 마련입니다. 이 부분을 npm run lint로 기계적으로 차단합니다.

설정은 간단합니다.

{
"rules": {
"preset-ja-technical-writing": {
...

3가지 프리셋(Preset)의 역할 분담은 다음과 같습니다.

프리셋	지키는 것	대표적인 규칙
preset-ja-technical-writing	일본어 기술문의 기본 작법	한 문장의 길이, 쉼표의 수, です・ます 조, 약한 표현, 장황한 표현, ら抜き(라누키)
preset-ai-writing	AI 생성문에 나타나기 쉬운 습관	아첨하는 제목, 이모지 과다, 근거 없는 숫자, 일률적인 불렛 포인트
prh + WEB+DB PRESS 사전	표기 불일치 통일	어미의 장음, 요코가나, 한자와 가나의 구분 사용

preset-ai-writing이 특히 효과적입니다. AI가 작성한 문장에 흔히 나타나는 "놀라운 퍼포먼스", "압도적인 개발 경험"과 같은 알맹이 없는 캐치프레이즈나, 이모지를 제목에 흩뿌리는 습관을 기계적으로 걸러줍니다.

스킬 측에도 npm run lint가 에러 제로(0)로 통과될 때까지 완료 보고를 하지 않는다는 규칙을 적어두었습니다. 이로써 "다 썼다고 생각하고" 던져주는 사고를 방지할 수 있습니다.

빠지기 쉬운 함정 · 주의하고 있는 점

실제로 운용하며 깨달은 점을 적습니다.

구성안 게이트가 없으면 토큰도 시간도 녹아내린다

처음에는 매번 프롬프트에 "아웃라인부터 작성해줘"라고 덧붙였습니다. 그러다 지시를 잊었을 때 AI가 3,000자를 생성하고, 구성부터 다시 해야 하는 사고가 발생합니다. 스킬 측에 "구성안 합의 없이 본문을 쓰지 않는다"라고 고정한 이후에는 이 사고가 제로가 되었습니다.

"규칙은 프롬프트로 매번 말한다"보다 "스킬에 적어둔다"가 더 확실합니다. 프롬프트는 잊어버리기 쉽고, 새로운 대화에서는 사라지기 때문입니다.

스킬을 작성하는 작업이 자신의 집필 기술을 정리하는 작업이 된다

이것이 가장 하고 싶었던 이야기입니다. 스킬에 "캐주얼한 です・ます 조"라고 적어도 AI는 지키지 못합니다. "약한 표현을 사용하지 않는다", "아첨하는 제목을 쓰지 않는다", "병렬 요소가 3개 이상이면 불렛 포인트나 테이블로 변환한다"와 같이 구체적으로 적어야 합니다.

이 작업은 자신이 평소에 막연하게 신경 쓰고 있던 집필 판단을 외부로 끄집어내는 작업입니다. 글로 써보면 스스로도 철저히 지키지 못했던 규칙들이 보입니다.

병렬적인 내용을 문장으로 길게 늘어놓기 → "A는 ~, B는 ~, C는 ~"가 보이면 불렛 포인트·테이블·H3 중 하나로 변환하기

AI가 출력한 내용 중 마음에 들지 않는 부분을 "왜 마음에 들지 않는가"까지 파고들면, 다음부터 스킬의 NG 패턴에 추가할 수 있습니다.

실패를 반영하는 루프를 지속한다

스킬은 만들어서 끝이 아닙니다. 쓸 때마다 위화감이 느껴지는 출력이 나옵니다. 그때 "다음부터는 피해야지"라고 생각만 하고 닫는 것이 아니라, SKILL.md의 NG 패턴에 추가합니다.

이 루프가 있는 덕분에 기술은 성장해 나갑니다. 동시에, 자신만의 집필 규칙도 명확해집니다.

요약

• Zenn 집필 환경을 리포지토리 (Repository) + Claude Code 기술 (Skill) + textlint의 3층 구조로 구축하면, AI에게 쓰게 하더라도 품질이 안정된다.
• 기술 (Skill)은 skill-creator로 템플릿을 만들고, 암묵지 (Implicit knowledge)를 NG 패턴까지 구체적으로 기술한다.
• textlint는 최종 게이트 (Gate)로서 기능하며, 기술 (Skill)이 비대해지는 것을 방지해 준다.
• 기술 (Skill)을 업데이트하는 작업은 작성자 자신의 집필 규칙을 정리하는 작업이기도 하다.

AI에게 모든 것을 떠넘기기 위한 환경이 아니라, AI와 함께 쓰면서 자신의 집필 스타일을 언어화해 나가는 환경이라고 생각하면, 기술 (Skill)을 작성하는 것 자체가 즐거워집니다.