한린트 · hanlint

고칠 곳이 보이는 한국어 글쓰기. 글을 넣으면 번역투, 명사 나열, 이중 피동과 문서 안의 어긋남을 찾아 문장, 이유, 고친 본보기를 보여 준다. 앱의 화면 글 (버튼, 라벨, 상태) 은 프리셋 screen 으로 잰다. 낱말 자리에 놓인 문장과 화면 해설을 잡고, hanlint sheet 가 소스 전체의 글을 표 하나로 모은다. 직접 고친 내용을 비교하고, 다시 쓰고 싶은 고침은 뜻을 확인한 뒤 기억할 수 있다.

지금 글 다듬기 · 저장과 사용 안내 · 명령과 설정 · npm API · 변경 이력

설치 없이 바로 써 보기

브라우저 편집기를 열면 예문과 실제 지적이 바로 나온다. 계정이나 API 키 없이 검사할 수 있다.

1. 왼쪽 원문에 내 글을 붙여 넣거나 파일을 연다. 오른쪽에 검사 결과가 나온다.
2. 결과에 바로 표시된 이유와 본보기를 읽는다. 고침 버튼을 누르면 아래 수정본에 반영된다.
3. 원문이 미리 담긴 아래 수정본을 바로 다듬고 한 번 눌러 기록한다. 수정 전 원문은 보존된다.
4. 수정본 아래에 원문 보호와 기억할 고침이 나타난다. 다시 제안받을 고침은 뜻을 확인하고 승인한다.

다크·라이트는 시스템 설정을 따르고 우상단 버튼으로 전환한다. 선택한 테마는 다음 방문에도 유지된다.

검사는 브라우저 안에서 실행한다. 원고와 수정 이력은 브라우저에 보관되며, 선택하면 파일로 내보내거나 개인 GitHub 저장소에 저장할 수 있다. GitHub 보관에는 원고를 저장할 저장소의 Contents 읽기·쓰기 토큰이 필요하다. 토큰은 현재 탭의 메모리에만 둔다. 저장 한도, 가져오기와 충돌 처리는 저장과 사용 안내에 있다.

수정 이력, 재사용 승인, 공통 규칙 개선은 서로 다른 단계다. 수정본을 기록한 것만으로 정답 데이터가 되지는 않는다. 승인한 고침은 같은 원문과 문맥에서 제안하고, 공통 규칙에 기여할 사례는 따로 선택해 내보낸다.

내 작업에 맞는 입구

Python과 npm은 공통 명령에서 같은 규칙과 출력을 사용하며, 런타임 의존성이 없다. 브라우저는 같은 npm 엔진으로 검사한다. audit 의 색 지도, 초안 비교와 평가 도구 등 Python 전용 명령의 범위는 명령 안내에서 확인할 수 있다.

터미널에서 첫 검사

Python 3.11 이상이면 설치 후 파일을 검사한다.

pip install hanlint
hanlint 글.md
hanlint sheet src/ --preset screen

둘째 줄은 앱의 화면 글이다. 소스 파일의 한국어 문자열과 JSX 글을 표 하나로 내보내고, 표의 고침 칸을 채워 hanlint sheet apply 시트.md 로 되돌려 쓴다.

Node 18 이상이면 다음 명령으로 같은 검사를 실행한다.

npx hanlint 글.md

hanlint 또는 npx hanlint만 실행하면 현재 폴더의 마크다운 이름으로 만든 사용 예가 나온다. 파일 대신 폴더를 주면 하위 마크다운까지 검사한다.

hanlint 문서들/ --preset docs
hanlint fix 글.md
hanlint 글.md --format json

fix는 원본 파일을 고친다. 적용 뒤에도 남은 지적과 문장의 뜻을 확인한다. 일반 검사의 종료 코드는 error가 없으면 0, 있으면 1, 잘못된 인자나 실행 오류는 2다. notice는 읽고 판단할 참고 지적이다. 명령별 예외는 종료 코드 안내에 있다.

어떤 자리를 보여 주나

