시작하기

예를 들어, 이런 일이 일어나고 있지는 않으신가요?

다른 파일로 링크를 걸어 두었는데, 어느 사이엔가 링크 대상 파일명이 변경되어 있었습니다. 링크는 끊어져 있지만, 빌드도 markdownlint도 통과합니다
같은 템플릿으로 작성하고 있을 터인 설계 문서에서, 어느 틈에 필수 섹션이 하나 누락되어 있었습니다. 리뷰에서도 놓쳤습니다
AI에게 새로운 문서를 생성시켰더니, 기존 파일에 대한 참조가 몇 군데 끊어져 있었습니다. 생성 시점에 사람은 알아차리지 못합니다

이러한 것들은 구문상으로는 올바른 Markdown입니다. markdownlint도 통과하고, 빌드도 통과하며, CI도 green입니다. 그럼에도 문서로서의 정합성은 무너져 있습니다 — 이것이 contextlint가 해결하고자 하는 문제입니다.

contextlint는 구조화된 Markdown 문서의 의미적 정합성을 검증하는 규칙 기반 린터입니다. 끊어진 링크, 필수 섹션 누락, 테이블의 빈 셀, ID 중복, 문서 간 의존 관계 붕괴와 같은 문제들을 결정론적으로, 몇 초 만에 감지합니다.

대상 사용자

contextlint는 Markdown 중심의 워크플로우를 채택한 팀 및 개인에게 적합합니다. 예를 들어 다음과 같은 경우입니다.

사양 주도 개발(SDD) — 요구사항·사양·설계를 Markdown으로 작성하고, 이를 바탕으로 AI가 코드를 생성하는 접근 방식
ADR(Architecture Decision Records) — 설계 판단을 Markdown으로 남기는 팀
문서 주도 개발 — 설계를 먼저 문서화한 후 구현에 들어가는 스타일
대규모 리포지토리의 문서 정비 — 수십~수백 개의 Markdown 파일이 서로 참조하는 규모

contextlint와 markdownlint의 관계

contextlint는 콘텐츠의 의미와 파일 간 정합성에 특화되어 있습니다. Markdown 구문·포맷·스타일(제목 레벨의 일관성, 리스트 표기법, 테이블 구문 등)은 대상이 아닙니다. 이러한 부분은 markdownlint의 영역이므로, 양쪽을 함께 사용하시기를 권장합니다.

관점	markdownlint	contextlint
Markdown 구문	✓	—
포맷·스타일	✓	—
테이블 내 데이터 정합성	—	✓
필수 섹션 존재 여부	—	✓
파일 간 참조 정합성	—	✓
의존 그래프 검증	—	✓

왜 정적 분석인가

문서의 정합성을 LLM에게 검증시키는 선택지도 있지만, contextlint는 정적 분석을 고수하고 있습니다. 이유는 몇 가지가 있습니다.

재현성 — 같은 입력이라면 같은 결과. 프롬프트나 temperature에 좌우되지 않습니다. CI에서 안정적으로 동작시킬 수 있습니다.
비용 — 토큰을 소비하지 않습니다. 100개 파일을 검증해도 비용은 0입니다.
속도 — 1초 이내에 완료됩니다. 에디터 통합(LSP)으로 「입력 중에 실시간 감지」가 성립할 정도의 속도입니다.
명확성 — 에러 메시지가 고정되어 있으므로, 기계 처리(자동 수정, CI에서의 필터링)에 적합합니다.

LLM은 문서를 작성하는 역할에서 힘을 발휘하며, 완성된 문서를 검증하는 데에는 정적 분석이 적합합니다. 각자가 잘하는 영역을 분담하도록 하는 것이 contextlint의 설계 사상입니다.

3계층 피드백

contextlint는 문서 라이프사이클의 3가지 시점에 통합할 수 있습니다.

시점	프로토콜	주요 도구
작성하는 동안	LSP	VS Code / Cursor / Neovim / Helix / JetBrains
AI가 작성하는 동안	MCP	Claude Code / Cursor Agent / Cline / Codex / Windsurf
머지 전	CLI	GitHub Actions / pre-commit / Husky / lint-staged

작성하는 순간부터 머지까지, 문서의 정합성을 지속적으로 유지할 수 있습니다.

시작하기

대상 사용자

contextlint와 markdownlint의 관계

왜 정적 분석인가

3계층 피드백

다음 단계