Chore: 용어집 검사 에이전트 추가

[taejinchoi-cbnu]

새로운 기능으로 용어집 검사 기능을 추가했습니다.

요약

용어집 구글 시트를 기준으로 합의된 번역어를 사용하였는지 한/영 병기 표현이 문서 안에서 일치하는지 검사합니다.

같은 영어 용어가 서로 다른 한국어로 번역되는 표기 흔들림(예: property를 객체/프로퍼티, method를 메소드/메서드로 혼용)을 용어집 표준 또는 병기 표현으로 통일하도록 권고만 합니다(자동 수정 x).

약 1000줄이 추가된 것으로 보이지만 절반가량이 용어집 CSV 데이터이고, 실제 기능 Python 코드와 Markdown 문서는 500줄 정도입니다.

변경 파일

영역	파일
신규 에이전트	agents/glossary-validator.md
신규 스크립트	scripts/check_glossary.py, scripts/_text_utils.py
용어집 캐시	glossary/meta.json, glossary/sheet1.csv, glossary/sheet2.csv
규칙 문서	skills/.../references/glossary-guidelines.md
통합	skills/.../SKILL.md, README.md, scripts/check_spelling.py, .gitignore

검사 규칙 (둘 다 🟡 권고, 자동 수정 대상 x)

규칙 ID	검사 내용	예시
GLOSSARY-mismatch	한국어(영어) 병기에서 한국어가 용어집 표준어와 다름	객체(property) → 프로퍼티(property)
GLOSSARY-inconsistent	한 영어 용어를 문서 안에서 다른 한국어로 혼용	큐(queue) 병기 후 본문에 큐만 단독 등장 → 대기열 권고

• 오탐 방지를 위해 한국어(영어) 병기 패턴에만 적용합니다. 한국어 단독·영어 단독 등장은 검사하지 않습니다.
• GLOSSARY-inconsistent는 문서 안에서 한 번이라도 비표준(영어)로 병기되어 앵커된 표기의 단독 재등장만 검출합니다(설계상 앵커 한계 존재).
• 코드 블록(```)·인라인 코드(`)는 모든 검사에서 제외됩니다.
• 문맥상 표준과 다르게 옮기는 게 옳은 경우가 있어 강제하지 않고 권고만 하며 자동 수정 단계에서도 GLOSSARY-* 항목은 손대지 않고 수동 검토 표에만 노출합니다.

용어집 캐시 동작

• 용어집 2개 시트(일반 용어 / 기호·구두점)를 glossary/에 CSV로 캐시합니다.
• 실행 시 sha256 비교로 시트가 바뀐 경우에만 캐시를 갱신하고, 마지막 확인 후 TTL(24h) 이내면 네트워크 조회를 생략합니다.
• 네트워크 실패 시 기존 캐시로 계속 동작하며 보고서 푸터에 캐시 시각과 경고를 한 줄로 표기합니다.

테스트

1-js/05-data-types/04-array/article.md 를 test-data로 사용하였습니다.

전체 아티클 검사로 결과가 길어 중간 내용은 생략하였습니다.

용어집에는 deque가 양단 대기열로 되어 있지만

본문에는 데큐로 번역한 부분을 찾아내었습니다.

다만 위 예시와 같이 무조건 용어집과 일치 시키는 것이 정답이 아니라고 판단하여 자동 수정을 구현하지 않았습니다.

---

기존 파일 수정

용어집 검사를 붙이면서 기존 맞춤법 검사 코드도 일부 함께 손봤습니다.
(이 부분은 반영하지 않으셔도 괜찮습니다!)

1. 마크다운 전처리를 공유 모듈로 분리

• "검사하면 안 되는 부분"(코드 블록·인라인 코드·URL·링크·HTML·프런트매터)을 걷어내는 strip_non_korean_content()가 원래 check_spelling.py에만 있었습니다.
• 용어집 검사도 같은 전처리가 필요하여(코드 블록 안 큐(queue)를 잡으면 안 되므로) scripts/_text_utils.py로 빼고 두 스크립트가 공유합니다.

# check_spelling.py - 47줄짜리 인라인 함수 정의가 사라지고
from _text_utils import strip_non_korean_content

2. 줄 수 보존으로 줄번호 정확도 확보

• 용어집 검사는 위반의 줄번호를 보고합니다.
• 그런데 기존 전처리는 코드 블록 전체를 개행 하나로 치환해, 코드 블록 뒤 본문의 줄번호가 전부 밀리는 현상이 발생하였고 (10줄 블록 → 1줄이면 이후 9칸씩 어긋남) 이를 코드 펜스/프런트매터를 원래 줄 수만큼의 개행으로 치환해 해결하였습니다.