지적에는 위치와 규칙 이름, 인용 문장, 이유가 붙는다. 본보기는 글의 종류와 합니다체·한다체·해요체에 맞춰 보여 준다. 본보기는 다시 쓰는 방법을 설명하는 사례이며, 내 문장에 그대로 적용할 답은 직접 고른다.

hanlint explain nounPile
hanlint patterns --rule nounPile
hanlint rules --preset docs

한린트는 좋은 글의 점수나 등급을 내지 않는다. 맞춤법 전체, 사실의 진실, 의미 보존과 자연스러움은 판단하지 않는다. 어떤 결함을 결정적으로 검사하고 어떤 것은 다루지 않는지는 제품 경계에 정리돼 있다.

글 종류부터 고르기

블로그, 기술 문서, 보고서, 안내서, 수필, 소설, 백과와 대화에 맞는 프리셋이 있다. 문서 한 편에만 적용하거나 프로젝트 설정으로 남길 수 있다.

hanlint 명세.md --preset docs
hanlint init --preset docs
hanlint doctor

이미 문서가 쌓인 저장소에는 baseline으로 기존 지적을 기록하고 새 지적부터 볼 수 있다. 설정 방법과 주의할 범위는 프리셋, 예외와 baseline를 따른다.

Contract, Finding, Patch

모델이나 편집기에서 재작성 범위를 확인할 때 쓰는 공개 프로토콜이다.

예를 들어 H2 제목이 있는 초안에서 제목 수와 순서를 잠그려면 다음과 같이 실행한다.

hanlint contract init 초안.md --reader "개발자" --goal "라이브러리를 비교한다" --outline h2 --output contract.json
hanlint check contract.json 초안.md --format text

생성한 계약은 사람이 확인한다. 제목이 없는 자유 원고는 브라우저에서 바로 비교할 수 있다. 계약 버전, 보호 범위, 입력 조건과 실행 가능한 API 예제는 Reader Contract 프로토콜에 있다.

Python과 JavaScript에서

Python은 패키지의 공개 진입점에서 가져온다.

from hanlint import lintText

text = "결과가 저장되어집니다."
for finding in lintText(text):
    print(finding.line, finding.rule, finding.why)

JavaScript는 npm install hanlint 후 ESM으로 가져온다.

import { lintText } from "hanlint";

const text = "결과가 저장되어집니다.";
for (const finding of lintText(text)) {
  console.log(finding.line, finding.rule, finding.why);
}

브라우저 편집기는 main의 소스로 배포한다. 패키지는 릴리즈 때 배포하므로 시점이 다를 수 있다. 새 API의 배포 상태는 npm 안내와 Unreleased 변경를 함께 확인한다.

더 필요한 안내

작문 패킷과 평가 도구는 자연스러움 향상이 입증된 기본 작법으로 제공하지 않는다. 실험 결과와 적용 경계는 작문 축과 실측 기록에서 확인할 수 있다.

AI 에이전트의 한국어 작법

에이전트가 쓴 한국어에는 되풀이되는 버릇이 있다. 그 버릇을 사람 글과 견줘 세고, 그 가운데 기계가 잡을 수 있는 것만 규칙으로 만들었다. 재료는 사람이 쓴 한국어 155만 문장 (위키백과 본문과 지침과 토론, 사업보고서 네 장르) 과 기계가 쓴 360편이다.

src/hanlint/data/koreanProse.txt 의 앞 여섯 항목이 그 결과다. 아래 표의 일곱 관측에 사람과 기계의 비율을 붙였다. 표본을 늘려 차이가 사라진 원칙은 다시 본다. 일곱째 항목은 과잉 교정을 막는다. hanlint primer 가 첫머리에 싣고, 에이전트 훅에 hanlint hook --prime 을 걸면 세션 문맥에 실린다.

(천 문장당 비율. 사람 쪽은 네 장르 가운데 가장 높은 값이다. 마지막 줄만 글 안의 문장 비율이다)

