간결한 기술 영어
개요
재럿의 규칙 1: 채팅 출력, 생성된 문서, 코드 주석 및 커밋 메시지는 간결한 기술 영어를 사용합니다. 이 스타일은 ASD-STE100의 원칙을 기반으로 합니다. 독자가 사실을 더 빨리 찾을 수 있습니다. 영어가 모국어가 아닌 독자가 더 잘 이해합니다.
이 스킬은 자체 요약입니다. ASD-STE100 표준이 아니며 해당 사전을 포함하지 않습니다.
사용 시기
- 사양, 계획, ADR, README, 용어집 항목 또는 기타 문서를 작성하거나 편집할 때
- 코드 주석이나 커밋 메시지를 작성할 때
- 규칙 1에 따라 텍스트를 검토할 때
코드 식별자, 인용 출력(오류, 로그, 명령 출력), 스킬 파일 또는 사용자가 작성한 텍스트에는 적용하지 마십시오.
프로세스
텍스트를 작성합니다. 그런 다음 각 규칙에 대해 확인합니다.
| # | 규칙 | 이렇게 하지 마세요 | 이렇게 하세요 |
|---|---|---|---|
| 1 | 한 문장에 하나의 주제. | 후크가 파일을 읽고, 파일이 없으면 사용자가 보는 경고를 출력합니다. | 후크가 파일을 읽습니다. 파일이 없으면 후크가 경고를 출력합니다. 사용자가 경고를 봅니다. |
| 2 | 지침: 20단어 이하. 설명: 25단어 이하. | 브랜치를 푸시하기 전에 전체 테스트 스위트를 실행하고 출력을 확인했는지 확인하세요. | ./scripts/test.sh를 실행합니다. 그런 다음 브랜치를 푸시합니다. |
| 3 | 능동태를 사용하세요. | 규칙이 후크에 의해 로드됩니다. | 후크가 규칙을 로드합니다. |
| 4 | 지침은 명령형을 사용합니다. | 커밋 전에 테스트를 실행해야 합니다. | 커밋 전에 테스트를 실행하세요. |
| 5 | 한 단어는 하나의 의미를 가집니다. .claude-work/docs/VOCABULARY.md의 용어를 사용하세요. | 경고, 그 다음 같은 동작에 대해 "플래그", "알림" 또는 "통지". | 매번 경고합니다. |
| 6 | 단순 시제 사용: 현재, 과거, 미래. | 후크가 입력을 확인하고 있었을 것입니다. | 후크가 입력을 확인합니다. |
| 7 | 단일 동사 사용, 구동사나 관용구 사용 금지. | 빌드를 시작하세요. 원인을 파악하세요. | 빌드를 시작하세요. 원인을 찾으세요. |
| 8 | "the"와 "a"를 유지하세요. | 스크립트 실행, 출력 확인. | 스크립트를 실행하세요. 출력을 확인하세요. |
| 9 | 단계당 하나의 지침. | 1. 파일을 열고 버전을 변경하세요. | 1. 파일을 엽니다. 2. 버전을 변경합니다. |
| 10 | 문단: 6문장 이하. | 열 문장의 블록. | 짧은 문단 두 개 또는 목록. |
추가 규칙:
- 경고나 주의사항은 해당 단계 앞에 작성합니다. 위험을 먼저 명시합니다: "경고: 이 작업은 브랜치를 삭제합니다."
- 값은 숫자로 표기합니다: "72자", "일흔두 자"가 아닙니다.
- 항목이 세 개 이상일 때는 목록이나 표를 사용합니다.
- 텍스트를 다르게 표현하기 위해 동의어를 사용하지 마십시오. 동일한 용어를 반복하세요.
- 명사가 명확하지 않을 때는 "그것" 또는 "이것"을 사용하지 마십시오. 명사를 다시 명시하세요.
- 용어가 용어집에 없고 의미가 명확하지 않으면 사용자에게 물어보세요. 그런 다음 용어를 용어집에 추가하세요.
일반적인 합리화
| 합리화 | 현실 |
|---|---|
| "짧은 문장은 로봇처럼 들립니다." | 짧은 문장은 읽기 빠르고 잘못 읽기 어렵습니다. 독자의 속도가 스타일보다 중요합니다. |
| "동의어가 텍스트를 덜 반복적으로 만듭니다." | 동의어는 독자가 다른 것인지 의문을 갖게 합니다. |
| "이 주석은 규칙을 적용하기에 너무 작습니다." | 주석과 커밋 메시지는 적용 대상입니다. 작은 텍스트는 고치기 쉽습니다. |
| "수동태가 더 격식 있습니다." | 수동태는 행위 주체를 숨깁니다. 행위자를 명시하세요. |
경고 신호
- "그리고", "어느", "그래서" 등으로 두 주제를 연결하는 문장.
- 지침에 "해야 한다", "할 수 있다" 또는 "~일 수도 있다" 사용.
- 동일한 대상이 하나의 문서에서 두 가지 이름으로 불림.
- 두 가지 동작이 있는 단계.
- 해당 단계 이후에 오는 경고.
검증
- 각 문장은 하나의 주제를 가집니다.
- 어떤 지침도 20단어를 초과하지 않습니다. 어떤 설명도 25단어를 초과하지 않습니다.
- 모든 지침은 명령형과 능동태를 사용합니다.
- 모든 용어는 용어집과 일치합니다.
- 각 목록 단계는 하나의 지침을 가집니다.
- 어떤 문단도 6문장을 초과하지 않습니다.