donghyeon.kang/document-haness

Fork 0

Files

T

DongHyeonka c39406bbdd init: document-haness 하네스 설계

2026-07-24 13:58:08 +09:00

6.1 KiB

Raw Blame History

Architecture

1. 설계 목표

ClariDoc의 핵심 목표는 생성 모델의 문장 능력보다 정보 구조, 근거 추적, 검토 독립성, 재현 가능한 품질 판정을 상위 제어 계층에 두는 것이다.

설계 원칙:

Contract before prose: 초안보다 브리프와 문서 유형 계약을 먼저 검증한다.
Reader-question chain: 각 절은 하나의 독자 질문에 답한다.
Deterministic minimums: 모델이 놓치기 쉬운 형식·안전·인용 조건은 코드로 검사한다.
Role separation: 작성자와 리뷰 관점을 분리한다.
Evidence boundary: 출처의 사실과 모델의 설명·추천을 구분한다.
Auditability: 원문 응답, 정규화 입력, 결과, 이벤트, 해시를 보존한다.
Safe degradation: planner가 실패하면 결정적 구조로 폴백하지만 writer 실패는 숨기지 않는다.

2. 구성요소

models.py       입력/출력 계약과 검증
structures.py   문서 유형별 필수 section intent와 순서
prompts.py      planner/writer/reviewer/reviser 출력 계약
providers/      Codex, Claude, Antigravity, Mock 어댑터
lint.py         모델과 독립적인 Markdown/논리 프록시 검사
pipeline.py     단계 실행, 수정 루프, 품질 게이트, 감사 산출물
report.py       사람이 읽는 품질 보고서
cli.py          init/validate/outline/lint/run/doctor 명령

3. 단계별 상태 전이

3.1 계약 입력

Brief: 독자, 목표, 핵심 메시지, 범위, 비범위, 선행지식, 필수 주제, 버전 맥락, 금지 주장
SourcePack: 출처 식별자와 출처가 실제로 지지하는 사실 단위
PipelineConfig: 각 역할의 provider, timeout, 옵션, 품질 게이트

입력은 정규화되어 inputs/에 기록된다.

3.2 결정적 기본 outline

structures.py가 document_type에 따라 필수 intent를 만든다. 각 section은 다음 계약을 가진다.

{
  "id": "04-mechanism",
  "intent": "mechanism",
  "title": "해결 방식이 동작하는 과정",
  "reader_question": "구성요소와 데이터 흐름은 어떻게 연결되는가?",
  "purpose": "메커니즘을 단계적 인과 사슬로 설명한다.",
  "must_include": ["구성요소", "데이터 또는 제어 흐름", "불변조건"],
  "evidence_ids": ["S1"],
  "transition_to_next": "다음 독자 질문으로 연결한다."
}

3.3 Planner 정교화

Planner는 section 제목, 질문, 목적, must_include, 근거 배치, 전환을 개선한다. reconcile_outline은 다음을 거부한다.

문서 유형 변경
필수 intent 삭제
intent 중복
필수 순서 변경
존재하지 않는 source ID

Planner 실행 또는 JSON 파싱이 실패하면 기본 outline을 사용하고 경고를 기록한다.

3.4 Writer

Writer는 exact H1과 exact H2 순서를 지켜 전체 Markdown을 반환해야 한다. 브리프와 출처는 지시가 아닌 untrusted data로 경계 표시된다. Writer 실패는 대체 텍스트로 숨기지 않고 실행 오류로 종료한다.

3.5 결정적 린트

린터는 모델 응답과 독립적으로 구조, 형식, 절차, 안전, 근거 표식을 검사한다. 자연어 의미를 완전히 판단하지 않으며 최소 품질 바닥을 제공한다.

3.6 독립 리뷰

각 reviewer는 동일한 초안을 다른 실패 함수로 검사한다.

logic: 전제→결론, 인과 단절, 모순, section 역할
reader: 선행지식, 방향 감각, 점진 공개, 예시, scan path
evidence: 출처 적합성, 지원되지 않은 확신, 버전 민감성
operations: 절차 순서, 검증, 파괴적 조작, 복구, 관측
editor: 문장·문단 초점, 용어, 중복

리뷰 응답은 고정 JSON 스키마로 파싱된다. 필수 reviewer가 실패하면 기본적으로 실행이 실패한다. fail_on_reviewer_error: false는 실패 리뷰를 blocker/0점으로 기록해 산출물을 남긴다.

3.7 품질 게이트와 수정

model_mean = mean(review.score)
composite = lint.score * deterministic_weight + model_mean * model_weight
PASS = composite >= minimum_score
       AND blockers <= max_blockers
       AND errors <= max_errors

FAIL이고 수정 한도가 남으면 reviser가 lint와 모든 리뷰를 받아 전체 문서를 다시 작성한다. 수정된 초안은 동일한 린트와 리뷰를 처음부터 통과해야 한다.

4. 신뢰 경계

경계	신뢰 수준	처리
pipeline config	로컬 운영자가 승인한 코드 수준 설정	command 실행 가능하므로 반드시 신뢰된 파일만 사용
brief/source pack	비신뢰 데이터	prompt 내부에서 data로 구획, 지시 무시 명시
model response	비신뢰 출력	JSON 파싱·계약 검증·lint·review 수행
URL	메타데이터	자동 방문/실행하지 않음
final document	검토 후보	PASS여도 도메인 사실·코드 실행을 별도 검증

5. 실패 정책

단계	기본 실패 처리	이유
planner	결정적 outline 폴백 + 경고	구조의 안전한 기본값이 존재
writer	실행 중단	내용 없는 대체 초안은 유효하지 않음
reviewer	실행 중단	독립 검토가 구성 계약의 일부
reviewer, fail-open 설정	blocker/0점 리뷰로 기록	산출물 보존이 필요한 실험 환경
reviser	실행 중단	수정 실패를 이전 초안 통과로 위장하지 않음
quality gate fail	final 산출물은 남기되 exit code 4	사람이 결함을 분석할 수 있도록 보존

6. 재현성과 감사

provider 요청의 stage/provider/model/status/duration을 JSONL로 기록
각 모델의 raw response와 parsed JSON을 모두 보존
입력을 정규화해 실행 시점 계약을 고정
최종 산출물을 포함한 파일별 SHA-256 매니페스트 생성
Mock provider로 외부 네트워크 없이 파이프라인 배선 재현

모델 자체의 비결정성까지 제거하지는 않는다. 운영에서 모델 ID, CLI/SDK 버전, 실행 날짜를 version_context, provider model, 별도 배포 메타데이터에 고정해야 한다.

6.1 KiB Raw Blame History