콘텐츠로 이동
contextlint

CTX-002 용어 일관성

개요

섹션 제목: “개요”

glossary(용어집) 파일에 정의된 별칭(alias)이 본문 중에서 사용되고 있지 않은지를 검증합니다. Database를 정식 표기로 하고, DB / database를 별칭으로서 등록한 경우, 본문에 DB가 등장하면 warning 으로 보고됩니다. 프로젝트 스코프 의 규칙으로, include로 읽어들인 모든 문서를 횡단하여 평가됩니다.

판정은 대소문자를 구별하지 않습니다. glossary 파일 자체는 대상 외입니다.

왜 필요한가

섹션 제목: “왜 필요한가”

「Database로 쓸지 DB로 쓸지」 같은 표기 흔들림은, 리뷰에서는 지적하기 어렵고, 방치하면 문서 전체의 검색성이 떨어집니다. 특히 AI로 초안을 생성하면, 같은 개념에 대해 여러 표기가 섞이기 쉽습니다. glossary를 1개의 진실의 원천(source of truth)으로 하여, 별칭이 섞이지 않았는지를 기계적으로 검출함으로써 용어를 일관시킬 수 있습니다.

옵션

섹션 제목: “옵션”
필드타입필수설명
glossarystring✓glossary로 취급할 파일의 glob
termColumnstring✓정식 표기가 저장된 컬럼명
aliasColumnstring—별칭이 저장된 컬럼명(쉼표 구분으로 여러 개 지정 가능). 미지정이면 아무것도 검출되지 않음
sectionstring—glossary 내에서 참조할 테이블을 특정 섹션 하위로 한정
filesstring—이 규칙을 적용할 파일의 glob(glossary 자체는 항상 제외)

aliasColumn은 형식상 optional이지만, 미지정이면 glossary로부터 별칭이 추출되지 않으므로 규칙은 아무것도 검출하지 않습니다. 실질적으로 필수에 가까운 취급입니다.

위반 예시

섹션 제목: “위반 예시”
docs/glossary.md:


| Term     | Aliases       |
| -------- | ------------- |
| Database | DB, database  |


docs/design.md:


# Design


We use a DB for storage.

docs/design.md에서 별칭 DB가 사용되고 있으므로 위반이 됩니다.

docs/design.md
  line 3  warning  "DB" should be "Database" (defined in glossary)  CTX-002

수정 후

섹션 제목: “수정 후”
docs/design.md:


# Design


We use a Database for storage.

설정 예시

섹션 제목: “설정 예시”
{
  "rule": "ctx002",
  "options": {
    "glossary": "docs/glossary.md",
    "termColumn": "Term",
    "aliasColumn": "Aliases",
    "files": "docs/**/*.md"
  }
}

glossary 파일 측은 다음과 같은 구조를 상정합니다.

## 용어


| Term     | Aliases       |
| -------- | ------------- |
| Database | DB, database  |
| API      | Api, api      |

Aliases 컬럼은 쉼표 구분으로, 여러 별칭을 1개의 셀에 열거할 수 있습니다.

관련 규칙

섹션 제목: “관련 규칙”