166 lines
5.8 KiB
Markdown
166 lines
5.8 KiB
Markdown
# ClariDoc Harness 검증 보고서
|
|
|
|
> 검증일: 2026-07-23
|
|
> 대상 버전: `claridoc-harness 0.1.0`
|
|
> 환경: Linux x86_64, Python 3.13.5
|
|
> 호환성 계약: Python 3.10 이상
|
|
|
|
## 1. 판정
|
|
|
|
소스 패키지, 오프라인 Mock 종단 간 파이프라인, 세 provider 어댑터의 격리 테스트, wheel 빌드·설치형 CLI를 검증했다.
|
|
|
|
**판정: 배포 가능한 개발자용 초기 버전.**
|
|
|
|
다만 Codex, Claude, Google Antigravity의 실제 실행 파일·SDK·인증이 이 검증 환경에 없으므로, 세 provider에 대한 **실제 모델 호출은 수행하지 않았다.** live 품질이나 계정별 모델 호환성을 증명하는 보고서가 아니다.
|
|
|
|
## 2. 자동화 테스트
|
|
|
|
실행 명령:
|
|
|
|
```bash
|
|
bash scripts/test.sh
|
|
```
|
|
|
|
결과:
|
|
|
|
```text
|
|
Ran 31 tests
|
|
OK
|
|
```
|
|
|
|
검증 범위:
|
|
|
|
- 브리프, source pack, pipeline, outline, review 런타임 계약
|
|
- 7개 문서 유형의 필수 intent와 순서
|
|
- planner 구조 병합의 삭제·순서·출처 위반 차단
|
|
- 리뷰의 9개 고정 평가 차원, severity, 유한 수치 검사
|
|
- 빈 reviewer 목록, reviewer role 중복, 비정상 품질 게이트 차단
|
|
- 필수 H2 누락·중복·순서 검사
|
|
- 일반 source ID와 존재하지 않는 source marker 검사
|
|
- 파괴적 명령의 영향 경고·복구점·검증 통제
|
|
- reviewer role을 통한 artifact 경로 탈출 방지
|
|
- Codex와 Claude의 가짜 실행 파일 기반 stdin/출력/인수 계약
|
|
- Antigravity의 가짜 SDK 기반 설정 전달, async 응답, 작업 디렉터리 복구
|
|
- Mock 종단 간 실행, 수정 한도, 품질 게이트, 이벤트, manifest
|
|
- manifest 파일 크기와 SHA-256 재검산
|
|
- CLI `init`과 `validate`
|
|
|
|
Coverage.py로 측정한 statement coverage는 **82%**였다. 이 수치는 테스트 범위의 보조 지표이며 정확성 증명으로 사용하지 않는다.
|
|
|
|
## 3. Python·JSON·문서 무결성
|
|
|
|
```bash
|
|
bash scripts/verify.sh
|
|
```
|
|
|
|
검증 내용:
|
|
|
|
- 모든 `src/`와 `tests/` Python 파일을 Python 3.10 grammar로 파싱
|
|
- 저장소 JSON 파일 구문 검사
|
|
- 로컬 Markdown 상대 링크 해석
|
|
- 예제 브리프와 source pack 런타임 검증
|
|
- Mock 종단 간 실행
|
|
- Mock 점수가 합성값임을 알리는 경고 존재
|
|
- 예제 run manifest의 모든 크기와 SHA-256 재검산
|
|
|
|
별도로 Draft 2020-12 validator를 사용해 다음 인스턴스를 검증했다.
|
|
|
|
- 예제 brief → `brief.schema.json`
|
|
- 예제 source pack → `source-pack.schema.json`
|
|
- Mock pipeline과 multi-agent pipeline → `pipeline.schema.json`
|
|
- 생성된 outline → `outline.schema.json`
|
|
- 네 개의 raw reviewer 응답 → `review.schema.json`
|
|
|
|
모두 통과했다. `jsonschema`는 검증 환경에서만 사용했으며 ClariDoc core runtime 의존성에는 포함하지 않았다.
|
|
|
|
## 4. 오프라인 종단 간 실행
|
|
|
|
실행 명령:
|
|
|
|
```bash
|
|
bash scripts/run-demo.sh
|
|
```
|
|
|
|
결과:
|
|
|
|
```text
|
|
GATE: PASS
|
|
SCORE: 89.3/100
|
|
```
|
|
|
|
결정적 lint 점수는 `87.5/100`, blocker와 error는 각각 `0`이었다. 네 reviewer 점수는 모두 Mock fixture가 생성한 합성값이다. `run.json`과 품질 보고서에는 다음 경고가 자동 기록된다.
|
|
|
|
```text
|
|
All providers are deterministic mocks. This run validates pipeline mechanics only;
|
|
model-review scores are synthetic and must not be used as evidence of document quality.
|
|
```
|
|
|
|
따라서 이 PASS는 구조 계약, 린터, 리뷰 파싱, 게이트, artifact 배선이 동작했다는 의미다. 외부 모델의 문서 품질이나 예제 문서의 사실성을 의미하지 않는다.
|
|
|
|
## 5. Wheel 빌드와 깨끗한 설치
|
|
|
|
빌드 artifact:
|
|
|
|
```text
|
|
dist/claridoc_harness-0.1.0-py3-none-any.whl
|
|
SHA-256: 1dd71f73466a255e4a2a22d60482b6c1bc0e629de9d5b17110bcf4f0fb0b4cc6
|
|
```
|
|
|
|
검증 절차:
|
|
|
|
1. PEP 517 wheel 빌드
|
|
2. 새 가상환경 생성
|
|
3. wheel을 `--no-deps`로 설치
|
|
4. `claridoc --version`
|
|
5. `claridoc validate`
|
|
6. Mock provider `doctor`
|
|
7. 설치된 CLI로 전체 Mock pipeline 실행
|
|
|
|
결과:
|
|
|
|
```text
|
|
claridoc 0.1.0
|
|
VALID: API 재시도는 횟수가 아니라 부하 예산으로 설계한다 (technical_blog), 3 sources
|
|
GATE: PASS
|
|
SCORE: 89.3/100
|
|
```
|
|
|
|
## 6. Provider 검증 수준
|
|
|
|
| Provider | 구현 표면 | 수행한 검증 | 실제 호출 |
|
|
|---|---|---|---|
|
|
| Codex | `codex exec`, stdin, `--output-last-message`, read-only sandbox | 가짜 executable로 command와 출력 수집 검증 | 미수행 |
|
|
| Claude | `claude -p --output-format text`, stdin | 가짜 executable로 piped prompt와 stdout 검증 | 미수행 |
|
|
| Antigravity | `google.antigravity.Agent`, `LocalAgentConfig`, async `chat` | 가짜 SDK로 config/model, cwd 격리, async text 검증 | 미수행 |
|
|
|
|
실제 multi-agent config에 대한 `doctor` 결과는 exit code `3`이며 세 항목 모두 `MISSING`이었다.
|
|
|
|
```text
|
|
[MISSING] codex: codex exec
|
|
[MISSING] claude: claude -p
|
|
[MISSING] antigravity: google-antigravity SDK
|
|
```
|
|
|
|
`doctor`는 설치 여부만 진단한다. 설치 후에도 로그인, 조직 권한, quota, 모델 ID, SDK 버전별 옵션은 live invocation으로 확인해야 한다.
|
|
|
|
## 7. 확인된 제한
|
|
|
|
- source pack의 URL을 자동 방문하거나 사실을 자동 수집하지 않는다.
|
|
- source marker가 존재해도 문장이 source fact를 정확히 함의하는지는 완전하게 증명하지 않는다.
|
|
- LLM reviewer 간 합의는 진실의 증명이 아니다.
|
|
- 코드 예제와 명령을 실제 대상 시스템에서 실행하지 않는다.
|
|
- 한국어·영어 문장 길이와 문단 분리는 휴리스틱이다.
|
|
- Windows용 `run-demo.ps1`은 제공하지만 이 Linux 환경에는 PowerShell이 없어 실행 검증하지 않았다.
|
|
- 실제 게시 전에는 도메인 소유자 검토, 코드 실행, 보안 검토, 출처 원문 대조가 필요하다.
|
|
|
|
## 8. 재현 명령
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
. .venv/bin/activate
|
|
python -m pip install -e .
|
|
|
|
bash scripts/verify.sh
|
|
claridoc doctor --config config/pipeline.multi-agent.example.json
|
|
```
|