saramchae

한국어 · English

사람체 — 사람 + 글씨체. 사람이 실제로 쓰는 글의 모양.

문서에서 AI 티와 번역투를 걷어내는 Claude Code·Codex 스킬입니다. 영어 문장을 그대로 옮겨 놓은 듯한 한국어를 한국어로 되돌리는 쪽에 무게가 있습니다. 문장을 다시 쓰기 전에 스캐너가 문서를 먼저 재기 때문에, 인상이 아니라 짚을 수 있는 줄에 수정이 들어갑니다.

어떻게 바뀌나

세 가지를 예로 듭니다. 왼쪽은 손대기 전, 오른쪽은 손댄 뒤입니다.

1. 영어를 그대로 옮긴 한국어

본 문서는 캐시 무효화 전략에 있어서의 개선 방안을 다루고 있으며, 기존 방식이 가지고 있는 한계를 살펴보고 이를 개선하기 위한 방향성을 제시하고자 합니다.

따라서 버전 프리픽스 방식으로의 전환을 제안합니다. 이 방식은 단순히 캐시를 비우는 것이 아니라 키 자체를 분리하는 것이며, 배포 안정성 측면에 있어 중요한 역할을 할 것으로 판단됩니다.

결론적으로, 본 전환은 팀의 배포 문화에 있어 하나의 분수령이 될 것으로 시사됩니다. 궁금한 점이 있으시면 언제든 문의해 주시기 바랍니다.

캐시 무효화 방식을 어떻게 바꿀지 정리했습니다.

버전 프리픽스 방식으로 옮기려고 합니다. 캐시를 비우는 게 아니라 키를 분리하는 방식이라, 배포할 때마다 캐시가 통째로 날아가는 일이 없어집니다.

배포가 그만큼 덜 위험해집니다.

어체는 그대로 존댓말이고, 문단 수도 그대로입니다. 바뀐 것은 문장이 한국어로 읽히느냐입니다.

• 번역투 — ~에 있어서의, ~하고자 합니다, ~의 경우. 영어 구문을 그대로 옮겨 놓은 자리입니다
• 과장 — 분수령, 중요한 역할을 할 것으로 판단됩니다
• 챗봇 잔여물 — 궁금한 점이 있으시면 언제든 문의해 주시기 바랍니다
• 문장 전체를 감싼 볼드
• 126자짜리 문장은 둘로 쪼개졌습니다

주장은 하나도 바뀌지 않았습니다. 없던 숫자를 만들어 넣거나 어체를 갈아치우는 것은 교정이 아니라 다시 쓰는 것이라, 이 스킬은 하지 않습니다.

2. 어체가 섞이고 목록 끝맺음이 제각각일 때

• 테스트를 실행합니다
• 린트 통과 확인
• 스테이징 배포 후 동작 확인이 필요함
• 롤백 계획을 세운다

• 테스트 실행
• 린트 통과 확인
• 스테이징 배포 후 동작 확인
• 롤백 계획 수립

네 항목이 각각 합니다·명사형·필요함·세운다로 끝납니다. 한 목록 안에서 어미가 갈리면 읽는 사람이 항목마다 문장 구조를 다시 잡아야 합니다. 스캐너는 이걸 이렇게 짚습니다.

[1] register: 평서체 1 / 존댓말 1  — mixed. minority 존댓말, 1 of them (50%)
[5] lists: ... mixed endings 1

체크리스트는 명사형으로 맞추는 쪽이 짧고, 문장형 목록이라면 문장형으로 맞춥니다. 어느 쪽이든 하나로 통일하는 것이 요점이지 특정 어미가 옳은 것이 아닙니다.

3. 문장에 열거가 묻혀 있을 때

이번 스프린트에서는 먼저, 인증 모듈의 토큰 갱신 로직을 수정했고, 다음으로, 결제 API 의 타임아웃을 3초에서 10초로 늘렸으며, 마지막으로, 로그 수집기가 누락하던 워커 프로세스 로그를 포함하도록 설정을 변경하였습니다.

이번 스프린트에서 바꾼 것은 셋입니다.

• 인증 모듈의 토큰 갱신 로직 수정
• 결제 API 타임아웃 3초 → 10초
• 로그 수집기가 누락하던 워커 프로세스 로그 포함

125자 한 문장에 항목 셋이 먼저·다음으로·마지막으로로 이어져 있습니다. 목록이 될 것이 문장 안에 갇힌 경우고, 스캐너가 이름을 붙여 줍니다.

[3] long sentences: 1
    L1  125자 / 5 clauses  이번 스프린트에서는 먼저, 인증 모듈의 토큰 갱신 …
[5] lists: ... prose that reads as a list: L[1]

앞의 2번과 방향이 반대입니다. 불릿을 줄이는 것도 늘리는 것도 목표가 아니고, 내용에 맞는 모양을 찾는 것이 목표입니다. 나란한 항목 서넛은 목록이고, 이어지는 논증은 산문입니다.

실제 문서 한 편이 통째로 바뀌는 모습은 demo/ 에 있습니다. before.md 와 after.md, 그리고 스캐너가 무엇을 짚었는지 정리한 표가 들어 있습니다.

빠른 시작

클론할 필요 없습니다. 두 줄이면 됩니다.

# Claude Code — 세션 안에서
/plugin marketplace add keenkim1202/saramchae
/plugin install saramchae@saramchae

# Codex — 터미널에서
codex plugin marketplace add keenkim1202/saramchae
codex plugin add saramchae@saramchae

git clone https://github.com/keenkim1202/saramchae.git
cd saramchae
cp -r saramchae saramchae-ko ~/.claude/skills/     # Claude Code
cp -r saramchae saramchae-ko ~/.codex/skills/      # Codex

