document-haness/skills/technical-doc-flow/references/terminology-policy.md

용어 정책

정확한 용어를 지우지 않고 독자가 받아들이는 순서를 바꾼다. 정식 명칭, 코드 식별자, 수치의 보존은 쉬운 설명과 충돌하지 않는다.

목차

• 기본 순서와 first-use
• 용어 예산과 canonical name
• 구현 식별자 보존
• 05_term_ledger.json과 통과 조건

기본 순서

처음 등장할 때 다음 순서를 따른다.

1. 쉬운 역할 또는 동작 설명
2. 정식 한국어 명칭
3. 영문 명칭과 약어
4. 구현 식별자

예:

• 나쁨: “IdempotencyExecutor가 fingerprint mismatch를 처리한다.”
• 좋음: “같은 요청 키에 다른 본문이 들어왔는지 판별하는 실행기(IdempotencyExecutor)는 요청 지문 불일치(fingerprint mismatch)를 별도 오류로 처리한다.”

코드 식별자가 문장의 주어여야 정확한 경우에도 직전 문장에서 역할을 먼저 설명한다.

첫 등장 (first-use)

• 독자가 처음 만나는 전문용어는 같은 문장 또는 바로 다음 문장에서 뜻을 정의한다.
• 약어는 첫 등장에 원어와 쉬운 뜻을 함께 쓴다. 예: “로그를 한 요청으로 묶는 임시 문맥 저장소(Mapped Diagnostic Context, MDC)”.
• 제목이나 표에서 본문보다 먼저 등장하면 그 위치가 first-use다.
• 독립적으로 검색하는 reference 항목은 문서 전체의 앞선 정의에 기대지 않고 항목 안에서 다시 정의한다.
• 잘 알려진 약어라도 독자 계약의 prerequisites에 없으면 확장한다.

기본 용어 예산

• 문장당 새 개념 2개 이하
• 문단당 새 개념 2개 이하
• 절당 새 개념 7개 이하

새 개념은 독자가 새 의미를 기억해야 하는 용어다. 이미 정의한 용어의 반복, 코드 예시에 나타나는 동일 식별자, 일반 언어는 다시 세지 않는다.

예산을 넘으면 다음 순서로 해결한다.

1. 불필요한 별칭을 제거한다.
2. 상세 식별자를 근거 노트, 표 또는 부록으로 옮긴다.
3. 개념을 여러 문단이나 절로 나눈다.
4. 분리만으로 부족하면 쉬운 설명을 앞에 보강하고 단위를 다시 나눠 예산 gate를 충족한다. 예외나 waiver로 초과를 통과시키지 않는다.

예산은 정확한 코드명이나 사용자 제공 인용을 바꾸는 허가가 아니다.

표준명 (canonical)과 별칭 (alias)

• 개념마다 표준명 canonical 하나를 고른다.
• 영문 원어는 english, 약어는 abbreviation에 기록하고, 그 밖의 레거시 이름과 검색용 표기만 aliases에 기록한다. 같은 표기를 여러 필드에 복제하지 않는다.
• 모든 term의 canonical, aliases, english, abbreviation을 정규화해 비교했을 때 하나의 표기에는 전역 소유자 하나만 있어야 한다. 같은 term의 두 필드에 같은 이름을 중복 배정하는 것도 허용하지 않는다.
• 첫 정의 뒤에는 표준명 또는 코드 식별자 중 하나를 일관되게 쓴다.
• seam/확장점/pluggable seam, replay/재생/저장 응답 재사용처럼 문단마다 이름을 바꾸지 않는다.
• 원문 인용, 공개 API, 클래스·함수·환경 변수·오류 코드에서는 원형을 보존한다.

구현 식별자 보존

다음은 번역, 축약, 대소문자 변경, “더 읽기 좋은 이름”으로의 치환을 금지한다.

• 클래스, 인터페이스, 함수, 메서드, 패키지, 모듈
• API 필드, 헤더, 상태값, 오류 코드
• 명령과 그 플래그·인수를 포함한 inline code 전체, 환경 변수, 설정 키
• 파일 경로, 숫자·단위, 날짜, 버전, 커밋, SQL 식별자
• 코드와 로그의 인용 문자열

