Technical Document Flow — 개발자 가이드

프로젝트 개요

Technical Document Flow는 Markdown 기술 문서를 위한 다중 단계 작성 하네스입니다. 참조 문서의 강점인 논증 흐름과 검증 가능성은 재사용하고, 약점이었던 선수지식 과소선언과 전문용어 밀집은 독자 계약·용어 장부·결정적 lint로 보완합니다.

핵심 경계는 다음과 같습니다.

LLM은 독자 모델링, 논리 설계, 설명, 의미 리뷰를 맡습니다.
Python 스크립트는 파일 무결성, 산출물 schema, 제목·링크, 용어 첫 사용, 약어, 예산, 실행 상태를 판정합니다.
최종 성공 여부는 에이전트의 “통과했습니다”가 아니라 09_final_report.json이 결정합니다.

논증 모델

설명문 기본 흐름은 다음과 같습니다.

구체적 실패 → 진짜 원인 → 구현 가능한 요구 → 최소 원리
→ 제약과 선택 → 전체 구조 → 책임 → 요청 하나의 종단 흐름
→ 자동 강제 → 실패 실험 → 대안·비용·한계 → 요구 회수

중요한 것은 장 이름이 아니라 인과관계입니다. 의사결정 문서는 맥락→제약→대안→결정→결과→재검토 조건, 사용 절차는 목표→전제→작동 원리→단계→확인→실패 복구 순서를 사용합니다.

런타임 역할

doc-evidence-curator — 자료에서 사실·추론·권고를 분리해 03_evidence_map.json을 만듭니다.
doc-logic-architect — 독자 계약, 논리 지도, 용어 장부를 만듭니다. 본문은 쓰지 않습니다.
doc-drafter — 승인된 지도대로 07_draft.md를 씁니다.
doc-logic-reviewer — 주장 사슬, 근거, 전환, 결론의 신규 주장을 독립 검토합니다.
doc-reader-reviewer — 선수지식, 용어 밀도, 예시, 인지부하를 독립 검토합니다.
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 경로입니다.

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에 정의합니다.

용어 정책

용어를 없애는 것이 아니라 도입 비용을 통제합니다.

독자가 이미 아는 현상이나 역할을 평이하게 설명합니다.
반복해 쓸 가치가 있을 때 정식 용어와 원어·약어를 붙입니다.
그 용어가 지금 문서에서 왜 필요한지 밝힙니다.
바로 가까운 예시에서 사용합니다.
이후에는 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 출력 회귀에 적합하지 않습니다. 테스트는 다음 세 층으로 나뉩니다.

순수 함수·schema·경계값 단위 테스트
good/bad/identity 방향성 fixture와 offline E2E
명시적으로 켜는 live LLM 평가

golden gate는 좋은 문서가 통과하고, 실패 모드를 심은 문서가 해당 안정적 rule ID로 실패하며, 이미 좋은 문서를 그대로 둔 결과도 통과하는지 확인합니다.

릴리스

RELEASING.md를 따릅니다. 최소 조건은 전체 offline 테스트, quick-rules sync, 버전/manifest sync, 설치 dry-run입니다. live 평가가 실행되지 않았다면 릴리스 노트에 skip 사실을 적습니다.

7.3 KiB Raw Blame History