왜 contextlint가 존재하는가
contextlint는 특정 워크플로우나 방법론에 묶여 있는 것이 아니라, Markdown으로 문서를 관리하는 모든 프로젝트 가 공통으로 안고 있는 정합성 문제를 대상으로 합니다. 이 페이지에서는 그 배경에 있는 문제와, contextlint가 그것을 어떻게 자리매김하는지를 설명합니다.
문제: 문서가 “깨지는데” 알아채지 못한다
섹션 제목: “문제: 문서가 “깨지는데” 알아채지 못한다”여러 Markdown 파일이 서로 참조하는 저장소에서는, 어느샌가 정합성이 무너져 가는 현상이 일상적으로 발생합니다.
- 파일명 변경(rename)으로 링크가 깨졌지만, 빌드도 markdownlint도 통과한다
- 동일한 템플릿으로 작성하고 있을 터인 설계 문서에서 필수 섹션이 누락되어 있지만, 리뷰에서도 놓친다
- 요구사항 ID를 변경했지만, 참조 측 파일은 옛 ID 그대로 남아 있다
- AI에 새 문서를 생성시켰더니 기존 파일 참조가 깨졌지만, 생성 시점에는 아무도 알아채지 못한다
이들은 Markdown으로서는 구문적으로 올바른 상태입니다. markdownlint는 통과하고, 빌드도 통과하며, CI도 green입니다. 그런데도 문서로서의 정합성은 무너져 있다 — 이 간극을 메우는 도구가 contextlint입니다.
왜 AI 시대에 표면화되었는가
섹션 제목: “왜 AI 시대에 표면화되었는가”문서의 정합성 문제 자체는 새로운 것이 아닙니다. 다만, AI 주도 소프트웨어 개발이 확산되면서 영향이 확대된 것은 사실입니다.
| 변화 | 문서에 미치는 영향 |
|---|---|
| 사양 주도 개발(SDD)의 보급 | 요구사항·사양·설계를 Markdown으로 작성하고, AI가 이를 바탕으로 코드를 생성한다. 문서가 깨져 있으면 생성되는 코드도 깨진다 |
| ADR / RFC 운용 확대 | 설계 결정을 Markdown으로 남기는 팀이 늘어나, 파일 간 상호 참조가 복잡해진다 |
| AI에 의한 문서 생성 / 편집 | 사람이 일일이 확인할 수 있는 양을 넘는 속도로 Markdown이 변경된다 |
| 문서 수의 증가 | 수십~수백 개의 파일이 서로 참조하는 규모에서는, 육안이나 grep으로는 따라잡을 수 없다 |
문서는 단독 파일이 아니라, ID 참조, 링크, 안정도의 전파 등을 통해 의존 관계의 그래프를 형성 하고 있습니다. 이 그래프가 무너졌을 때, 영향은 표면화되기 어려워 조용히 퍼져 나갑니다.
왜 코드 린터와 같은 메커니즘이 필요한가
섹션 제목: “왜 코드 린터와 같은 메커니즘이 필요한가”코드에는 ESLint나 타입 검사가 있어, 구문적으로 올바른 것뿐만 아니라 의미적으로 정합한지 를 검증하는 메커니즘이 갖추어져 있습니다. 한편, Markdown 문서의 세계에는 구문·포맷 린터(markdownlint)는 있어도, 콘텐츠의 의미적 정합성 을 검증하는 표준 도구는 존재하지 않았습니다.
코드에 대해 eslint나 tsc가 수행하는 역할을, 문서에 대해 수행하는 도구가 필요하다 — 이것이 contextlint의 출발점입니다.
contextlint가 담당하는 범위
섹션 제목: “contextlint가 담당하는 범위”contextlint는 구조화된 Markdown 문서의 의미적 정합성 에 특화된 린터입니다.
- Markdown 테이블의 내용(필수 컬럼, 빈 셀, 허용 값, 패턴, 고유성, 컬럼 간 제약)
- 필수 섹션의 존재와 순서
- 파일 간 참조 정합성(링크, ID 추적성, 앵커, 이미지)
- 문서 의존 관계 그래프의 건전성(추적성 체인, 순환 참조, 고립 문서)
- 콘텐츠 품질(플레이스홀더 잔존, 용어의 일관성)
반대로 담당하지 않는 것 도 명확합니다. Markdown의 구문·포맷·스타일(제목 레벨의 일관성, 리스트 표기법, 테이블 구문)은 대상 외입니다. 이는 markdownlint의 영역입니다. 양자를 함께 사용하는 것을 권장합니다. 자세한 내용은 의미 린터와 구문 린터를 참조하세요.
상정하는 사용자
섹션 제목: “상정하는 사용자”contextlint는 Markdown 중심의 워크플로우를 채택하고 있는 팀·개인에게 적합합니다. 구체적으로는 다음과 같은 경우입니다.
- 사양 주도 개발(SDD) — 요구사항·사양·설계를 Markdown으로 작성하고, 이를 바탕으로 AI가 코드를 생성하는 접근법
- ADR (Architecture Decision Records) — 설계 결정을 Markdown으로 남기고 있는 팀
- 문서 주도 개발 — 설계를 먼저 문서화한 후 구현에 들어가는 스타일
- 대규모 저장소의 문서 정비 — 수십~수백 개의 Markdown 파일이 서로 참조하는 규모
다음 단계
섹션 제목: “다음 단계”- 의미 린터와 구문 린터 — markdownlint와의 관계와 역할 분담
- 3계층 피드백 설계 — LSP / MCP / CI로 나눈 이유
- Context Graph — 문서 의존 관계 그래프를 기반으로 삼은 이유