기여하기

기여하기

kimchi-claude의 규칙표와 코드를 고치는 방법입니다. 저장소의 불변식과 브랜치 규칙은 AGENTS.md에, 설계 판단과 근거는 설계 문서에 있습니다.

오탐·놓친 표현 제보

규칙이나 훅이 문제없는 문장을 잘못 지적했다면 오탐 이슈를, 규칙표에 없어서 걸러지지 않은 어색한 표현을 찾았다면 놓친 표현 이슈를 열어 주십시오. 이슈 양식에서 걸린 문장과 근거를 함께 적어 주시면 규칙표에 반영하기 쉽습니다.

이슈를 열거나 수정하면 봇이 자동으로 현재 규칙(main, 즉 최신 릴리스 기준)으로 그 문장을 재현해 코멘트를 답니다. 재현 여부에 따라 reproduced/not-reproduced 라벨이 붙으니, 코멘트를 먼저 확인한 뒤 필요하면 규칙표를 고쳐 PR을 올려 주십시오.

규칙 추가

rules/ 안의 마크다운 표에 한 줄을 넣고 다시 생성하면 됩니다. 한 줄은 이렇게 생겼습니다.

| 원어 | 쓰지 말 것 | 쓸 것 | 이유 | 검사 | 순위 | |—|—|—|—|—|—| | thin contract | 얇은 계약 | 낮은 결합도 | 은유를 직역해 뜻이 사라졌다 | 치환 | 핵심 |

이유 칸은 규칙 파일의 관례대로 한다체로 씁니다.

표기·맞춤법·띄어쓰기 규칙은 이유 칸 맨 앞에 [표기] 를, 외래어 표기 규칙은 [외래어] 를 붙입니다(뒤에 한 칸 띄웁니다). 린터는 이 표지로 낱말 경계 검사를 정합니다. [표기]는 왼쪽 경계를 보지 않아 “확인해야합니다”의 “해야합니다”도 잡고, [외래어]는 양쪽을 다 보지 않아 “메세지큐”의 “메세지”도 잡습니다. 표지는 출력 스타일과 훅 메시지에서는 떼고 보여 줍니다.

npm run build   # output-styles/natural-korean.md 를 다시 만든다
npm test        # 생성물이 최신인지 확인하고 시험을 돈다

검사 칸에는 세 값 중 하나를 씁니다. 린터가 할 수 있는 일이 값마다 다릅니다.

값	뜻
치환	문자열로 잡을 수 있고, 쓸 것으로 그대로 바꿔도 뜻이 상하지 않습니다. 자동 교정 대상입니다
정규식	잡을 수는 있지만 문맥을 봐야 고칠 수 있어서 경고만 합니다
프롬프트	문자열로는 잡을 수 없어서 출력 스타일로만 막습니다

순위(핵심/보통/참고)는 출력 스타일에 무엇을 담을지 정하는 기준입니다. 규칙이 수백 개로 늘어나도 스타일 본문은 상한까지만 담습니다.

영어 낱말 뒤 조사 고르기

한국어 조사는 앞말의 **발음**을 따릅니다. 철자가 아닙니다. 그래서 `commit을`이 맞고 `commit를`은 틀립니다. "커밋"의 끝소리에 ㅅ 받침이 있기 때문입니다. 이 판정은 규칙표가 아니라 `hooks/lib/particle.mjs`가 합니다. 영어 낱말을 한 줄씩 표에 넣는 방식으로는 다 덮을 수 없습니다. | 입력 | 고친 결과 | 이유 | |---|---|---| | `commit를` | `commit을` | 커밋 — ㅅ 받침 | | `cache을` | `cache를` | 캐시 — 받침 없음 | | `3을` | `3을` | 삼 — ㅁ 받침 | | `S3을` | `S3를` | 에스쓰리 — 글자가 붙으면 숫자를 영어로 읽습니다 | | `SQL를` | `SQL을` | 에스큐엘 — 두음자어는 글자로 읽습니다 | | `JSON로` | `JSON으로` | 제이슨 — 낱말로 읽는 두음자어입니다 | | `kubernetes를` | 손대지 않음 | 읽는 법을 모릅니다 | 마지막 줄이 설계 원칙입니다. **모르면 판정하지 않습니다.** 잘못 고치는 편이 안 고치는 편보다 나쁩니다.

자동 교정의 조사 함정

치환에는 한국어만의 함정이 있습니다. "얇은 계약**을** 유지"에서 "얇은 계약"을 "낮은 결합도"로 바꾸면 "낮은 결합도**을** 유지"가 됩니다. 받침이 사라졌기 때문입니다. 그래서 자동 교정은 바꾸기 전에 **마지막 음절의 받침 유무가 같은지** 먼저 봅니다. 받침이 달라지는데 뒤에 조사가 붙어 있으면 바꾸지 않고 경고만 합니다.

나쁜 예를 인용할 때 검사에서 빼기

문체 가이드나 규칙 문서는 나쁜 예를 일부러 인용합니다. 이런 문장까지 지적하면 문서를 쓸 수 없으니 표시를 달아 검사에서 뺍니다. ```markdown 문서 전체를 뺀다 | 나쁜 예 | 좋은 예 | 이 구간만 뺀다 | 얇은 계약 | 낮은 결합도 | 얇은 계약이라고 쓴 줄 이 줄만 뺀다 ``` 이 저장소에서는 `rules/`와 설계 문서가 이 표시를 씁니다. 나머지 한국어 문서는 모두 자체 린터를 통과해야 하고, `npm test`의 `dogfood` 시험이 확인합니다. README와 이 문서도 예외가 아닙니다.

개발

의존성이 없어서 Node만 있으면 됩니다.

npm test          # 생성물 최신 여부 확인 + 단위 시험
npm run build     # 출력 스타일 다시 생성
npm run art       # README 그림 다시 생성. 문구는 훅과 린터가 만든다
npm run score -- <file>   # 글 하나를 린터로 채점
npm run eval      # claude plugin eval. 자식 claude 를 띄워 토큰이 든다

손으로 말투를 잴 때 사용자 설정이 섞이지 않게 하는 방법은 evals/README.md에 적어 두었습니다.

풀 리퀘스트를 올리면 GitHub Actions가 같은 npm test를 돌립니다. 로컬에서 통과했더라도 확인해 주십시오.

풀 리퀘스트마다 pr-version 워크플로가 버전·제목 형식도 함께 확인합니다. package.json과 .claude-plugin/plugin.json의 버전이 같은지, base 브랜치보다 올라갔는지, 마지막 커밋 제목이 0.x.y — <합니다체 한 문장> 형식인지를 봅니다 (AGENTS.md 참고).