Humanizer

AI가 쓴 글에 남는 습관(뜸 들이는 도입, "X가 아니라 Y" 대비, 한 줄짜리 마무리, 과장된 의미 부여 등)을 찾아서, 내용은 그대로 두고 사람이 쓴 글처럼 다시 쓰게 만드는 에이전트 Skill입니다. 코드 라이브러리가 아니라 SKILL.md 한 파일로 된 프롬프트이고, Claude Code·Codex 등 Skill을 지원하는 에이전트에서 동작합니다.

• 원인 하나로 설명한다: 언어 모델은 "가장 많은 독자와 주제에 무난한 선택"을 하므로, 26개 패턴을 모두 그 기본 선택의 변형으로 묶어 설명합니다.
• 강한 신호부터 고친다: 패턴 번호가 강도·빈도 순서입니다. 1~5번은 한 번만 보여도 고치고, 표시가 붙은 패턴은 다른 흔적과 같이 있을 때만 고칩니다.

ChatGPT나 Claude로 블로그 글 초안을 받아 보면 내용은 맞는데 이상하게 읽기 싫은 글이 나올 때가 많습니다.

• "오늘은 캐싱에 대해 깊이 알아보겠습니다. 지금부터 꼭 알아야 할 내용을 정리해 드립니다."
• "이것은 단순한 기능이 아니라, 협업 방식 자체의 변화입니다."
• "빠르고, 안정적이며, 확장 가능한 구조"처럼 늘 세 개씩 나열되는 형용사
• 문단마다 끝에 붙는 "바로 이것이 핵심입니다."
• 모든 항목 앞에 붙은 굵은 글씨 라벨과 이모지 제목

Humanizer는 이런 글을 "AI가 쓴 티가 나는 지점"을 목록으로 표시하고, 그 지점을 중심으로 다시 쓰게 하는 Skill입니다. 노련한 편집자가 쓰는 체크리스트를 에이전트에게 쥐여 준 것이라고 생각하면 됩니다.

기술적으로 정의하면, Humanizer는 Agent Skills 형식을 따르는 SKILL.md 한 파일짜리 프롬프트입니다. YAML frontmatter에 이름과 설명이 있고, 본문에 "왜 AI 글이 그렇게 들리는가"라는 설명, 4단계 작업 절차, 26개 패턴(각각 찾을 표현 / 문제 / Before·After 예시), 그리고 "적용하지 말아야 할 경우"가 들어 있습니다. 빌드 단계도, 실행 코드도 없습니다. 저장소에 있는 유일한 Python 코드는 패키지 파일을 검사하는 scripts/validate-package.py입니다.

이름 때문에 오해하기 쉬운 점이 하나 있습니다. Humanizer의 목표는 사람 독자가 읽기 좋은 글이고, AI 탐지기를 통과하는 것이 아닙니다. README에도 "AI 탐지기 통과는 목표가 아니며, 탐지기는 여전히 출력 대부분을 잡아낸다"고 명시되어 있습니다. 이 차이는 장단점과 대안 비교와 주의할 점과 FAQ에서 다시 다룹니다.

주요 사용 사례

• 블로그·공지 글 다듬기: AI로 쓴 초안을 붙여 넣으면 초안, 남은 흔적 목록, 최종본을 함께 돌려받습니다.
• 문서 파일 직접 수정: Humanize the prose in docs/launch-post.md처럼 경로를 주면 산문만 고치고 코드와 링크는 그대로 둡니다.

요구사항: AI로 빠르게 쓴 글을, 독자가 "AI가 썼네" 하고 넘기지 않을 글로 만들고 싶다
 ↓
일반적인 구현: "좀 더 자연스럽게, 사람이 쓴 것처럼 다듬어줘"라고 다시 요청한다
 ↓
문제 발생: 단어만 바뀌고 구조적 습관은 그대로 남거나, 그럴듯한 사실·수치가 새로 끼어든다
 ↓
Humanizer로 해결: 26개 패턴을 강한 순서로 표시하고, 사실을 보존하는 규칙 아래에서 문단 단위로 다시 쓴다

상황 예시