한 프로젝트에서만 쓰려면 <프로젝트>/.claude/skills/ 또는 <레포루트>/.agents/skills/ 에 넣습니다. 한 언어만 쓴다면 그쪽 디렉터리만 복사해도 됩니다.

다음 세션부터 인식합니다. 그다음 이렇게 부릅니다.

/saramchae-ko docs/design-note.md     # Claude Code
$saramchae-ko docs/design-note.md     # Codex

이름을 몰라도 됩니다. 이렇게 말해도 알아서 불립니다.

이 문서 사람이 쓴 것처럼 다듬어 줘 · 문체 다듬어 · AI 티 빼줘 · 가독성 검토

어느 쪽을 설치하나

한 언어만 쓴다면 그쪽만 복사해도 됩니다. 다만 한 문서에 둘 다 돌리지는 마세요.

무엇을 잡아내나

문서는 두 가지 방식으로 동시에 어긋나고, 읽는 사람은 둘을 같은 문제로 느낍니다. 그래서 양쪽을 함께 봅니다.

하나는 문체입니다. AI 어휘, 세 겹으로 쌓인 완충 표현, 그리고 한국어라면 번역투와 평서체 사이에 끼어든 존댓말 한 문장.

다른 하나는 구조입니다. 340자짜리 문단. 두 문장이면 될 자리에 아홉 개로 중첩된 불릿. 세 줄마다 걸린 문장 단위 볼드 — 결과적으로 강조가 하나도 없는 상태.

문장 길이를 한국어에서만 절 개수로 재는 이유가 있습니다. 한국어의 신호는 글자 수가 아니라 ~하며·~하고 연쇄이기 때문입니다. 짧아도 절이 다섯이면 읽기 어렵습니다.

기준값은 지어낸 것이 아닙니다. 각 SKILL.md 에 어느 문헌에서 왔는지 적어 두었습니다.

절대 건드리지 않는 것

여기서 틀리면 문서를 그냥 두는 것보다 나쁩니다.

frontmatter 는 모든 검사에서 제외됩니다.

스캐너만 따로 쓰기

수정 없이 숫자만 보고 싶을 때가 있습니다. 스캐너는 단독으로 돌아갑니다.

python3 ~/.claude/skills/saramchae-ko/scripts/scan.py FILE

위 before 문서를 넣으면 이렇게 나옵니다.

[1] register: 평서체 0 / 존댓말 5  — consistent

[2] translationese 6, 한자어 0, chat residue 1
    translationese: ~에 있어×3, ~을 통해×1, ~의 경우×1, 결론적으로×1
    chat residue: 궁금한 점이

[3] long sentences: 2 (n=8)
    L5  126자 / 4 clauses  현재 시스템의 경우, 배포가 진행될 때마다 캐시 전체를 비우는 …
    L7  108자 / 1 clauses  **따라서 버전 프리픽스 방식으로의 전환을 제안합니다.** 이 방식은 …

[7] bold: sentence-level 1 / term-level 0

출력은 판정이 아니라 분류로 읽습니다. 대부분의 문서는 두 개쯤 걸리고, 그게 정상입니다. 줄을 봤을 때 눈에 보이지 않는 지적은 오탐이니 버리면 됩니다. 각 숫자가 무엇을 틀리는지는 각 SKILL.md 7절에 정리해 두었습니다.

CI 에 걸기

--json 으로 기계가 읽는 출력을, --fail-over 로 게이트를 만듭니다. 파일과 디렉터리를 여러 개 넘길 수 있고, 디렉터리는 *.md 를 재귀로 찾습니다.

python3 scan.py --json docs/                    # 전부 훑어서 JSON 으로
python3 scan.py --fail-over 10 docs/ README.md  # 지적이 10개 넘는 파일이 있으면 exit 1

total 은 길이로 보정하지 않은 단순 합계입니다. 긴 문서일수록 자연히 커지므로, 임계값은 레포에 맞게 한 번 재보고 정하세요.

문서가 나쁜 글을 인용할 때

스타일 가이드, 버그 리포트를 인용한 체인지로그, before/after 예시처럼 나쁜 글에 대한 문서는 나쁜 글로 가득합니다. 그대로 두면 문서가 자기 예시를 자기한테 지적합니다.

그 구간을 마커로 감싸면 스캐너도 에이전트도 건드리지 않습니다. HTML 주석이라 렌더링에는 보이지 않습니다.

<!-- saramchae:off -->
본 문서는 개선 방안에 있어서의 방향성을 제시하고자 합니다.
<!-- saramchae:on -->

이 README 의 before/after 표 셋이 바로 그렇게 묶여 있습니다. 묶지 않으면 이 문서의 total 이 20, 묶으면 8 입니다. 남은 8은 실제로 이 문서에 있는 것들입니다.

위 예시처럼 마커를 코드 펜스 안에 넣어 보여 주는 경우는 마커로 치지 않습니다. 문법을 설명하는 문서가 자기를 가려 버리면 곤란하니까요.

라이선스

MIT.

각 SKILL.md 의 일부는 2차적 저작물입니다. 원본은 @blader 의 humanizer 스킬이고, 이를 옮긴 softaworks/agent-toolkit 판을 바탕으로 했습니다. 둘 다 MIT 입니다. 어느 절이 해당하는지는 각 스킬의 Credits 에 적어 두었습니다.

원저작권 표시와 라이선스 전문은 NOTICE 에 그대로 실었습니다.

어체 검사, 구조 검사, 스캐너 두 개, 검증은 직접 쓴 것입니다.