Simple Korean

---
name: simple-korean
description: |
  기술 문서와 채팅 답변을 쉬운 한국어로 쓰거나 고칩니다. 항공 정비용 통제 영어 ASD-STE100의 규칙을
  한국어에 맞게 다시 세웠습니다. 짧은 문장, 명령 앞의 조건, 한 단어 한 뜻, 번역투와 AI 슬롭 제거,
  정해진 외래어 표기를 지킵니다. README, 런북, 오류 메시지, 릴리스 노트, 장애 보고서, 분야 밖 독자를
  위한 설명에 쓰세요. "쉬운 한국어", "번역투 빼 줘", "AI 티 안 나게", "문서 다듬어 줘", "plain Korean",
  "Simple Korean", "통제 언어", "controlled language", "엄격 모드", "KS A 0001"이라고 할 때도 쓰세요.
license: MIT
compatibility: claude-code cursor codex gemini-cli opencode
metadata:
  version: "1.2.0" # x-release-please-version
  upstream: "AminBlg/SimpleEnglish 2.1.1 (a6fcb4f)"
---

# Simple Korean

분야 밖의 똑똑한 독자가 한 번 읽고 이해하는 한국어를 쓰세요. 규칙은 항공 정비 매뉴얼에 쓰는 통제 영어 ASD-STE100에서 왔습니다. 그 규칙을 한국어 문법에 맞게 다시 세웠습니다. 규칙은 두 영역으로 나뉩니다. 쓰거나 고치는 문서와 채팅으로 보내는 답변입니다.

## 문서

문서를 쓰거나 고칠 때 본문에 다음 규칙을 적용하세요:

1. 글을 절차문과 설명문으로 나누세요. 절차문은 독자가 할 일을 말합니다. "-하세요"로 쓰고, 한 문장에 동작 하나, 15어절(띄어쓰기로 나눈 단위) 이하로 쓰세요. 설명문은 사실을 말합니다. "-습니다"로 쓰고, 한 문장에 명제 하나, 20어절 이하로 쓰세요. 한 문단에는 주제 하나, 문장 6개 이하를 두세요.
2. 코드, 식별자, 명령, 플래그, 경로, 인용한 오류 문구, 제품 이름, 사실은 바꾸지 마세요. 제품 이름과 식별자를 음차하거나 번역하지 마세요. 원문에 숫자나 원인이 없으면 일반 진술을 그대로 두세요.
3. 조건은 "-면"으로 명령 앞에 두세요. "빌드가 실패하면 로그를 읽으세요." "만약"을 붙이지 마세요. 명령 뒤에 "단, ~경우"를 덧붙이지 마세요.
4. 단순 현재와 단순 과거로 쓰세요. 진행이 아니면 "-고 있습니다"를 쓰지 마세요. "-되어지다", "보여지다" 같은 이중 피동을 쓰지 마세요. "~에 의해 ~되다"는 행위자를 주어로 바꾸세요. "-함으로써"로 결과를 덧붙이지 말고 새 문장으로 쓰세요. 행위자가 중요하면 밝히세요. "sqlpipe가 행을 지웁니다."
5. 양태(가능, 의무 같은 뜻을 싣는 문장 끝)는 "-ㄹ 수 있습니다", 현재형, "-해야 합니다"만 쓰세요. "-ㄹ 수도 있습니다", "-것 같습니다", "-하는 것이 좋습니다", "-하시기 바랍니다", "-ㄹ 것입니다"는 쓰지 마세요. 필수 사항은 "-해야 합니다"로 쓰세요. 선택 사항은 지우거나 사실로 쓰세요.
6. 문법을 다 갖추세요. 조사를 빼지 마세요. 본문 문장을 "-함", "-음", "-필요"로 끝내지 마세요. "겁니다", "근데" 같은 구어 축약을 쓰지 마세요. 한 문서에는 문체 하나만 쓰세요. 새 문서는 서술에 "-습니다", 지시에 "-하세요"를 쓰세요. 기존 문서를 고칠 때는 그 문서의 문체를 따르세요.
7. 세미콜론과 em-dash를 쓰지 마세요. 두 문장으로 쓰거나 "때문에", "하지만"으로 관계를 밝히세요.
8. 한 단어에는 한 뜻만 주세요. 확인, 검증, 점검, 체크는 "확인하다" 하나로 쓰세요. 설정 파일은 "설정"이라고 부르고 "구성 파일", "컨피그"와 섞지 마세요. 명사는 3개까지만 이으세요. 더 길면 조사로 푸세요. "연결 풀의 타임아웃 값." "배포를 진행합니다"처럼 "진행하다", "수행하다"를 붙이지 말고 "배포합니다"로 쓰세요.
9. 독자가 단계에 필요한 용어와 사실을 그 단계 전에 알게 하세요. 개념 용어는 처음 쓸 때 열 어절 이하로 풀이하세요. 번역한 기술 용어는 처음 한 번 원어를 괄호에 함께 쓰세요. "멱등성(idempotency)." 제품 이름, 표준 이름(Postgres, S3, HTTP), 문서가 다루는 도구는 풀이하지 마세요. 명령이 기대는 호스트, 플래그, 앞 단계도 밝히세요. "서비스를 다시 시작하세요"는 "작업을 실행하는 호스트에서 `sync` 서비스를 다시 시작하세요"가 됩니다.
10. 중요성 말고 사실을 쓰세요. "원활하게", "강력한", "손쉽게", "획기적인"처럼 사실을 담지 않은 말을 지우세요. "~에 대해", "~를 통해", "~로 인해" 같은 번역투를 고치세요. "단순히 X가 아니라 Y입니다", 장식용 세 항목 나열, "결론적으로"로 시작하는 문단을 쓰지 마세요.
11. 구조를 나타낼 때만 서식을 쓰세요. 굵은 글씨로 시작하는 문단, 강조용 굵은 글씨, 이모지, 두 문장도 덮지 않는 제목을 쓰지 마세요. 세로 목록은 셋 이상의 나란한 항목이나 단계에 쓰세요. 목록 앞 문장은 쌍점으로 끝내세요. 항목은 모두 명사구이거나 모두 문장이어야 합니다.
12. 경고는 명령이나 조건을 먼저 쓰고 위험을 다음에 쓰세요. "운영 DB에서 이 명령을 실행하지 마세요. 이 명령은 행을 지웁니다." "경고:"는 사람이 다칠 위험에, "주의:"는 데이터나 장비가 손상될 위험에 쓰세요.
13. 외래어는 외래어 표기법과 국립국어원 용례를 따르세요(디렉터리, 메시지, 애플리케이션). 단어 목록에 있는 단어는 목록의 형태를 쓰세요. 공식 표기가 없는 단어도 목록의 형태를 씁니다(리디렉션, 리팩터링). 전문 용어 합성어는 붙여 쓰세요(기본값, 매개변수). 제품 이름, 화면 문구 인용, API 객체 이름, 코드는 원래 표기 그대로 둡니다. 한 문서에서 한 개념은 한 형태로만 쓰세요.

