콘텐츠로 이동
contextlint

REF-002 ID의 정의와 참조

개요

섹션 제목: “개요”

정의 파일(요구사항서 등)에서 선언된 ID와, 다른 파일(테스트나 설계서 등)로부터의 참조가 양방향으로 정합한지를 검증합니다. 프로젝트 스코프 의 규칙으로, include로 읽어들인 모든 문서를 횡단하여 평가됩니다.

  • 참조되어 있지만 정의가 없는 ID → error
  • 정의되어 있지만 참조되지 않은 ID → warning

왜 필요한가

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

요구사항 ID는 정의 파일(requirements.md 등)에서 선언되어, 테스트·설계·구현 문서로부터 참조되는 구조가 되기 쉽습니다. 요구사항을 이름 변경하거나 삭제해도, 참조 측 문서는 자동으로 따라가지 않습니다. 반대로 정의된 요구사항이 어디에서도 참조되지 않으면, 그 요구사항은 구현이나 테스트에 연결되지 않은 가능성이 있습니다. 이 규칙은 양방향 추적성을 기계적으로 검증합니다.

옵션

섹션 제목: “옵션”
필드타입필수설명
definitionsstring✓ID를 정의할 파일의 glob
referencesstring[]✓ID를 참조할 파일의 glob 배열
idColumnstring✓정의 파일에서 ID가 저장된 컬럼명
idPatternstring✓ID로서 취급할 값의 정규표현식

idPattern은 정의 측의 테이블 컬럼 값, 참조 측 문서 내의 텍스트 양쪽의 대조에 사용됩니다. 일반 텍스트 중의 토큰도 대상이므로, ID 같지 않은 단어를 잘못 잡아내지 않도록 명시적인 접두사(^REQ- 등)를 포함시키는 것이 안전합니다.

위반 예시

섹션 제목: “위반 예시”
docs/requirements.md:
| ID     | 내용             |
| ------ | ---------------- |
| REQ-01 | 사용자 등록      |
| REQ-02 | 비밀번호 재설정  |


docs/tests.md:
- REQ-01의 테스트는 ...
- REQ-99의 테스트는 ...

REQ-99가 정의되어 있지 않기 때문에 error, REQ-02가 어디에서도 참조되지 않기 때문에 warning이 됩니다.

docs/tests.md
  line 2  error  ID "REQ-99" is referenced but not defined in any definition file  REF-002


docs/requirements.md
  line 4  warning  ID "REQ-02" is defined but never referenced  REF-002

수정 후

섹션 제목: “수정 후”

정의 측에 없는 REQ-99를 REQ-02로 수정하고, REQ-02가 참조되도록 합니다.

docs/tests.md:
- REQ-01의 테스트는 ...
- REQ-02의 테스트는 ...

설정 예시

섹션 제목: “설정 예시”
{
  "rule": "ref002",
  "options": {
    "definitions": "**/requirements.md",
    "references": ["**/tests.md", "**/design.md"],
    "idColumn": "ID",
    "idPattern": "^REQ-\\d+$"
  }
}

관련 규칙

섹션 제목: “관련 규칙”