# 기존: 코드 블록을 \n 하나로 → 이후 줄번호가 밀림
content = re.sub(r'```[\s\S]*?```', '\n', content)

# 변경(_text_utils.py): 들어온 줄 수 = 나가는 줄 수
content = re.sub(
    r'^(`{3,})[^\n]*\n[\s\S]*?^\1[ \t]*$',
    lambda m: '\n' * m.group(0).count('\n'),
    content, flags=re.MULTILINE,
)

두 호출자의 요구가 달라(맞춤법은 토큰 경계용 '\n', 용어집은 위치 보존용 ' ') inline_replacement 인자로 분기합니다.

3. 맞춤법 검사기 버그 3건 수정

(a) 원문과 동일한 "교정" 오탐 제거

• hanspell이 가끔 원문과 똑같은 단어를 "고쳤다"고 내놓아 X → X 무의미 위반이 보고됐습니다.
• 그래서 이를 위반으로 append 하기 직전에 원문과 수정안이 같으면 등록하지 않고 그 항목을 통째로 건너뛰는 방식으로 수정하였습니다.

if original.strip() == suggestion.strip():
    # 원문 == 수정안 → 진짜 교정이 아님
    i += 1      # (설명 줄까지 이미 i+=1 했으니) 이 오류 블록을 마저 넘기고
    continue    # append를 건너뛰고 다음 줄로

(b) 도구 실패를 "오류 없음"으로 오인하지 않도록 수정

• hanspell은 위반을 stderr로, 교정된 본문을 stdout으로 내보내고 파서는 stderr의 원문 -> 수정안 줄만 위반으로 체크합니다.
• 변경 전에는 returncode를 확인하지 않아, "정상 + 위반 0건" 과 "hanspell이 실행 도중 실패"(stderr에 에러 메시지) 가 둘 다 violations 빈 목록(total: 0)으로 나왔고 보고서는 이 둘을 구분 못 해 후자를 "맞춤법 오류 없음 ✅"으로 둔갑시켰습니다.
• 그래서 판정 기준을 종료 코드 + stdout 유무로 분리했습니다.

# returncode != 0  : 프로세스가 비정상 종료(설치 실패·크래시 등)
# not stdout.strip(): 교정 본문조차 못 받음 = 정상 실행이 아님
# → 두 조건이 동시에 참일 때만 '진짜 실패'로 보고 에러를 내고 종료.
#   (정상 실행이면 위반이 0건이어도 stdout에 교정 본문이 실리므로 이 분기에 안 걸림)
if result.returncode != 0 and not result.stdout.strip():
    print(json.dumps({'error': f'hanspell failed (exit {result.returncode}): ...'}))
    sys.exit(1)  # 실패를 '오류 없음'으로 삼키지 않고, 호출자가 실패를 알도록 비정상 종료

(c) 불필요한 corrected_text 필드 제거

출력 JSON이 교정된 전체 본문(stdout)을 통째로 담고 있었으나 검증 보고서는 위반 목록만 사용합니다.
사용하지 않는 stdout을 제거해 출력을 가볍게 했습니다.

output = {
    'file': file_path,             # 검사한 파일 경로
    'violations': violations,      # 보고서가 실제로 쓰는 위반 목록
    'total': len(violations),      # 위반 개수(요약용)
    # 'corrected_text': result.stdout.strip(),  ← 삭제: 본문 전체 사본이라 불필요·용량만 큼
}

---

PS. 플러그인 메타데이터(.claude-plugin/plugin.json, marketplace.json)는 건드리지 않았습니다.
검토 후 두 파일의 version 올려주시면 감사하겠습니다! 🙏

[taejinchoi-cbnu]

@BHyeonKim PR 작성 완료 했습니다!

• 에이전트 추가는 설계와 테스트 시나리오 그리고 검토는 제가 작성 및 진행하고 구현 및 테스트 진행에서 claude를 사용하였습니다.
• 기존 파일 수정 부분은 에이전트 추가 과정에서 발견한 버그를 claude와 수정하였습니다.
• PR에 있는 설명이 부족하여 궁금한 점이 생기시면 디스코드 DM, 코멘트 편하신 곳으로 태그와 같이 연락 주시면 감사하겠습니다.

[BHyeonKim]

주중에 일정이 생겨서 주말에 리뷰하겠습니다.🥲

[taejinchoi-cbnu]

이번 주 아니더라도 천천히 해주셔도 됩니다!!
고생 많으셔요..👊👊