document-haness/docs/EXTENDING.md

Extending ClariDoc

새로운 문서 유형

1. DocumentType enum에 값을 추가한다.
2. STRUCTURE_SPECS에 독자 질문 순서와 section intent를 정의한다.
3. 각 section에 title, reader question, purpose, must-include를 한국어/영어로 제공한다.
4. lint.py에 해당 유형의 최소 계약을 추가한다.
5. 모든 intent가 고유하고 최소 section 수를 만족하는 테스트를 추가한다.
6. Mock writer에 새 intent의 fixture body를 추가하거나 명시적 fallback을 검증한다.

새 유형을 만들기 전에 기존 유형의 하위 section으로 충분한지 확인한다. 유형이 늘수록 분류 실패 비용도 커진다.

새로운 lint rule

좋은 결정적 rule은 다음 조건을 만족한다.

• 모델 없이 같은 입력에 같은 결과
• 결함 위치와 수정 방향을 설명
• false positive가 관리 가능
• blocker/error/warning/info의 위험 수준이 명확
• 자연어 의미 전체를 안다고 가장하지 않음

LintIssue의 code prefix를 기존 범주에 맞춘다.

• MD: Markdown 무결성
• STR: 구조
• AUD: 독자/오프닝
• READ: 가독성 proxy
• TYPE: 문서 유형 계약
• EVD: 근거
• SAFE: 안전
• VER: 버전
• LEN: 길이
• FIN: 미완료 표시

새로운 reviewer role

1. prompts.py의 ROLE_GUIDANCE에 실패 함수를 정의한다.
2. pipeline config reviewers에 role/provider를 추가한다.
3. 공통 9개 dimension을 유지하거나 조직용 dimension을 parser와 보고서에 명시적으로 확장한다.
4. 다른 reviewer와 중복되는 일반 교정이 아니라 독립적인 결함 탐지 관점을 제공한다.

예: accessibility, localization, API consistency, security threat modeling.

출처 자동 수집기

Core pipeline은 URL을 자동 방문하지 않는다. 수집기를 추가할 때는 별도 단계로 분리한다.

retriever → immutable evidence snapshot → fact extractor → human/source-owner approval → SourcePack

최종 source pack에는 원문 snapshot hash, 추출 위치, 접근 날짜, 허용된 fact를 남기는 것이 바람직하다. 검색 결과 요약을 바로 source truth로 쓰지 않는다.

실행 가능한 코드 검증

코드 블록을 테스트하려면 document generation과 별도의 verifier를 둔다.

1. 언어 태그와 fixture를 추출한다.
2. 격리된 container/sandbox에서 실행한다.
3. expected output과 비교한다.
4. 결과와 로그를 evidence artifact로 저장한다.
5. 문서의 예시 section과 artifact hash를 연결한다.

문서 모델에게 “코드가 맞다”고 평가하게 하는 것만으로 실행 검증을 대체하지 않는다.