67 lines
2.7 KiB
Markdown
67 lines
2.7 KiB
Markdown
# 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을 자동 방문하지 않는다. 수집기를 추가할 때는 별도 단계로 분리한다.
|
|
|
|
```text
|
|
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를 연결한다.
|
|
|
|
문서 모델에게 “코드가 맞다”고 평가하게 하는 것만으로 실행 검증을 대체하지 않는다.
|