166 lines
5.3 KiB
Markdown
166 lines
5.3 KiB
Markdown
# Architecture
|
||
|
||
## 1. 목표
|
||
|
||
ClariDoc은 문장 생성 능력보다 다음 제어 계층을 우선한다.
|
||
|
||
1. 독자 과업과 문서 유형 계약
|
||
2. 프로젝트 근거의 수집과 source hierarchy
|
||
3. 기술 선택의 rationale completeness
|
||
4. 독자용 prose와 내부 provenance의 격리
|
||
5. 결정적 검사와 독립 reviewer
|
||
6. 재현 가능한 artifact와 hash manifest
|
||
|
||
## 2. 구성요소
|
||
|
||
```text
|
||
models.py brief/source/outline/review/pipeline 계약
|
||
corpus.py 로컬 문서 탐색, heading chunk, ranking, source-pack 생성
|
||
structures.py 문서 유형별 필수 section intent와 decision requirements
|
||
prompts.py planner/writer/reviewer/reviser 경계와 출력 계약
|
||
providers/ Codex, Claude, Antigravity, Mock adapter
|
||
lint.py 구조, 메타 누출, rationale, 안전성의 결정적 검사
|
||
provenance.py evidence-map.json과 provenance.md 생성
|
||
pipeline.py 단계 실행, 리뷰, 수정 루프, quality gate, manifest
|
||
report.py 사람이 읽는 품질 보고서
|
||
cli.py init/collect/validate/outline/lint/run/doctor
|
||
```
|
||
|
||
## 3. 입력 계층
|
||
|
||
### 3.1 Brief
|
||
|
||
Brief는 주제보다 독자 과업과 판단 경계를 먼저 고정한다.
|
||
|
||
- audience / prior knowledge / needs
|
||
- reader goal / core message
|
||
- scope / non-scope
|
||
- prerequisites / required topics
|
||
- citation style / date policy / style profile
|
||
- forbidden claims
|
||
|
||
### 3.2 SourcePack
|
||
|
||
Source는 단순 URL이 아니라 다음 metadata를 가질 수 있다.
|
||
|
||
```json
|
||
{
|
||
"id": "L1234abcd",
|
||
"title": "...",
|
||
"url": "repo:///raw/branch-notes/example.md",
|
||
"facts": ["heading chunk text"],
|
||
"source_type": "branch-note",
|
||
"status": "verified",
|
||
"path": "raw/branch-notes/example.md",
|
||
"heading": "결정 사항",
|
||
"line_start": 120,
|
||
"line_end": 150,
|
||
"claim_ids": ["TX-C1"],
|
||
"decision_ids": ["D13"],
|
||
"priority": 21.7
|
||
}
|
||
```
|
||
|
||
이 metadata는 내부 reasoning과 audit에 사용된다. `citation_style=hidden`에서는 독자용 문서로 출력되지 않는다.
|
||
|
||
## 4. Local corpus retrieval
|
||
|
||
`corpus.py`는 다음 순서로 동작한다.
|
||
|
||
1. configured include directory를 순회한다.
|
||
2. Markdown frontmatter에서 title/status를 읽는다.
|
||
3. heading 단위로 chunk를 만든다.
|
||
4. query와 각 chunk를 BM25 계열 점수로 비교한다.
|
||
5. source type, status, decision/rationale 용어에 가중한다.
|
||
6. 파일별 최대 chunk 수와 전체 top-k를 적용한다.
|
||
7. repository-relative provenance를 포함한 SourcePack으로 변환한다.
|
||
|
||
Source precedence:
|
||
|
||
```text
|
||
canonical-project
|
||
> canonical-concept
|
||
> branch-note
|
||
> official-doc
|
||
> company-tech-blog
|
||
> local-document
|
||
```
|
||
|
||
이 순서는 절대적인 진실 순위가 아니다. 현재 프로젝트 상태에는 canonical project가 우선이고, 선택 배경에는 branch note가 더 유용할 수 있다. Planner와 reviewer가 claim 종류에 맞게 사용해야 한다.
|
||
|
||
## 5. Outline contract
|
||
|
||
각 section은 다음 속성을 가진다.
|
||
|
||
```json
|
||
{
|
||
"id": "04-decision-rationale",
|
||
"intent": "decision_rationale",
|
||
"title": "선택의 이유와 지킨 경계",
|
||
"reader_question": "왜 이 선택을 했고 무엇을 포기했는가?",
|
||
"purpose": "선택을 이유, 대안, 비용, 가드레일과 함께 설명한다.",
|
||
"must_include": ["선택", "이유", "대안", "수용한 비용", "가드레일"],
|
||
"evidence_ids": ["L..."],
|
||
"decision_requirements": [
|
||
"context_or_constraint",
|
||
"choice",
|
||
"why",
|
||
"alternative",
|
||
"accepted_cost",
|
||
"guardrail"
|
||
],
|
||
"transition_to_next": "코드와 흐름으로 연결한다."
|
||
}
|
||
```
|
||
|
||
Planner는 제목·질문·근거 배치를 정교화할 수 있지만 intent의 삭제, 추가, 재배열은 할 수 없다.
|
||
|
||
## 6. Reader/provenance split
|
||
|
||
### Reader-facing surface
|
||
|
||
- `final/document.md`
|
||
- 선택 이유와 기술 설명
|
||
- 공개 citation policy에 따른 citation만 포함
|
||
|
||
### Internal surface
|
||
|
||
- `final/provenance.md`
|
||
- `final/evidence-map.json`
|
||
- normalized source pack
|
||
- raw provider responses
|
||
- review JSON과 lint report
|
||
- provider event log
|
||
|
||
Hidden mode에서 internal source ID, repository path, access date가 `document.md`에 보이면 quality gate error다.
|
||
|
||
## 7. Review topology
|
||
|
||
- logic: 전제, 인과, 결론
|
||
- decision: context, why, alternative, cost, guardrail
|
||
- reader: orientation, cognitive load, natural prose
|
||
- evidence: claim/source fit, hierarchy, status
|
||
- operations: prerequisites, safety, verification, rollback
|
||
- editor: 문장 흐름과 표현, 질문-답 연결, 정보 구조가 반복 문장 틀로 노출되는지 검사
|
||
|
||
Writer와 logic·decision·reader·editor·evidence·operations reviewer를 분리해 self-review 편향을 줄이지만, 여러 모델의 일치는 사실 검증을 대신하지 않는다.
|
||
|
||
## 8. Quality gate
|
||
|
||
```text
|
||
composite = deterministic_lint × deterministic_weight
|
||
+ model_review_mean × model_weight
|
||
```
|
||
|
||
통과 조건은 점수와 함께 blocker/error 개수를 검사한다. revision loop가 최대 횟수에 도달하면 실패 상태와 artifact를 그대로 보존한다.
|
||
|
||
## 9. Failure behavior
|
||
|
||
- invalid input contract: 실행 전 실패
|
||
- planner invalid JSON/contract: deterministic base outline으로 안전 폴백
|
||
- writer/provider failure: 숨기지 않고 pipeline failure
|
||
- reviewer failure: config에 따라 failure 또는 blocker review
|
||
- revision no-op: warning 기록
|
||
- output path traversal in reviewer role: slug sanitize
|
||
- final artifact: manifest로 크기와 SHA-256 기록
|