Context Graph
contextlint는 파일을 하나씩 독립적으로 검증하는 것이 아니라, 프로젝트 전체의 문서를 하나의 의존 관계 그래프로 다룹니다. 이것이 Context Graph입니다. 이 페이지에서는 왜 그래프를 기반으로 삼았는지, 그래프가 어떤 개념을 표현하고 있는지를 설명합니다.
구체적인 API 인터페이스(buildContextGraph, getImpactSet 등)는 Graph API 카테고리에서 다룹니다. Concepts에서는 개념 모델 에 집중합니다.
왜 그래프가 필요한가
섹션 제목: “왜 그래프가 필요한가”문서는 독립된 파일의 모음이 아니라, 서로 참조하는 의존 관계의 네트워크 를 형성하고 있습니다.
- 어떤 요구사항 ID가 다른 파일에서 참조된다
- 사양 파일이 링크로 다른 파일을 참조한다
- 상태의 안정도가 의존 관계를 따라 하류로 영향을 미친다
- 섹션이 앵커로 다른 파일에서 참조된다
파일 단위의 lint만으로는, 이러한 파일을 가로지르는 정합성 은 검증할 수 없습니다. 예를 들어 다음과 같은 문제는 그래프를 구축해야 비로소 검출할 수 있습니다.
| 문제 | 그래프가 필요한 이유 |
|---|---|
| 요구사항 ID를 변경했지만, 참조 측이 옛 ID 그대로 | 정의 측과 참조 측을 동시에 볼 필요가 있다 |
requirements.md → design.md → test.md의 체인이 끊어져 있다 |
여러 파일의 참조 관계를 추적 할 필요가 있다 |
A.md → B.md → C.md → A.md의 순환 의존 |
그래프 전체를 보고 사이클 을 검출할 필요가 있다 |
| 어디에서도 참조되지 않는 고립 문서 | 모든 파일의 피참조 상황 을 집계할 필요가 있다 |
contextlint가 이들을 다룰 수 있는 것은, 파일을 node, 참조를 edge로 하는 유향 그래프 를 내부적으로 구축하고 있기 때문입니다.
Context Graph가 표현하는 것
섹션 제목: “Context Graph가 표현하는 것”Context Graph는 프로젝트 내 문서 의존 관계를 유향 그래프로 모델링한 데이터 구조입니다.
| 구성 요소 | 무엇을 나타내는가 |
|---|---|
| node (정점) | 하나의 Markdown 파일 |
| edge (변) | 어떤 파일에서 다른 파일로의 참조 (링크, ID 참조, 앵커, 이미지) |
| 방향 | “참조하는 측” → “참조되는 측” |
이 모델에 의해, contextlint는 다음과 같은 질문에 답할 수 있게 됩니다.
- 이 파일을 변경했을 때, 영향을 받는 것은 어느 파일인가?
- 이 파일에 관련된 문서의 최소 집합은?
- 문서 간에 순환 의존이 있는가?
- 어디에서도 참조되지 않는 고립된 문서가 있는가?
- 요구사항 → 사양 → 설계 → 테스트의 추적성 체인이 끊어져 있지 않은가?
직접적 영향과 간접적 영향
섹션 제목: “직접적 영향과 간접적 영향”Context Graph는 의존 관계를 따라감으로써, 변경의 영향 범위를 직접 (direct) 과 간접 (transitive) 으로 분류할 수 있습니다.
requirements.md ↓ 참조됨spec.md (직접 영향) ↓ 참조됨test-plan.md (간접 영향)requirements.md를 변경했을 때, spec.md는 직접적으로 영향을 받지만, test-plan.md는 spec.md를 경유하여 간접적으로 영향을 받습니다. grep만으로는 간접적인 영향은 추적할 수 없습니다. Context Graph를 구축함으로써, 변경의 파급 범위 를 재귀적으로 파악할 수 있게 됩니다.
이 정보는 리팩토링이나 요구사항 변경을 할 때 “어느 파일을 함께 리뷰해야 할지” 를 판단하는 재료가 됩니다.
그래프를 기반으로 삼는 의의
섹션 제목: “그래프를 기반으로 삼는 의의”Context Graph는 단순히 하나의 규칙(예를 들어 GRP-001 / GRP-002 / GRP-003)을 위한 내부 데이터 구조가 아닙니다. contextlint 전체의 기반 으로서 여러 기능을 지탱하고 있습니다.
| 기능 | 그래프를 어떻게 사용하는가 |
|---|---|
| 파일 간 참조 규칙 (REF-*) | 파일 간 edge를 따라 참조 대상의 존재를 검증 |
| ID 추적성 (REF-002, GRP-001) | 정의와 참조를 node 위에 매핑하여 추적 |
| 순환 참조 검출 (GRP-002) | 그래프의 사이클을 검출 |
| 고립 문서 검출 (GRP-003) | 입차수가 0인 node를 검출 |
영향 분석 (contextlint impact) |
지정 node에서 도달 가능한 node를 열거 |
컨텍스트 슬라이스 (contextlint slice) |
쿼리에 관련된 최소 부분 그래프를 추출 |
Context Compiler (contextlint compile) |
그래프에서 문서의 역할(entry / hub / leaf / bridge / isolated)을 분류 |
이들은 개별 기능이지만, 같은 그래프 표현을 공유 함으로써, 출력에 일관성이 생깁니다. 어떤 규칙에서 “이 파일은 A에 의존하고 있다” 고 판정된 경우, 영향 분석에서도 같은 의존 관계가 반영됩니다.
결정론성
섹션 제목: “결정론성”Context Graph의 구축은 결정론적 입니다. 같은 문서 집합에서는 항상 같은 그래프가 구축됩니다.
- LLM을 사용하지 않는다
- 파일의 mtime이나 git의 타임스탬프를 참조하지 않는다
- 파일 내용만을 입력으로 한다
이 성질에 의해, CI에서 안정된 결과를 얻을 수 있고, 에디터·AI 호스트·CI의 3계층 피드백에서도 같은 그래프가 공유됩니다(자세한 내용은 3계층 피드백 설계를 참조).