SaaS 스타트업의 개발자가 새 기능 "공유 초안(shared drafts)" 출시 공지를 써야 합니다. 시간이 없어 Claude에게 초안을 받았습니다.

드디어 공유 초안 기능을 소개하게 되어 정말 기쁩니다! 🚀 몇 달 동안 저희 팀도 final_v7.docx 같은 파일 이름에 파묻혀 지냈고, 더 나은 방법이 있어야 한다고 생각했습니다. 이제 두 사람이 같은 문서를 동시에 편집할 수 있습니다. 이것은 단순한 기능이 아니라, 협업 방식 자체의 변화입니다. 그리고 가장 좋은 점은? 모든 요금제에서 오늘부터 무료라는 것입니다. 곱씹어 보세요.

일반적인 구현 방식

가장 먼저 떠올리는 방법은 다시 부탁하는 것입니다.

위 글을 좀 더 자연스럽고 사람이 쓴 것처럼 다듬어줘. AI 티 안 나게.

이 방식에서 발생하는 문제

• 기준이 없습니다: "자연스럽게"는 모델에게 아무 정보도 주지 않습니다. 모델은 이모지를 빼고 단어 몇 개를 바꾼 뒤 "단순한 기능이 아니라 ~입니다" 대비는 그대로 둘 때가 많습니다.
• 같은 모델의 기본값으로 돌아갑니다: 다시 쓰는 것도 같은 모델이므로, 다시 쓴 글에 새로운 3개 나열과 새로운 마무리 문장이 생깁니다.
• 사실이 바뀝니다: "더 생생하게"라는 압력 아래에서 원문에 없던 사용자 수, 고객 인용, 날짜가 끼어듭니다. 공지 글에서는 가장 위험한 실수입니다.
• 어디가 문제였는지 남지 않습니다: 결과만 돌아오므로, 작성자는 다음 글에서 무엇을 피해야 하는지 배우지 못합니다.

Humanizer를 사용하면

같은 초안을 /humanizer에 넣으면 에이전트는 먼저 흔적을 표시합니다. 들뜬 도입과 이모지(§22, §20), "단순한 기능이 아니라 ~"(§1), "가장 좋은 점은?"(§4), "곱씹어 보세요."(§2)가 잡힙니다. 그다음 초안을 쓰고, 초안에 남은 흔적과 원문 대비 빠지거나 추가된 사실을 점검한 뒤 최종본을 씁니다.

공유 초안 기능이 오늘 나왔습니다. 몇 달 동안 저희 팀도 final_v7.docx 같은 파일을 주고받았고, 그래서 두 사람이 같은 문서를 동시에 편집하고 서로의 변경을 실시간으로 볼 수 있게 만들었습니다. 모든 요금제에서 무료입니다.

Humanizer는 2026년 1월 공개 이후 GitHub Star 약 5만 4천 개, Fork 약 4,300개를 기록했습니다(2026년 10월 기준). 저장소 하나가 Markdown 파일 하나에 가깝다는 점을 생각하면 이례적인 숫자입니다. 이유는 다음과 같습니다.

AI 글에 대한 피로가 커졌습니다. 블로그, 링크드인, 사내 문서, PR 설명까지 AI로 쓴 글이 늘면서, 독자는 "이 문장은 AI가 썼구나" 싶은 순간 글을 덜 믿게 됩니다. 글을 AI로 쓰는 사람에게 "AI 티를 줄이는 것"은 이제 품질 문제입니다.

근거가 있는 기준표를 씁니다. 패턴 목록은 개인의 취향이 아니라 Wikipedia 편집자들이 AI 생성 문서를 걸러내기 위해 관리하는 "Signs of AI writing" 문서에서 가져왔습니다. 3.0.0에서는 이 문서의 최신 내용에 맞춰 패턴을 다시 정리했습니다.

설치 비용이 거의 없습니다. 명령 한 줄로 설치하고 /humanizer 한 번으로 씁니다. 의존성도, 서버도, API 키도 필요 없고, 이미 쓰고 있는 에이전트와 모델을 그대로 씁니다.

