init: document-haness 설계

2026-07-23 17:52:22 +09:00
parent 993788c14e
commit d6f78f92a0
127 changed files with 20099 additions and 1 deletions
@@ -0,0 +1,250 @@
+{
+  "$schema": "../schemas/quality-rules.schema.json",
+  "schema_version": "1.0",
+  "rules_version": "1.4.0",
+  "thresholds": {
+    "heading": {
+      "required_h1_count": 1,
+      "max_level_jump": 1
+    },
+    "term": {
+      "max_new_terms_per_sentence": 2,
+      "max_new_terms_per_paragraph": 2,
+      "max_new_terms_per_section": 7,
+      "definition_window_chars": 240,
+      "max_assumed_known": 12,
+      "max_assumed_per_prerequisite": 4
+    },
+    "paragraph": {
+      "max_chars": 900,
+      "max_sentences": 7
+    },
+    "logic": {
+      "core_claim_max_reader_paragraphs": 2
+    },
+    "route": {
+      "light": {
+        "requires_existing_draft": true,
+        "max_input_chars": 4000,
+        "max_sources": 2,
+        "max_headings": 8
+      },
+      "standard": {
+        "max_input_chars": 12000,
+        "max_sources": 8,
+        "max_headings": 24
+      },
+      "deep": {
+        "min_input_chars": 12001,
+        "min_sources": 9,
+        "min_headings": 25
+      }
+    },
+    "split": {
+      "default_max_chars": 12000,
+      "minimum_h2_fill_ratio": 0.35
+    },
+    "finalization": {
+      "max_change_rate": 0.0
+    }
+  },
+  "patterns": {
+    "placeholders": [
+      "\\bTODO\\b",
+      "\\bTBD\\b",
+      "\\bFIXME\\b",
+      "\\bXXX\\b",
+      "\\?\\?\\?",
+      "\\{\\{[^{}]+\\}\\}",
+      "\\[(?:작성|보강|확인|추가)\\s*(?:예정|필요|중)?\\]"
+    ],
+    "evidence_markers": [
+      "<!--\\s*claim:{claim_id}\\s*-->",
+      "\\[(?:근거|관찰|측정|도출|권고|가정):\\s*{claim_id}\\]"
+    ],
+    "technical_candidate_allowlist": [
+      "Markdown",
+      "UTF-8",
+      "SHA256",
+      "TODO",
+      "TBD",
+      "FIXME",
+      "XXX"
+    ],
+    "technical_lowercase_candidates": [
+      "backpressure",
+      "deadlock",
+      "deserialization",
+      "idempotency",
+      "memoization",
+      "observability",
+      "serialization",
+      "sharding",
+      "throughput"
+    ]
+  },
+  "rules": [
+    {
+      "id": "DOC-H001",
+      "category": "heading",
+      "severity": "error",
+      "description": "제목 단계는 한 번에 한 수준만 내려가야 합니다."
+    },
+    {
+      "id": "DOC-H002",
+      "category": "heading",
+      "severity": "error",
+      "description": "문서에는 비어 있지 않은 H1 제목이 정확히 하나 있어야 합니다."
+    },
+    {
+      "id": "DOC-M001",
+      "category": "markdown",
+      "severity": "error",
+      "description": "TODO, TBD 같은 미완성 표시를 최종 문서에 남기지 않습니다."
+    },
+    {
+      "id": "DOC-M002",
+      "category": "markdown",
+      "severity": "error",
+      "description": "Markdown 코드 fence는 같은 기호로 닫혀야 합니다."
+    },
+    {
+      "id": "DOC-M003",
+      "category": "markdown",
+      "severity": "error",
+      "description": "문서 내부 앵커 링크는 실제 제목이나 명시적 id를 가리켜야 합니다."
+    },
+    {
+      "id": "DOC-M004",
+      "category": "markdown",
+      "severity": "error",
+      "description": "HTML 주석은 문서 끝 전에 닫혀야 하며 렌더링되는 내용을 숨기지 않아야 합니다."
+    },
+    {
+      "id": "DOC-L001",
+      "category": "logic",
+      "severity": "error",
+      "description": "logic map의 섹션은 문서에 빠짐없이 같은 순서로 나타나야 합니다."
+    },
+    {
+      "id": "DOC-L002",
+      "category": "logic",
+      "severity": "error",
+      "description": "logic map의 핵심 주장은 문서 앞부분에 명시되어야 합니다."
+    },
+    {
+      "id": "DOC-L003",
+      "category": "logic",
+      "severity": "error",
+      "description": "근거가 필요한 절은 연결된 claim id를 본문 marker로 표시해야 합니다."
+    },
+    {
+      "id": "DOC-L004",
+      "category": "logic",
+      "severity": "error",
+      "description": "logic map 섹션의 필수 필드와 의존 순서는 완결되어야 합니다."
+    },
+    {
+      "id": "DOC-T001",
+      "category": "terminology",
+      "severity": "error",
+      "description": "새 용어의 첫 등장은 용어 장부에 적은 쉬운 설명 문구를 포함해야 합니다."
+    },
+    {
+      "id": "DOC-T002",
+      "category": "terminology",
+      "severity": "error",
+      "description": "별칭은 정식 용어의 첫 설명보다 먼저 사용하지 않습니다."
+    },
+    {
+      "id": "DOC-T003",
+      "category": "terminology",
+      "severity": "error",
+      "description": "약어는 정식 이름과 쉬운 뜻을 먼저 소개한 뒤 사용해야 합니다."
+    },
+    {
+      "id": "DOC-T004",
+      "category": "terminology",
+      "severity": "error",
+      "description": "한 문단에서 새로 소개하는 용어 수는 설정된 예산을 넘지 않아야 합니다."
+    },
+    {
+      "id": "DOC-T005",
+      "category": "terminology",
+      "severity": "error",
+      "description": "한 문장에서 새로 소개하는 용어 수는 설정된 예산을 넘지 않아야 합니다."
+    },
+    {
+      "id": "DOC-T006",
+      "category": "terminology",
+      "severity": "error",
+      "description": "한 절에서 새로 소개하는 용어 수는 설정된 예산을 넘지 않아야 합니다."
+    },
+    {
+      "id": "DOC-T007",
+      "category": "terminology",
+      "severity": "error",
+      "description": "영문 및 코드형 기술 용어 후보는 용어 장부 또는 독자 계약에 등록해야 합니다."
+    },
+    {
+      "id": "DOC-T008",
+      "category": "terminology",
+      "severity": "warning",
+      "description": "독자가 이미 안다고 가정하는 용어 목록은 선수지식과 비례하는 범위로 제한합니다."
+    },
+    {
+      "id": "DOC-T009",
+      "category": "terminology",
+      "severity": "error",
+      "description": "용어 장부와 독자 계약의 assumed_known 목록은 정확히 일치해야 합니다."
+    },
+    {
+      "id": "DOC-P001",
+      "category": "paragraph",
+      "severity": "warning",
+      "description": "긴 문단은 독자가 한 번에 따라갈 수 있도록 나눕니다."
+    },
+    {
+      "id": "DOC-P002",
+      "category": "paragraph",
+      "severity": "warning",
+      "description": "한 문단의 문장 수가 지나치게 많지 않아야 합니다."
+    },
+    {
+      "id": "DOC-F001",
+      "category": "fidelity",
+      "severity": "error",
+      "description": "기준 문서의 fenced·indented code block은 정확히 보존해야 합니다."
+    },
+    {
+      "id": "DOC-F002",
+      "category": "fidelity",
+      "severity": "error",
+      "description": "기준 문서의 inline code 식별자·명령·인수는 보존해야 합니다."
+    },
+    {
+      "id": "DOC-F003",
+      "category": "fidelity",
+      "severity": "error",
+      "description": "기준 문서의 http·https·ftp·ftps·file·mailto·ssh·git 절대 URI와 Markdown link/citation target은 보존해야 합니다."
+    },
+    {
+      "id": "DOC-F004",
+      "category": "fidelity",
+      "severity": "error",
+      "description": "기준 문서의 숫자, 단위, 날짜, 버전은 의미 연결과 함께 보존해야 합니다."
+    },
+    {
+      "id": "DOC-F005",
+      "category": "fidelity",
+      "severity": "error",
+      "description": "기준 문서의 명시적 큰따옴표와 blockquote 인용은 보존해야 합니다."
+    },
+    {
+      "id": "FNL-001",
+      "category": "finalization",
+      "severity": "error",
+      "description": "finalizer의 초안 대비 변경률은 설정된 상한을 넘지 않아야 합니다."
+    }
+  ]
+}
@@ -0,0 +1,62 @@
+{
+  "schema_version": "1.0",
+  "name": "technical-doc-flow",
+  "agents": [
+    "doc-evidence-curator",
+    "doc-logic-architect",
+    "doc-drafter",
+    "doc-logic-reviewer",
+    "doc-reader-reviewer",
+    "doc-finalizer"
+  ],
+  "artifacts": {
+    "always": [
+      "00_run.json",
+      "01_input.md",
+      "01_sources.json",
+      "02_reader_contract.json",
+      "04_logic_map.json",
+      "05_term_ledger.json"
+    ],
+    "light": [
+      "07_draft.md",
+      "08_lint.json",
+      "final.md",
+      "09_final_report.json"
+    ],
+    "standard": [
+      "03_evidence_map.json",
+      "07_draft.md",
+      "08_logic_review.json",
+      "08_reader_review.json",
+      "08_lint.json",
+      "final.md",
+      "09_final_report.json"
+    ],
+    "deep": [
+      "03_evidence_map.json",
+      "07_draft.md",
+      "08_logic_review.json",
+      "08_reader_review.json",
+      "08_lint.json",
+      "final.md",
+      "09_final_report.json"
+    ],
+    "review_mode": [
+      "07_draft.md",
+      "08_logic_review.json",
+      "08_reader_review.json",
+      "08_lint.json",
+      "09_final_report.json"
+    ]
+  },
+  "supported_document_kinds": [
+    "explanation",
+    "decision",
+    "how-to",
+    "reference"
+  ],
+  "supported_output_formats": [
+    "markdown"
+  ]
+}