콘텐츠로 이동
contextlint

의미 린터와 구문 린터

contextlint의 태그라인은 “markdownlint for syntax. contextlint for meaning.“입니다. 이는 markdownlint와 기능이 겹치는 도구를 만든 것이 아니라, 다른 레이어를 담당하는 보완 관계 에 있음을 나타냅니다. 이 페이지에서는 의미 린터(semantic linter)와 구문 린터(syntax linter)의 차이를 정리합니다.

레이어의 차이

섹션 제목: “레이어의 차이”

린터는 검증하는 대상에 따라 레이어가 나뉩니다.

레이어 검증 대상 예
구문 (syntax) 표기가 문법을 따르고 있는가 제목 레벨, 리스트 표기법, 테이블 구문
포맷 (format) 표기 스타일이 통일되어 있는가 행 끝 공백, 리스트 기호의 통일
의미 (semantic) 내용이 논리적으로 정합한가 필수 컬럼의 유무, ID의 고유성, 참조 대상의 존재

markdownlint는 구문과 포맷 을 담당합니다. contextlint는 의미적 정합성과 파일 간 정합성 을 담당합니다. 양자는 경합하지 않으며, 레이어가 다릅니다.

기능 대비

섹션 제목: “기능 대비”
관점 markdownlint contextlint
Markdown 구문 ✓ —
포맷·스타일 ✓ —
제목 레벨의 일관성 ✓ —
테이블 구문의 정확성 ✓ —
테이블 내 데이터 정합성 — ✓
필수 섹션의 존재 — ✓
필수 섹션의 순서 — ✓
ID의 고유성 — ✓
파일 간 참조 정합성 — ✓
의존 관계 그래프 검증 — ✓
용어의 일관성 — ✓

구체적인 예로 보는 차이

섹션 제목: “구체적인 예로 보는 차이”

같은 테이블에 대해, 양자는 다른 측면을 검증합니다.

| ID          | Status | Description |
| ----------- | ------ | ----------- |
| REQ-AUTH-01 |        | 로그인 요건 |
| REQ-AUTH-01 | stable |              |
  • markdownlint가 보는 것: 파이프 개수, 구분 행의 정형, 공백의 처리 — 테이블이 Markdown으로서 유효한가
  • contextlint가 보는 것:
    • Status 컬럼에 빈 셀이 있다 (TBL-002)
    • ID 컬럼에 중복이 있다 (TBL-006)
    • Description 컬럼에 빈 셀이 있다 (TBL-002)
    • 테이블 내용이 업무상의 정합성을 유지하고 있는가

양자를 조합함으로써, 표기의 정확성 + 내용의 정확성 을 양면에서 커버할 수 있습니다.

왜 의미 린터가 필요한가

섹션 제목: “왜 의미 린터가 필요한가”

구문 린터만으로는 커버할 수 없는 영역은, 문서가 규모를 키울수록 표면화됩니다.

  • 링크가 Markdown으로서 올바른 표기법으로 작성되어 있어도, 링크 대상 파일이 존재하지 않는 경우가 있다
  • 테이블이 Markdown으로서 올바른 구문이어도, 필수 컬럼이 누락되어 있는 경우가 있다
  • 같은 ID가 여러 파일에서 정의되어 있어도, Markdown으로서는 아무 문제가 없다
  • stable 상태의 요구사항이 draft 상태의 요구사항에 의존하고 있어도, Markdown 구문상으로는 오류가 되지 않는다

이들은 Markdown 레이어에서는 검출 불가능한 문제입니다. 문법이 아닌 의미 레이어 에 있기 때문에, 별도의 린터가 필요합니다.

병용이 전제

섹션 제목: “병용이 전제”

contextlint는 markdownlint를 대체하지 않습니다. 양자는 병용함으로써 비로소, 문서를 다층적으로 검증할 수 있습니다.

  • markdownlint — “Markdown으로서 올바르게 작성되었는가”
  • contextlint — “문서의 내용이 정합한가”

CI 파이프라인에서는 양쪽을 순서대로 실행할 것을 권장합니다. markdownlint로 구문을, contextlint로 의미를 — 각각의 강점 영역에 분담시키는 것이 자연스러운 사용 방법입니다.

다음 단계

섹션 제목: “다음 단계”