일곱 관측 가운데 셋만 기계가 검사한다. 넷은 표층으로 정당한 용법과 못 가른다. ~인 셈이다 는 사람 글에서 걸린 실물이 전부 멀쩡했고 (10년 걸린 셈입니다), ~하는 편이 낫다 는 낱낱으로 짚으면 사람 글 3.31%를 때린다. 마지막 줄은 글 단위 지표라 낱낱의 문제를 피해 가는 듯했지만, 산문 8문장 이상인 사람 글 4,021편 가운데 30.2%에 긴 문장이 하나도 없다 (16문장 이상으로 좁혀도 19.5%). 사람 다섯에 하나를 때리는 것은 규칙이 아니다. 못 잡는 것을 못 잡는다고 적는 것이 이 표의 값이다.

증명

용어 보존 문장을 더하기 전 작법서를 읽고 쓴 글과 읽지 않고 쓴 글을 같은 주제로 만들어 출처를 가리고 견줬다. 현재 문구의 추가 효과는 따로 재지 않았다. 판정 조건은 돌리기 전에 적었다 (tests/_attempts/craftLift/probeCraftLift_log.md).

2회차는 1회차와 주제가 겹치지 않고 수를 합치지도 않은 독립 시험이다. 심판은 작법서도 규칙 이름도 받지 않았고 글의 차례는 과제마다 섞였다. 필자 교체 회차는 필자만 Codex 로 바꾸고 심판은 claude-opus-5 로 두었다. 같은 묶음을 받은 Codex 심판도 77 대 19 로 작법서 쪽을 골랐다 (tests/_attempts/codexCraft/probeCodexCraft_log.md).

이긴 이유가 두 회차 모두 한 곳을 가리킨다. 작법서를 읽은 글에서 숫자와 동작이 나온다 (수분 15퍼센트와 30퍼센트, 이슬점 12도, 가구를 5센티미터 띄우라). 작법서에 구체적으로 써라 는 줄이 없는데 그렇다. 4번이 헤지를 막으니 단언해야 하고, 단언하려면 근거가 손에 잡혀야 한다.

규칙의 오탐

규칙 둘을 사람 말뭉치 5,150편과 기계 360편에 걸어 잰 수다.

사람 글 800편에 한 편꼴로 걸린다. phraseRepeat 은 같은 꼴이 두 번 이상 나오고 글 안의 비율이 8% 를 넘을 때만 짚는다. 한 번 쓴 글은 조용하다.

다시 재기

python -X utf8 -B tests/_attempts/aiTells/probeAiTells.py many <기계 글 폴더>
python -X utf8 -B tests/_attempts/aiTells/probeDensity.py --ai <기계 글 폴더>
python -X utf8 -B tests/_attempts/aiTells/probeRuleReach.py --ai <기계 글 폴더>
python -X utf8 -B tests/_attempts/craftLift/probeCraftLift.py follow <시험 폴더>

말뭉치는 scripts/fetch/ 가 받는다 (위키백과는 --namespaces 로 장르를 고른다). 잰 것과 못 잰 것과 버린 것은 실측 기록에 있다. 이 방향에서 버린 것이 남긴 것보다 많다.

오탐과 개선 사례

정당한 문장이 잡혔으면 오탐 신고에 문장, 규칙 이름, 사용한 버전과 글 종류를 남긴다. 앞뒤 문맥이 필요하면 공개할 수 있는 범위로 함께 적는다. 브라우저에서 기록한 수정 사례도 선택해서 내보낼 수 있다. 기여 절차에 따라 사례를 검토한 뒤 규칙이나 본보기를 고친다.

English

hanlint is a Korean prose linter for Markdown, with a browser editor, Python package and Node.js CLI. It reports translationese, noun pile-ups, double passives and document inconsistencies, with locations, reasons and rewriting examples. The browser runs the same npm engine locally and keeps revision history separate from explicitly approved corrections.

Python and npm share deterministic rules with zero runtime dependencies. Reader Contracts can protect numbers, URLs, inline code, links and heading order. These checks do not judge truth, meaning or writing quality. Try the editor, use pip install hanlint, or run npx hanlint draft.md.

라이선스

npm과 브라우저에는 쉬운 말 자료의 파생물이 포함된다. 브라우저의 자료와 글꼴 고지는 자료 출처와 라이선스에서 읽을 수 있다. 기준 말뭉치 원문은 제품에 배포하지 않는다.