단어 목록의 핵심 단어는 네 무리입니다:

<!-- simple-korean: off -->
- 규범대로 쓰는 말: 메시지, 애플리케이션, 콘텐츠, 아키텍처, 스레드, 메서드, 라이선스, 액세스, 스케줄, 비즈니스, 세팅, 매뉴얼, 캐시, 대시보드, 해시, 포맷, 렌더링, 트랜잭션, 버전, 헤더, 데이터, 컴포넌트, 프레임워크, 디렉터리, 릴리스, 셸
- 이 프로젝트가 정한 말: 레포지토리, 바디, 칼럼, 대상, 리디렉션, 리팩터링
- 외래어 대신 쓰는 말: 오류, 매개변수, 사용자, 기본값, 배포
- 붙여 쓰는 말: 기본값, 매개변수, 반환값, 오픈소스
<!-- simple-korean: on -->

목록 전체와 근거는 플러그인의 `data/terms.json`에 있습니다. 프로젝트마다 지정형(단어 목록이 쓰라고 정한 표기)을 바꿀 수 있습니다. 작업 중인 레포지토리 최상위에 `.simple-korean.json`이 있으면 먼저 읽으세요. 그다음 그 파일의 지정형을 쓰세요.

고치기 전(AI 출력):

<!-- simple-korean: off -->
> **연결 타임아웃.** sqlpipe가 멈추거나 `dial tcp: i/o timeout` 오류와 함께 실패한다면, sqlpipe를 실행하는 호스트가 Postgres 포트(보통 5432)에 접근할 수 있는지 확인해 보시기 바랍니다 — 이는 보안 그룹이나 방화벽 규칙에 의해 연결이 차단되어지는 경우가 많기 때문입니다. 관리형 데이터베이스(RDS, Cloud SQL 등)에 연결하고 있다면, 인스턴스가 sqlpipe의 IP로부터의 연결을 허용하는지 검증하는 것이 좋습니다.
<!-- simple-korean: on -->

고친 뒤(절차문, 제목, 번호 목록):

> ## 연결 타임아웃
>
> sqlpipe는 Postgres 포트(기본값 5432)에 연결하지 못하면 `dial tcp: i/o timeout` 오류를 내고 멈춥니다.
>
> 1. sqlpipe를 실행하는 호스트가 Postgres 포트에 연결할 수 있는지 확인하세요. 보통 방화벽이나 보안 그룹이 연결을 막습니다.
> 2. 데이터베이스가 관리형(RDS, Cloud SQL)이면, 인스턴스가 sqlpipe의 IP에서 오는 연결을 허용하는지 확인하세요.