쉬운 설명은 식별자 옆에 추가한다. 식별자 자체를 고치지 않는다. 긴 규칙명은 본문에서 쉬운 역할명으로 설명하고, 정확한 이름은 괄호·근거 표·코드 블록에 보존한다.

표

• 표 머리글은 가능하면 쉬운 언어를 사용한다.
• 표의 상태값과 코드명은 머리글이나 바로 앞 문장에서 역할을 설명한다.
• 하나의 표 안에서 alias를 섞지 않는다.

05_term_ledger.json 최소 필드

{
  "schema_version": "1.0",
  "assumed_known": ["HTTP"],
  "budgets": {"per_sentence": 2, "per_paragraph": 2, "per_section": 7},
  "terms": [
    {
      "id": "term-id",
      "canonical": "의존 방향",
      "plain_definition": "어느 코드가 어느 쪽을 알아도 되는지를 정한 규칙",
      "why_needed": "변경 책임과 허용 호출을 설명하기 위해 필요하다.",
      "aliases": ["의존성 방향"],
      "first_section": "SEC-003",
      "first_use": "어느 코드가 어느 쪽을 알아도 되는지 정한 규칙인 의존 방향",
      "english": "dependency direction",
      "protected": false
    }
  ]
}

필수 최상위 필드는 schema_version, assumed_known, budgets, terms다. 각 용어의 필수 필드는 id, canonical, plain_definition, why_needed, aliases, first_section, first_use이며 english, abbreviation, protected는 필요할 때 사용한다. 정확히 보존해야 하는 구현 식별자는 protected: true인 별도 용어 항목으로 기록하거나 입력 보존 목록과 연결한다.

first_section은 설명 위치에 대한 선언이자 logic map 연결 계약이다. 각 term ID는 정확히 그 절의 04_logic_map.json.sections[].new_terms에 한 번 나타나야 하며 다른 절의 new_terms에는 나타나면 안 된다. ledger에 없는 ID를 new_terms에 넣거나 ledger term을 어느 절에도 연결하지 않는 것도 오류다.

독자 계약의 assumed_known은 설명 없이 써도 된다고 합의한 목록이고 must_explain은 본문에서 처음부터 풀어야 할 목록이다. 두 목록은 정규화했을 때 겹치면 안 된다. 모든 must_explain 항목은 term ledger의 canonical, aliases, english, abbreviation 중 하나로 실제 term에 연결되어야 한다. reader contract와 ledger의 assumed_known 목록도 일치시킨다.

용어 게이트

• 새 영문·코드형 전문용어 후보가 ledger나 독자 계약에 없으면 기본 gate를 막는다. 대문자·snake_case·kebab-case·camelCase·점 표기는 형태로 찾고, 소문자 한 단어는 quality-rules.json.patterns.technical_lowercase_candidates에 명시한 기술어만 찾는다. 모든 영문 일반어를 기술어로 단정하지 않으며, 후보가 일반어라면 technical_candidate_allowlist에 근거를 남긴다. 전문용어라면 ledger 등록·독자 계약 등록·불필요한 용어 제거 중 하나로 처리한다.
• first-use 정의가 실제 최초 위치보다 뒤에 있으면 실패한다.
• 약어 원어와 쉬운 뜻 중 하나가 빠지면 실패한다.
• 한 개념이 여러 canonical name을 가지면 실패한다.
• canonical, alias, 영문명, 약어의 같은 표기가 둘 이상의 필드나 term에 배정되면 실패한다.
• term ID가 first_section의 new_terms에 정확히 한 번 연결되지 않으면 실패한다.
• assumed_known과 must_explain이 겹치거나 must_explain이 ledger term에 연결되지 않으면 실패한다.
• 구현 식별자가 원문 또는 근거와 다르면 중대 실패다.
• inline code 안의 명령·플래그·인수와 숫자·단위·날짜·버전이 기준 문서와 달라지면 중대 실패다.
• 문장·문단·절의 용어 예산 초과는 기본 gate를 막는다. 불필요한 별칭을 없애거나 설명 단위를 나누되, 정확한 식별자를 삭제해 숫자만 맞추지 않는다.