# claude-seo 한국어 패치

[`AgriciDaniel/claude-seo`](https://github.com/AgriciDaniel/claude-seo)(GitHub ★15,000)의
콘텐츠 품질 검사기를 **한국어에서 동작하게** 고치는 패치입니다.

원본은 한국어 글을 읽지 못합니다. 그런데 오류를 내지 않고 **높은 점수**를 줍니다.
읽지 못하니 감점할 게 없어서입니다.

---

## 문제

`scripts/content_quality.py:144`

```python
_TOKEN_RE = re.compile(r"[A-Za-z][A-Za-z'\-]*")
```

ASCII 알파벳만 매칭합니다. 한국어·일본어·중국어·아랍어·러시아어·태국어는
**토큰 0개**로 세어집니다.

그 결과 점수 계산식이 이렇게 무너집니다.

```
overall = (100-filler)×0.25 + (100-ai)×0.25 + density×100×0.25
          + (100-rep)×0.15 + min(100, tokens/10)×0.10
```

- `filler`, `ai_pattern`, `repetition` → 걸릴 토큰이 없어 전부 **0** → 앞 세 항이 만점
- `density` → 분모가 `n_tokens`인데 그게 14 같은 값이라 **오히려 부풀려짐**
- 남는 건 길이 보너스뿐인데 가중치가 0.10

→ 합계 85~90점. **못 읽을수록 높은 점수가 나옵니다.**

### 실측 (같은 글의 한/영 번역본 8쌍)

같은 필자, 같은 템플릿, 같은 내용. 언어만 다른 글 8쌍으로 측정했습니다.

| | 평균 점수 | 토큰 합계 |
|---|---|---|
| 한국어판 | **86.6** | 644 |
| 영문판 | 78.8 | 6,231 |

**8쌍 전부 한국어판이 높았습니다.** 최악은 `dashdock-launch` 한국어판 —
1,685자에서 토큰이 **14개**로 세어졌습니다.

글자당 인식률로 보면 영어 0.168 / 한국어 0.026. 영어의 0.168은 정상값입니다
(영단어 평균 4.7자 + 공백 ≈ 5.7자/단어 → 0.175). **영어에서는 제대로 작동하고
한국어만 안 되는 것**입니다.

---

## 고치는 것

1. **토크나이저에 비라틴 문자 추가** — 한글·가나·한자·키릴
2. **조사 절삭** — `클로드는`·`클로드를`·`클로드가` → `클로드`
   같은 낱말로 묶어야 반복·고유토큰 계산이 맞습니다
3. **한국어 어구 목록 추가** — AI 상투구 41개 + 군더더기 26개 (`ko-patterns.json`)

`information_density`는 **원본 그대로 둡니다.** 한글 고유명사를 흉내내려고
"반복 등장 낱말"을 세봤더니 반복이 특징인 슬롭 글이 오히려 밀도 만점을 받았습니다.
토크나이저가 고쳐지면서 분모가 정상화된 것만으로 원래 문제는 해결됩니다.

---

## 쓰는 법

준비물: Node.js. claude-seo가 이미 설치돼 있어야 합니다.

```bash
node patch-korean.mjs            # 적용
node patch-korean.mjs --check    # 적용 상태 확인
node patch-korean.mjs --revert   # 원복
```

원본을 `content_quality.py.orig`로 백업하므로 되돌릴 수 있습니다.
두 번 실행해도 안전합니다(멱등).

설치 경로가 다르면 환경변수로 지정합니다.

```bash
CLAUDE_SEO_CONTENT_QUALITY=<경로>/content_quality.py node patch-korean.mjs
```

> ⚠ claude-seo를 재설치하거나 업데이트하면 패치가 지워집니다. 다시 실행하세요.

---

## 효과

### 대조군 — 같은 내용의 "AI 슬롭" 문단을 영어·한국어로

| | 패치 전 | 패치 후 |
|---|---|---|
| 영어 슬롭 | 41점 (AI패턴 90) | **41점** — 변화 없음 |
| 한국어 슬롭 | 65점 (AI패턴 0) | **39점** (AI패턴 100) |

한국어 슬롭 39점이 영어 슬롭 41점과 거의 같아졌습니다.
같은 내용이면 같은 점수가 나오는 게 정상입니다.
**영어 결과가 그대로인 것도 중요합니다** — 원래 잘 되던 걸 망가뜨리지 않았습니다.

### 실제 글 8쌍

| | 패치 전 | 패치 후 |
|---|---|---|
| 한국어 토큰 합계 | 644 | **5,763** (8.9배) |
| 한국어 평균 점수 | 86.6 (부풀려짐) | **74.4** |
| 영문 평균 점수 | 78.8 | 78.8 (불변) |

실제 글에서는 오탐이 없었습니다 — AI패턴 0, 군더더기 0.

---

## 한계 — 솔직히 적어둡니다

- **조사 절삭이 형태소 분석이 아닙니다.** 규칙 기반이라 `나는`(대명사)의 `는`처럼
  조사가 아닌 걸 뗄 수 있습니다. 2글자 미만으로 줄면 원형을 유지하게 해뒀지만
  완벽하지 않습니다. 정확히 하려면 KoNLPy·Kiwi 같은 형태소 분석기가 필요한데,
  설치 부담이 커서 넣지 않았습니다.
- **`information_density`는 여전히 라틴 고유명사 + 숫자 기준**입니다.
  한국어 기술글은 고유명사가 대개 라틴(Claude·Firebase·GitHub)이라 상당수 잡히지만,
  순한국어 글에서는 낮게 나옵니다.
- **어구 목록은 제 글투 기준으로 고른 것**입니다. `ko-patterns.json`을 열어
  본인 글에 맞게 고치세요. 그러라고 JSON으로 뺐습니다.
- 이 패치는 `content_quality.py` 하나만 고칩니다. 다른 스크립트의 한국어 대응은
  확인하지 않았습니다.

---

## 알려진 원본 버그 (패치와 별개)

`content_quality.py`가 URL을 파일 경로로 취급합니다. 윈도우에서 크래시합니다.

```
OSError: [Errno 22] Invalid argument:
  'https:\jarvisstudio-blog.web.app\blog\local-memory-system'
```

다른 스크립트(`sitemap_discovery`·`drift_baseline`·`preload_check`)는 URL을 받는데
이것만 파일을 받습니다. 인자 규약이 스크립트마다 다릅니다.

---

## 라이선스

원본 claude-seo는 MIT입니다. 이 패치도 MIT로 씁니다. 마음대로 가져다 쓰세요.

측정 원자료와 전체 검증 기록: <https://jarvisstudio-blog.web.app/blog/>
자비스스튜디오 · <https://blog.naver.com/jarvisstudio>