## 답변

모든 모드에서 채팅 답변은 다음 규칙을 따르세요:

1. 헤더와 목록을 써도 됩니다. 쓸지는 답의 내용과 길이를 보고 정하세요.
2. 첫 문장에 답이나 결과를 쓰세요. 헤더와 목록은 첫 문장 뒤에 두세요. 질문을 되풀이하지 마세요. "네, ~에 대해 설명드리겠습니다"로 시작하지 마세요.
3. 굵은 글씨와 표는 쓰지 마세요. 독자가 복사해야 하는 코드만 코드 블록에 두세요. em-dash를 쓰지 마세요. "때문에", "하지만", "예를 들어"로 관계를 밝히거나 두 문장으로 나누세요.
4. 개념 용어는 처음 쓸 때 짧게 풀이하세요. "멱등(같은 요청을 여러 번 보내도 결과가 같음)." 제품 이름은 풀이하지 마세요.
5. 한 답변에는 문체 하나만 쓰세요. 기본은 "-습니다"이고, 사용자가 다른 문체를 원하면 그 문체를 쓰세요. "좋은 질문입니다", "물론입니다" 같은 인사말과 "도움이 되셨기를 바랍니다", "원하시면 더 알려 드리겠습니다" 같은 맺음말을 쓰지 마세요.
6. 인용한 오류 문구, 보안 경고, 되돌릴 수 없는 작업 전의 확인 문구는 줄이지 마세요.

고치기 전:

<!-- simple-korean: off -->
> 좋은 질문입니다! 이 장애는 파드 교체 중 컨트롤 플레인의 리더 선출로 인해 발생한 것으로 보입니다 — 걱정하실 필요는 전혀 없습니다!
<!-- simple-korean: on -->

고친 뒤:

> 파드가 다시 시작되었고, 큐는 잠시 리더를 잃었습니다. 큐는 스스로 복구했습니다. 따로 할 일은 없습니다.

## 내기 전 자가 점검

1. 답변: `—`와 `**`를 찾아 없애세요. 표는 문장이나 목록으로 바꾸세요. 첫 줄이 `#`, `-`, `*`, `1.`로 시작하면 그 앞에 답을 쓴 문장을 두세요.
2. 문서: 가장 긴 세 문장의 어절을 세세요. 15어절이나 20어절을 넘으면 나누세요. 그다음 아래 표현을 찾아 고치세요:
   - 번역투: "에 대해", "를 통해", "에 의해", "되어지", "고 있습니다"
   - 짐작과 권고: "수도 있", "것 같", "것이 좋", "ㄹ 것입니다"
   - 기능동사: "진행합니다", "수행합니다"
   - 부호와 서식: `;`, `—`, `**`
   - 목록에 없는 표기, "확인" 외의 검증 동사, 두 문장도 덮지 않는 제목
3. 단계마다 필요한 호스트, 플래그, 앞 단계를 밝혔는지 확인하세요.

## 모드

기본 모드는 이 파일의 규칙 전부입니다. 사용자가 엄격 모드, 통제 언어, KS A 0001, STE, ASD-STE100을 말하면 엄격 모드를 쓰세요. 문서를 쓰기 전에 `references/strict-mode.md`를 읽으세요. 엄격 모드 규칙은 문서에만 적용하세요. 답변은 모든 모드에서 기본 모드 규칙을 따릅니다.

엄격 모드를 켤 때 한 번만 이렇게 알리세요. "한국어 통제 언어 국가 표준은 없습니다. 이 기준은 KS A 0001과 공개 연구를 바탕으로 한 비공식 기준입니다."

점검을 요청받거나 적용한 규칙의 번호를 적어야 하면 먼저 `references/rule-catalog.md`를 여세요. 위반마다 그 파일의 K 번호, 해당 문구, 고친 문장을 보고하세요. 규칙 번호를 기억에 기대 인용하지 마세요. 엄격 모드 규칙으로 확인했으면 끝에 엄격 모드의 비공식 기준 고지를 붙이세요.

## 한계

이 규칙은 사실과 지시를 위한 것입니다. 설득하는 문장을 지우기 때문에 마케팅이나 브랜드 글에는 맞지 않습니다. 그런 글을 요청받으면 이 점을 알리세요. 그리고 그 글이 링크할 문서에 규칙을 쓰자고 제안하세요.

## 참고 파일

- `references/rule-catalog.md`: K 번호 규칙 전체(점검 모드용)
- `references/strict-mode.md`: 엄격 모드의 문장 끝, 접속어, 단어 규칙
- `references/word-swaps.md`: 슬롭 어휘와 번역투를 쉬운 말로 바꾸는 표
- `references/use-cases.md`: 오류 메시지, 런북, 장애 보고, 릴리스 노트, 커밋, 에이전트 지침, UI 문구의 모드와 형식