init: document-haness 설계
This commit is contained in:
DongHyeonka
@@ -0,0 +1,107 @@
|
||||
# Technical Document Flow — 개발자 가이드
|
||||
|
||||
## 프로젝트 개요
|
||||
|
||||
Technical Document Flow는 Markdown 기술 문서를 위한 다중 단계 작성 하네스입니다. 참조 문서의 강점인 논증 흐름과 검증 가능성은 재사용하고, 약점이었던 선수지식 과소선언과 전문용어 밀집은 독자 계약·용어 장부·결정적 lint로 보완합니다.
|
||||
|
||||
핵심 경계는 다음과 같습니다.
|
||||
|
||||
- LLM은 독자 모델링, 논리 설계, 설명, 의미 리뷰를 맡습니다.
|
||||
- Python 스크립트는 파일 무결성, 산출물 schema, 제목·링크, 용어 첫 사용, 약어, 예산, 실행 상태를 판정합니다.
|
||||
- 최종 성공 여부는 에이전트의 “통과했습니다”가 아니라 `09_final_report.json`이 결정합니다.
|
||||
|
||||
## 논증 모델
|
||||
|
||||
설명문 기본 흐름은 다음과 같습니다.
|
||||
|
||||
```text
|
||||
구체적 실패 → 진짜 원인 → 구현 가능한 요구 → 최소 원리
|
||||
→ 제약과 선택 → 전체 구조 → 책임 → 요청 하나의 종단 흐름
|
||||
→ 자동 강제 → 실패 실험 → 대안·비용·한계 → 요구 회수
|
||||
```
|
||||
|
||||
중요한 것은 장 이름이 아니라 인과관계입니다. 의사결정 문서는 맥락→제약→대안→결정→결과→재검토 조건, 사용 절차는 목표→전제→작동 원리→단계→확인→실패 복구 순서를 사용합니다.
|
||||
|
||||
## 런타임 역할
|
||||
|
||||
1. `doc-evidence-curator` — 자료에서 사실·추론·권고를 분리해 `03_evidence_map.json`을 만듭니다.
|
||||
2. `doc-logic-architect` — 독자 계약, 논리 지도, 용어 장부를 만듭니다. 본문은 쓰지 않습니다.
|
||||
3. `doc-drafter` — 승인된 지도대로 `07_draft.md`를 씁니다.
|
||||
4. `doc-logic-reviewer` — 주장 사슬, 근거, 전환, 결론의 신규 주장을 독립 검토합니다.
|
||||
5. `doc-reader-reviewer` — 선수지식, 용어 밀도, 예시, 인지부하를 독립 검토합니다.
|
||||
6. `doc-finalizer` — 현재 review 계약을 검증하고 확정된 `07_draft.md`를 byte-identical `final.md`로 복사합니다. 본문은 고치지 않습니다.
|
||||
역할 파일은 다른 에이전트를 임의로 부르지 않습니다. 호출 순서와 재시도는 canonical `SKILL.md`만 결정합니다.
|
||||
|
||||
## 경로
|
||||
|
||||
- `light`: 짧고 구조가 이미 선 초안. 증거 큐레이션과 독립 리뷰를 생략할 수 있지만 독자 계약·논리 지도·용어 장부·lint는 생략하지 않습니다.
|
||||
- `standard`: 기본 경로. 근거→설계→집필→논리/독자 병렬 리뷰→byte-identical final 복사→lint입니다. 수정이 필요하면 Phase 3의 draft로 돌아갑니다.
|
||||
- `deep`: 많은 근거, 초장문, 명시적 정밀 요청. standard에 무손실 장문 분할과 엄격한 gate를 더합니다.
|
||||
|
||||
경로 점수 실패는 `standard`로 안전하게 내려갑니다. `light`나 `standard` 결과가 gate를 통과하지 못했다고 자동으로 성공 처리하지 않습니다.
|
||||
|
||||
## 상태와 산출물
|
||||
|
||||
`00_run.json`은 실행 상태의 단일 기준입니다. 다음은 standard/deep write/revise 경로입니다.
|
||||
|
||||
```text
|
||||
initialized → evidence_ready → planned → drafted → reviewed
|
||||
│
|
||||
└→ byte-identical final 복사 → lint pass
|
||||
│
|
||||
└→ finalized → verified
|
||||
|
||||
finding 또는 lint 수정 → Phase 3의 07_draft.md → 적용 review 재실행 → final 재복사 → lint 재실행
|
||||
외부 결정·상류 계약 blocker → hold_for_review
|
||||
복구 불가능한 실행 오류·중단 → failed / incomplete
|
||||
```
|
||||
|
||||
light write/revise는 `evidence_ready`를 건너뛰며, 두 독립 리뷰를 생략하면 `reviewed`도 거치지 않습니다. review mode는 `planned → reviewed`에서 검증하고 `final.md`, `finalized`, `verified`를 만들거나 거치지 않습니다.
|
||||
|
||||
각 JSON에는 `schema_version`이 있어야 합니다. 원자적 쓰기 후 상태를 전진시킵니다. 중단된 실행은 `incomplete`, 복구할 수 없는 실행 오류는 `failed`, 사람 판단이 필요한 실행은 `hold_for_review`로 남기며 파일이 있다는 이유만으로 완료로 간주하지 않습니다.
|
||||
|
||||
산출물 이름은 [artifact-contracts.md](skills/technical-doc-flow/references/artifact-contracts.md)에 정의합니다.
|
||||
|
||||
## 용어 정책
|
||||
|
||||
용어를 없애는 것이 아니라 도입 비용을 통제합니다.
|
||||
|
||||
1. 독자가 이미 아는 현상이나 역할을 평이하게 설명합니다.
|
||||
2. 반복해 쓸 가치가 있을 때 정식 용어와 원어·약어를 붙입니다.
|
||||
3. 그 용어가 지금 문서에서 왜 필요한지 밝힙니다.
|
||||
4. 바로 가까운 예시에서 사용합니다.
|
||||
5. 이후에는 canonical 이름 하나를 유지합니다.
|
||||
|
||||
기본 예산은 한 문단 신규 용어 2개, 한 절 신규 용어 7개입니다. 이는 기계적 삭제 기준이 아니라 분할·재설명 신호입니다. fenced·indented code block 전체, inline code 식별자·명령·인수, 링크·인용 대상, 숫자·범위·단위·날짜·버전의 의미 연결, 표준명과 인용 원문은 보호합니다.
|
||||
|
||||
## 결정적 도구
|
||||
|
||||
- `init_run.py`: 실행 디렉터리 원자 할당, 입력·자료 해시, 경로 권고
|
||||
- `lint_document.py`: Markdown·논리 지도·용어 장부 계약 검사
|
||||
- `verify_run.py`: route별 산출물과 최종 상태 검증
|
||||
- `split_document.py` / `reassemble_document.py`: 장문을 제목·문단 경계에서 무손실 처리
|
||||
- `build_quick_rules.py`: 규칙 SSOT에서 런타임 요약 생성
|
||||
- `check_release_sync.py`: VERSION·매니페스트·진입점·산출물 설명의 드리프트 차단
|
||||
|
||||
## 실패 처리
|
||||
|
||||
- 입력·schema가 잘못되면 exit 2로 중단하고 입력을 고칩니다.
|
||||
- lint error가 있으면 현재 final candidate를 게시하지 않습니다. Phase 3의 `07_draft.md` 또는 해당 상류 artifact를 고친 뒤 적용되는 review, byte-identical final 복사, lint를 다시 실행합니다.
|
||||
- finalizer는 critical/high뿐 아니라 medium/low finding도 병합하거나 수정하지 않습니다. 실제로 고칠 finding은 `doc-drafter` 또는 해당 상류 owner로 반환합니다.
|
||||
- 같은 원인의 두 번째 lint에도 error가 남거나 근거 충돌에 외부 결정·상류 계약 변경이 필요하면 `hold_for_review`입니다.
|
||||
- warning은 숨기지 않고 최종 보고에 남깁니다. `deep` 또는 사용자가 엄격 검사를 요구하면 warning도 gate 실패로 올릴 수 있습니다.
|
||||
- 장문 재조립의 해시, 누락 청크, 빈 청크가 맞지 않으면 원문을 추측해 복구하지 않습니다.
|
||||
|
||||
## 테스트 전략
|
||||
|
||||
문장 전체의 문자열 일치는 LLM 출력 회귀에 적합하지 않습니다. 테스트는 다음 세 층으로 나뉩니다.
|
||||
|
||||
1. 순수 함수·schema·경계값 단위 테스트
|
||||
2. good/bad/identity 방향성 fixture와 offline E2E
|
||||
3. 명시적으로 켜는 live LLM 평가
|
||||
|
||||
golden gate는 좋은 문서가 통과하고, 실패 모드를 심은 문서가 해당 안정적 rule ID로 실패하며, 이미 좋은 문서를 그대로 둔 결과도 통과하는지 확인합니다.
|
||||
|
||||
## 릴리스
|
||||
|
||||
`RELEASING.md`를 따릅니다. 최소 조건은 전체 offline 테스트, quick-rules sync, 버전/manifest sync, 설치 dry-run입니다. live 평가가 실행되지 않았다면 릴리스 노트에 skip 사실을 적습니다.
|
||||
Reference in New Issue
Block a user