Skill 생태계의 대표 사례입니다. Claude Code 플러그인, Skills CLI(npx skills), Claude.ai 업로드, Codex를 모두 지원하는 "이식 가능한 Skill"의 모범 사례로 자주 언급됩니다. Skill이 무엇인지 처음 배우는 사람에게도 구조가 단순해서 좋은 교재가 됩니다.

외부 검증 결과가 공개되어 있습니다. 한 사용자가 진행한 블라인드 비교(#229)에서 언어 모델 심사자들은 원본 AI 글보다 Humanizer 수정본을 16번 중 16번 선호했습니다. 같은 실험에서 AI 탐지율은 거의 줄지 않았는데, 프로젝트는 이 결과를 받아들여 "탐지기 통과는 목표가 아니다"를 README에 명시했습니다.

직접 프롬프트나 문체 린터와의 항목별 차이는 장단점과 대안 비교에 정리했습니다.

• AI로 초안을 쓰고 사람이 이름을 걸고 내보내는 글: 블로그, 공지, 뉴스레터, 릴리스 노트처럼 독자의 신뢰가 중요한 글은 AI 습관 하나가 글 전체의 인상을 깎습니다.
• 같은 종류의 글을 반복해서 쓰는 경우: 매주 쓰는 릴리스 노트나 사내 공지처럼 반복되는 글은 기준표를 한 번 설치해 두는 효과가 큽니다.
• 문서 저장소를 에이전트로 관리하는 경우: File 모드는 코드 블록과 링크를 건드리지 않으므로 README, docs/ 같은 기술 문서에 바로 쓸 수 있습니다.
• 내 문체를 지키고 싶은 경우: 샘플을 주면 그 문체를 기준으로 고치므로 "AI가 다듬은 글"이 아니라 "내가 쓴 글"에 가까워집니다.
• 좋은 글쓰기 기준을 배우고 싶은 경우: 26개 패턴의 Before·After 예시 자체가 짧은 문장 작법 교재입니다. 설치하지 않고 SKILL.md를 읽기만 해도 얻는 것이 많습니다.

• AI 탐지기를 통과하는 것이 목적일 때: Humanizer는 그 목적으로 설계되지 않았고, 공개된 실험에서도 탐지율은 거의 바뀌지 않았습니다.

  예: 과제나 지원서를 탐지기에 통과시키려고 Humanizer를 쓰는 것은 목적에 맞지 않고, AI 사용 공개 규칙이 있는 곳이라면 규칙 위반 문제도 따로 생깁니다.

• 원래 사람이 쓴 글: Humanizer는 흔적이 여러 개 겹칠 때를 신호로 봅니다. 사람이 공들여 쓴 글에 돌리면 작성자가 일부러 쓴 대시나 반복까지 지워 개성을 깎을 수 있습니다.
• 한두 문장짜리 짧은 텍스트: 슬랙 메시지 한 줄, 버튼 문구 같은 짧은 글은 Skill 전체(약 5,200단어)를 컨텍스트에 올리는 비용이 고치는 이득보다 큽니다.
• 형식이 정해진 문서: 법률 문서, 표준 양식, 인용문처럼 표현 자체를 바꾸면 안 되는 글은 대상이 아닙니다. Skill도 인용·제목·고유명사는 건드리지 않도록 되어 있습니다.
• 스타일 가이드가 이미 강하게 정해진 조직: 사내 스타일 가이드가 대시나 굵은 글씨 라벨을 요구한다면 Humanizer의 규칙과 충돌합니다. 이때는 Humanizer를 그대로 쓰기보다 팀 규칙에 맞춘 사본이나 문체 린터가 낫습니다.

  예: 모든 릴리스 노트 항목을 "기능: 설명" 형식으로 쓰는 팀이라면 §19(굵은 글씨 라벨)가 매번 그 형식을 풀어 버립니다.

한 문장으로

Humanizer는 AI가 쓴 글에 반복해서 나타나는 습관을 강도순 26개 패턴과 사실 보존 규칙, 초안 → 점검 → 최종본 절차로 찾아 고치기 위한 에이전트 Skill입니다.

이것만 기억하기

1. 왜 사용하는가?

   • "사람처럼 써줘"라는 막연한 요청 대신, 근거 있는 기준표로 AI 글쓰기 습관을 찾아 고치기 위해서입니다.

2. 어떤 문제를 해결하는가?

   • "X가 아니라 Y" 대비, 한 줄 마무리, 3개 나열, 과장된 의미 부여, 챗봇 인사말처럼 독자가 AI 글이라고 느끼는 지점과, 다시 쓰면서 가짜 사실이 끼어드는 문제입니다.

3. 어떻게 동작하는가?

   • 에이전트가 SKILL.md를 읽고, 흔적 표시 → 초안 → 점검 → 최종본 순서로 다시 씁니다. 결과물의 형태는 붙여넣기, File, Embedded 모드에 따라 달라집니다.

4. 실제 프로젝트에서는 어디에 사용하는가?

   • 블로그와 공지 원고, docs/ 같은 문서 파일, PR 설명·커밋 메시지·릴리스 노트, 팀 리뷰 흐름에 씁니다.

5. 언제 사용하지 않는가?

   • AI 탐지기 통과가 목적일 때, 원래 사람이 쓴 글, 한두 문장짜리 글, 표현을 바꾸면 안 되는 문서에는 맞지 않습니다.

Humanizer를 이루는 개념(Skill, 기본 선택이라는 원인, 26개 패턴과 강도, 4단계 절차, 사실 보존, Voice, 출력 모드)이 각각 무엇이고 어떻게 맞물려 동작하는지 다룹니다.

용어 한눈에 보기

1. Skill (프롬프트 한 파일로 된 도구)

쉽게 설명하면

신입 편집자에게 건네는 "교정 매뉴얼 한 권"과 같습니다. 매뉴얼은 평소에는 책장에 꽂혀 있다가, 원고 교정 일을 맡을 때 펼쳐 봅니다. Humanizer는 그 매뉴얼 자체이고, 실제로 교정하는 사람은 여러분이 쓰는 에이전트(Claude Code, Codex 등)입니다.

사용하는 에이전트별 설치 방법, 프로젝트 단위 설치, 가장 간단한 첫 실행, 설치할 때 자주 헷갈리는 부분을 다룹니다.

설치

Humanizer는 빌드나 의존성이 없는 Skill이므로, 설치는 "SKILL.md를 에이전트가 찾는 위치에 두는 것"입니다. 쓰는 에이전트에 맞는 방법 하나를 고르면 됩니다.

방법 1. Claude Code 플러그인 (Claude Code 2.1.142 이상)

/plugin marketplace add blader/humanizer
/plugin install humanizer@humanizer

저장소 자체가 마켓플레이스(.claude-plugin/marketplace.json)이자 플러그인(.claude-plugin/plugin.json)입니다. plugin.json의 "skills": ["./"]가 저장소 루트의 SKILL.md를 가리킵니다. 플러그인으로 설치하면 명령 이름에 네임스페이스가 붙어 /humanizer:humanizer가 됩니다.

방법 2. Skills CLI (Codex, 이전 버전 Claude Code, 기타 에이전트)

# Codex
npx skills add blader/humanizer --global --agent codex

# Claude Code 2.1.142 미만
npx skills add blader/humanizer --global --agent claude-code

pnpm dlx skills add blader/humanizer --global --agent codex

skills는 Vercel Labs가 관리하는 범용 Skill 설치 CLI입니다. 저장소를 받아 각 에이전트의 Skill 폴더에 SKILL.md를 넣어 줍니다. 이 방법으로 설치하면 명령 이름은 /humanizer입니다.

방법 3. Skills CLI가 지원하는 모든 에이전트에 한 번에

npx skills add blader/humanizer --global --agent '*'

Gemini CLI, GitHub Copilot, Windsurf 등 Skills CLI가 아는 에이전트 전부에 설치됩니다. 실제로 쓰지 않는 에이전트에도 들어가므로, 보통은 쓰는 에이전트만 지정하는 편이 관리하기 쉽습니다.

방법 4. Claude.ai와 Claude Desktop

GitHub에서 으로 저장소를 내려받아 설정의 Skill 업로드 화면에 올립니다. 2.11.2부터 저장소 안에 symlink가 없어서 GitHub가 만들어 주는 소스 ZIP을 그대로 올리면 됩니다. 예전 글에 나오는 별도 릴리스 파일은 이제 쓰지 않습니다.

AI로 쓴 기술 블로그 초안을 내 문체 샘플에 맞춰 다듬는 과정과, 기능 출시 공지에서 사실이 바뀌지 않았는지 확인하는 과정을 다룹니다.

예제 1. 기술 블로그 초안을 내 문체로 다듬기

요구사항

사내 기술 블로그에 "결제 API 재시도 로직을 고친 이야기"를 올려야 한다. 초안은 Claude로 빠르게 받았는데, 읽어 보니 남이 쓴 글 같다. 내가 예전에 쓴 글의 말투로 바꾸고 싶다. 단, 장애 시각·재시도 횟수·결과 수치는 초안 그대로여야 한다.

구현

먼저 초안을 확인합니다. 흔적이 어디에 있는지 미리 알아 두면 결과를 검토하기 쉽습니다.

## 🚀 결제 재시도, 이제는 다르게

결제 시스템에서 재시도는 단순한 기술적 선택이 아니라, 사용자 신뢰의 문제입니다.
지난 3월 14일, 저희는 PG사 응답 지연으로 약 40분간 결제 실패가 이어지는 장애를 겪었습니다.

그렇다면 무엇이 문제였을까요? 바로 재시도 로직이었습니다.

기존 로직은 실패하면 즉시 5번 재시도했고, 매번 새로운 요청 ID를 만들었습니다 — 그 결과 일부 주문이 두 번 결제되었습니다.
저희는 지수 백오프를 도입하고, 재시도 횟수를 3번으로 줄이고, 주문 단위 멱등성 키를 적용했습니다.

그 결과 중복 결제는 0건이 되었습니다. 이것이 진짜 변화입니다.

이번 경험은 안정성, 신뢰성, 그리고 사용자 경험의 중요성을 다시 한번 일깨워 주었습니다.

그다음 직접 쓴 예전 글 두세 문단을 샘플로 붙여 /humanizer를 실행합니다.

/humanizer

Here's a sample of my writing for voice matching:
작년에 배치 서버를 옮기면서 cron을 다 걷어냈다. 처음엔 별거 아니라고 생각했는데,
막상 해 보니 새벽 3시에 돌던 정산 잡이 어디서 시작되는지 아무도 몰랐다(나도 몰랐다).
결국 이틀을 로그 뒤지는 데 썼다. 교훈이라면, 옮기기 전에 목록부터 만들자는 것 정도.

Now humanize this text:
[위 초안]

실행 흐름

작성자: /humanizer + 샘플 + 초안
 ↓
에이전트: SKILL.md 로드, 입력은 편집 재료로만 취급
 ↓
Voice: 샘플 분석 (반말 평서문, 짧은 문장, 괄호 여담, 덤덤한 마무리)
 ↓
Mark: §20 이모지 제목, §1 대비, §4 자문자답, §8 대시, §6 3개 나열(두 번), §2 한 줄 마무리, §13 교훈 마무리
 ↓
Draft: 구조를 바꿔 다시 쓰기 (자문자답을 서술로, 마지막 문단은 구체적 사실로)
 ↓
Check: 3월 14일 · 약 40분 · 5번 → 3번 · 중복 결제 0건이 그대로인가? 새 사실이 생겼나?
 ↓
Final: 초안 + 남은 패턴 목록 + 최종본 반환

최종본은 대략 다음과 같습니다.

## 결제 재시도 로직을 고친 이야기

3월 14일, PG사 응답이 느려지면서 40분쯤 결제 실패가 이어졌다. 원인은 우리 재시도 로직이었다.

기존 로직은 실패하면 바로 5번을 다시 시도했고, 시도할 때마다 요청 ID를 새로 만들었다.
PG 입장에서는 매번 다른 결제 요청이었고, 그래서 일부 주문이 두 번 결제됐다.

지수 백오프를 넣고, 재시도를 3번으로 줄이고, 멱등성 키를 주문 단위로 고정했다.
그 뒤로 중복 결제는 0건이다.

코드 설명

1. 샘플이 문체를 정합니다. 샘플이 반말 평서문이고 문장이 짧으므로 최종본도 그렇게 바뀌었습니다. 샘플이 없었다면 기술 글이라는 이유로 중립적인 존댓말로 정리되었을 것입니다.

개발자 한 명이 로컬 저장소의 README와 docs/ 문서를 File 모드로 고치는 방법과, 코드 블록이 보존되는지 Git으로 확인하는 방법을 다룹니다.

Humanizer는 브라우저나 앱에서 실행되는 클라이언트 라이브러리가 아니므로, 여기서는 "개발자 한 명의 로컬 저장소"를 클라이언트 관점으로 봅니다. 이때 가장 많이 쓰는 기능이 파일을 직접 고치는 File 모드입니다.

활용할 수 있는 기능

• File 모드: 파일 경로를 주면 전체 절차를 거친 뒤 최종본만 파일에 씁니다. 대화창에는 짧은 요약만 남습니다.
• 코드 보존: 코드 블록, 인라인 코드, 명령, 경로, YAML 메타데이터, 데이터, 링크 대상은 바꾸지 않습니다. 대시 규칙(§8)도 코드·명령·경로·URL 안의 대시와 하이픈은 건드리지 않습니다.
• 기술 문서용 목소리: 샘플이 없으면 글의 종류에서 목소리를 정하므로, 기술·참고 문서는 의견이나 여담 없이 중립적이고 평이하게 정리됩니다.
• 문서 특유의 흔적: 기술 문서에서 특히 자주 잡히는 패턴은 다음과 같습니다.
  • §19 굵은 글씨 라벨 목록 ("- Performance: 성능이 향상되었습니다")
  • §20 장식적인 제목 (이모지, 모든 단어 대문자, "한 화면에 보는 결정" 같은 연출형 제목)
  • §24 제목을 첫 문장에서 반복 ("## 성능" 다음 "성능은 중요합니다.")
  • §25 주제 대신 문서 자체를 설명 ("이 함수는 기존 방식을 대체하기 위해 추가되었습니다", "아래 표는 ~를 비교합니다")
  • §11 주어 없는 문장 ("별도 설정 필요 없음")

실제 예제

AI로 쓴 docs/caching.md가 있다고 하겠습니다.

---
title: 캐시 레이어 가이드
owner: platform-team
---

# 🚀 Caching Layer Deep Dive

## 개요

캐싱은 중요합니다.

이 문서는 기존의 매 요청 DB 조회 방식을 대체하기 위해 추가된 캐시 레이어를 설명합니다.
캐시 레이어는 단순한 성능 개선 도구가 아니라, 서비스 안정성의 핵심 축입니다.

- **속도:** 응답 속도가 크게 향상됩니다.
- **비용:** DB 비용이 절감됩니다.
- **안정성:** 트래픽 급증에도 안정적으로 동작합니다.

## 설정

별도 설정 필요 없음. 아래와 같이 클라이언트를 생성하면 됩니다 — 기본 TTL은 60초입니다.

```ts
// TTL은 초 단위 -- 0이면 캐시하지 않음
export const cache = createCache({ ttlSeconds: 60, namespace: 'api-v2' });
```

자세한 옵션은 [캐시 옵션 문서](./cache-options.md)를 참고하세요.

팀 저장소에 Humanizer를 같은 버전으로 고정해 공유하는 방법, PR 설명·커밋 메시지에 Embedded 모드로 연결하는 방법, 그리고 기술 블로그 팀에 실제로 도입하는 과정을 다룹니다.

팀·운영 환경에서의 활용

Humanizer는 서버 런타임에서 import하는 라이브러리가 아닙니다. 그래서 "서버에서의 활용" 대신, 여러 사람이 같은 기준으로 글을 다듬도록 저장소와 리뷰 흐름에 넣는 방법을 봅니다.

활용 사례

• 버전 고정 공유: Skill을 프로젝트 범위로 복사 설치하고 저장소에 커밋해서, 팀원 모두의 에이전트가 같은 버전의 SKILL.md를 읽게 합니다.
• Embedded 모드 연결: 저장소의 에이전트 지시 파일(CLAUDE.md, AGENTS.md)에 "PR 설명과 커밋 메시지는 Humanizer를 거친다"를 적어, 다른 작업 중에 최종본만 받아 쓰게 합니다.
• 팀 문체 샘플: 팀이 좋다고 합의한 글 두세 문단을 파일로 두고, Voice 샘플로 항상 같이 넘깁니다.
• 팀 규칙 래퍼 Skill: Humanizer 원본은 그대로 두고, 팀 고유 규칙(용어집, 존댓말, 예외)을 담은 작은 Skill이 Humanizer를 부르게 합니다.
• 기계적 검사는 CI로: Humanizer는 모델이 따르는 지침이라 결과가 매번 같지 않습니다. "본문에 대시 금지"처럼 기계로 확인할 수 있는 몇 가지는 별도 스크립트로 CI에서 검사합니다.

애플리케이션 구조

Humanizer가 "코드의 어느 계층에 들어가느냐"가 아니라, 글이 만들어져 배포되는 흐름의 어느 단계에 개입하느냐로 보는 것이 맞습니다.

작성자 / 에이전트 (초안 작성)
 ↓
팀 래퍼 Skill (팀 문체 샘플 + 용어집 + 예외 규칙)
 ↓
Humanizer Skill (흔적 표시 → 초안 → 점검 → 최종본)
 ↓
저장소 (posts/*.md, PR 설명, 커밋 메시지)
 ↓
CI (기계적으로 확인 가능한 흔적만 검사)
 ↓
사람 리뷰 (사실 대조, 최종 승인)

실제 코드

팀 저장소에 같은 버전 고정하기

# --global 없이 설치하면 프로젝트 범위, --copy는 symlink 대신 파일 복사
npx skills add blader/humanizer --agent claude-code codex --copy -y

git add .claude/skills/humanizer .agents/skills/humanizer skills-lock.json
git commit -m "chore: humanizer skill 프로젝트 범위로 추가"

Humanizer의 장점과 단점, 그리고 직접 프롬프트·문체 린터·상용 서비스 같은 대안과 비교해 상황별로 무엇을 고를지 다룹니다.

"자연스럽게 다듬어줘"라고 직접 요청할 때와 무엇이 달라지나

코드가 없는 라이브러리의 "소스 코드"인 SKILL.md가 어떤 순서와 형식으로 쓰였고 왜 그렇게 설계되었는지, 그리고 프롬프트 한 파일을 검증 스크립트와 CI로 어떻게 관리하는지 다룹니다.

저장소는 무엇으로 이루어져 있는가

Humanizer 저장소의 AGENTS.md는 이 프로젝트를 한 문장으로 정의합니다. "SKILL.md는 에이전트가 읽는 프롬프트이고, 메타데이터 아래의 프롬프트가 곧 제품이다." 나머지 파일은 모두 이 한 파일을 배포하고 검증하기 위해 있습니다.

humanizer/
├── SKILL.md                      # 제품 본체. 유일한 Skill 파일 (약 400줄, 약 5,200단어)
├── README.md                     # 설치·사용법, 패턴 표 (SKILL.md와 패턴 이름이 일치해야 함)
├── CHANGELOG.md                  # 버전별 변경 기록. 옛 기록은 당시 패턴 번호를 그대로 유지
├── AGENTS.md                     # 이 저장소를 고치는 에이전트를 위한 규칙
├── LICENSE                       # MIT
├── .claude-plugin/
│   ├── plugin.json               # Claude 플러그인. "skills": ["./"]로 루트 SKILL.md를 가리킴
│   └── marketplace.json          # 저장소를 Claude 마켓플레이스로 추가할 수 있게 함
├── .cursor-plugin/
│   └── plugin.json               # Cursor 플러그인. skills 경로를 일부러 비워 루트 SKILL.md를 읽게 함
├── agents/
│   └── openai.yaml               # OpenAI 호환 에이전트용 표시 이름, 짧은 설명, 기본 프롬프트
├── scripts/
│   └── validate-package.py       # 패키지 검증기 (표준 라이브러리만 사용)
└── .github/workflows/
    └── validate.yml              # PR과 main 푸시마다 검증기 + Skill 탐색 + 플러그인 검증 실행

GitHub가 저장소 언어를 Python으로 표시하는 것은 이 검증기 때문입니다. 실제로 사용자에게 전달되는 것은 Markdown 한 파일입니다.

SKILL.md를 위에서 아래로 읽기

SKILL.md는 다음 순서로 되어 있습니다. 순서 자체가 설계입니다.

사용하면서 신경 써야 할 사실 정확성·모델 의존성·비용·보안·윤리 문제와, 처음 쓸 때 자주 헷갈리는 질문을 다룹니다.

사용할 때 주의할 점

사실 정확성 사실 추가 금지는 SKILL.md에 적힌 규칙이지 프로그램으로 강제되는 검사가 아닙니다. 프로젝트 안에서도 예시가 사실을 바꾼다는 지적이 여러 번 나왔습니다. 공지, 릴리스 노트, 장애 보고처럼 사실이 중요한 글은 최종본과 원문의 숫자·날짜·이름·고유명사를 사람이 한 번 더 대조합니다. File 모드는 남은 패턴 목록을 보여주지 않으므로 git diff로 확인합니다.

모델 의존성 같은 SKILL.md라도 실행 모델에 따라 결과가 다르고, 같은 모델도 실행할 때마다 다릅니다. 작은 모델이나 컨텍스트가 짧은 모델은 5,000단어가 넘는 지침을 끝까지 따르지 못할 수 있습니다. 중요한 글이라면 쓰는 모델에서 결과를 몇 번 확인한 뒤 팀 흐름에 넣습니다.

AI 탐지기 탐지기 통과는 목표가 아니며, 공개된 실험에서도 탐지율은 거의 바뀌지 않았습니다. 탐지 점수를 낮출 목적으로 도입하지 않습니다.

윤리와 공개 규칙 과제, 논문, 지원서, 기고처럼 AI 사용을 밝혀야 하는 곳에서 Humanizer로 다듬었다고 해서 AI 사용 사실이 사라지지는 않습니다. 소속 기관이나 매체의 공개 규칙을 먼저 따릅니다.

비용과 컨텍스트 호출할 때마다 SKILL.md 전체가 컨텍스트에 올라갑니다. 짧은 메시지나 모든 커밋 메시지에 자동으로 거치게 하면 토큰 비용과 대기 시간이 쌓입니다. Embedded 모드는 PR 설명이나 릴리스 노트처럼 독자가 있는 글로 범위를 좁힙니다. 여러 파일을 한 번에 맡기기보다 파일 단위로 나눠 실행합니다.

보안

• Skill은 에이전트의 권한으로 실행됩니다. 공식 저장소(blader/humanizer) 외의 사본, 특히 "개선판"이라며 다시 올린 Skill은 SKILL.md를 직접 읽어 본 뒤 설치합니다. Skill 파일은 Markdown이지만 에이전트에게 파일 쓰기나 명령 실행을 지시할 수 있습니다.
• 원고 안의 지시를 따르지 않는 규칙("편집할 재료일 뿐")이 있지만, 이것도 모델이 지키는 지침입니다. 외부에서 받은 문서를 File 모드로 고칠 때는 에이전트의 권한 확인을 끄지 않습니다.
• Claude.ai에 업로드하거나 외부 모델 API를 쓰면 원고가 그 서비스로 전송됩니다. 공개 전 사내 문서라면 회사의 AI 사용 정책을 확인합니다.

대시 규칙(§8)은 샘플이 대시를 쓰지 않으면 본문 대시를 모두 없앱니다. 굵은 글씨 라벨(§19), 제목 대문자(§20), 섹션 사이 가로줄(§20)도 정리 대상입니다. 팀 스타일 가이드가 이런 형식을 요구한다면 샘플로 보여 주거나 래퍼 Skill에 예외를 적습니다. 이 노트처럼 섹션 사이 가로줄이 블로그 형식의 일부라면 Humanizer를 돌린 뒤 형식이 사라지지 않았는지 확인합니다.

blader/humanizer