질문이 지식으로 남지 않는 문제 — 3대 계통 LLM-Wiki를 폴더 구조와 검증기로 만들기 (헤르메스 사례글 12편)

계통A/원본/  계통A/정리/  계통A/종합/
계통B/원본/  계통B/정리/  계통B/종합/

20_정리/일주/을축일주.md   (front-matter에 gyetong: A)

hanbadook-wiki/
├── 00_규약/                  # 이 위키의 헌법. 수정에 승인 필요
│   ├── AGENTS.md            # 에이전트 지침 (전문은 3-4에)
│   ├── 문서서식.md           # front-matter 필수 필드
│   ├── 계통정의.md           # 3대 계통 판별 신호 (아직 미확정)
│   ├── ingest절차.md         # 6단계 + 분모·분자 보고
│   └── check_wiki.py        # 서식 검증기
├── 10_원본/                  # 계통별 물리 분리
│   ├── 계통A/slides/
│   ├── 계통B/slides/
│   └── 계통C/slides/
├── 20_정리/                  # 개념 1 : 문서 1
│   ├── 일주/  격국/  용신/  통변/
├── 30_종합/
│   ├── 대비/                 # 계통 복수값이 허용되는 유일한 폴더
│   ├── 논점/  사례/
├── 40_질의/                  # 질문 → 근거 → 답 → 환류
│   ├── open/  closed/
├── 50_영수증/
│   ├── ingest/  실행/  ASK/
└── 90_보류/                  # 멈춘 것들이 사라지지 않게
    ├── 회수실패/  계통상충/

# 한바둑 LLM-Wiki 에이전트 지침 v1.0

너는 한바둑 명리 지식 위키를 읽고 갱신하는 작업 에이전트다.
아래는 부탁이 아니라 판정 기준이다. 어길 수 없는 것은 check_wiki.py가 막는다.

## 1. 계통 분리 — 가장 먼저 지킬 것

- 이 위키는 3대 계통의 서술을 따로 관리한다. 계통이 다르면 같은 용어라도 다른 문서다.
- 문서를 만들거나 고치기 전에 gyetong 필드를 먼저 정한다. 정하지 못하면 만들지 않는다.
- 계통을 판별할 수 없으면 추측하지 말고 멈추고 사람에게 묻는다.
- 계통 판별 근거는 00_규약/계통정의.md의 판별 신호만 쓴다. 문체나 인상으로 정하지 않는다.
- 여러 계통을 한 문서에 담는 것은 30_종합/대비/에서만 허용되며, 이때도 계통별로 절을 나눈다.

## 2. 근거 — 없으면 쓰지 않는다

- 모든 주장에는 slide ID가 붙어야 한다. ID 없는 문장은 위키에 넣지 않는다.
- 원문을 옮기지 않는다. 인용은 한 문장 이내로 하고 나머지는 ID로 가리킨다.
- 근거를 찾지 못하면 status: 확인못함으로 두고 본문을 비운다.
  빈칸을 그럴듯한 설명으로 메우는 것이 이 위키에서 가장 큰 사고다.

## 3. 멈추는 조건 — 다음 중 하나라도 해당하면 작업을 중단하고 보고한다

- 계통을 판별할 수 없다
- 근거 slide를 회수하지 못했다
- 기존 문서와 내용이 충돌한다
- 요청이 문서 10건 이상을 한 번에 바꾸라고 한다
- 되돌릴 수 없는 조작(파일 삭제, 대량 이동)이 필요하다

멈출 때는 50_영수증/ASK/에 사유 코드와 함께 한 건을 남긴다.

## 4. 권한 경계 — 되돌릴 수 있는가

| 작업 | 권한 |
| --- | --- |
| 문서 읽기, 검색 | 자유 |
| 새 문서 만들기 | 자유 (검증기 통과 시) |
| 기존 문서 수정 | 자유 (version 올리고 이전 값 영수증에 기록) |
| 문서 삭제, 대량 이동, 폴더 구조 변경 | 승인 필요 |
| 00_규약/ 수정 | 승인 필요 |

기준은 대가의 크기가 아니라 복원 가능성이다. 되돌릴 수 없으면 승인을 받는다.

## 5. 보고 형식 — 분모와 분자를 함께

작업을 마치면 다음 형식으로만 보고한다. 넣은 건수만 세지 않는다.

    대상 N건 · 적재 n건 · 제외 m건
    제외 사유: [코드] 건수 ...
    보류: 회수실패 x건 / 계통상충 y건

## 6. 하지 않는 것

- 검증기를 우회하거나 규약 파일을 고쳐서 통과시키지 않는다
- 성능이나 편의를 이유로 계통 필터를 풀지 않는다
- 사람이 내린 계통 선택을 재검색 결과로 덮어쓰지 않는다

---
doc_id: J-0007            # 층 접두 + 일련번호
title: 을축일주
layer: 정리                # 원본 | 정리 | 종합 | 질의
gyetong: A                # 단일값. 30_종합/대비/ 에서만 배열 허용
concept: 일주/을축         # 개념 1 : 문서 1
evidence:                 # 근거 slide ID. 비면 status는 확인못함
  - 6082
  - 6091
status: 확인함             # 확인함 | 확인못함 | 확인불가
verified_by: 하민
verified_at: 2026-08-06
version: v1.0
---

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""한바둑 LLM-Wiki 문서 서식 검증기 v1.0

규약(00_규약/문서서식.md)을 코드로 판정한다.
통과 · 차단 두 값만 두고, 차단에는 반드시 사유 코드를 남긴다.
"""
import sys, pathlib, re

REQUIRED = ["doc_id", "title", "layer", "gyetong", "concept",
            "evidence", "status", "verified_by", "verified_at", "version"]
LAYERS = {"원본", "정리", "종합", "질의"}
STATUS = {"확인함", "확인못함", "확인불가"}
MULTI_OK = "30_종합/대비"          # 계통 배열이 허용되는 유일한 경로
EXCLUDE = ("00_규약", "50_영수증", "90_보류")


def parse_front_matter(text):
    m = re.match(r"^---\n(.*?)\n---\n", text, re.S)
    if not m:
        return None
    fm, key = {}, None
    for line in m.group(1).split("\n"):
        if re.match(r"^\s*-\s+", line) and key:
            fm.setdefault(key, [])
            if not isinstance(fm[key], list):
                fm[key] = []
            fm[key].append(line.split("-", 1)[1].strip())
        elif ":" in line:
            key, val = line.split(":", 1)
            key, val = key.strip(), val.strip()
            fm[key] = val if val else []
    return fm


def check(path, root):
    """→ list of (code, message). 빈 리스트면 통과."""
    errs = []
    fm = parse_front_matter(path.read_text(encoding="utf-8"))
    if fm is None:
        return [("FM-000", "front-matter 없음")]

    for k in REQUIRED:
        if k not in fm:
            errs.append(("FM-001", f"필수 필드 누락: {k}"))
    if errs:
        return errs

    if fm["layer"] not in LAYERS:
        errs.append(("FM-002", f"layer 값 오류: {fm['layer']}"))
    if fm["status"] not in STATUS:
        errs.append(("FM-003", f"status 값 오류: {fm['status']}"))

    # 계통 단일값 규칙
    rel = str(path.relative_to(root))
    multi = isinstance(fm["gyetong"], list) or "," in str(fm["gyetong"])
    if multi and not rel.startswith(MULTI_OK):
        errs.append(("GT-001", f"계통 복수값은 {MULTI_OK}/ 에서만 허용"))
    if not multi and rel.startswith(MULTI_OK):
        errs.append(("GT-002", "대비 문서인데 계통이 하나뿐"))

    # 근거와 상태의 정합
    ev = fm["evidence"] if isinstance(fm["evidence"], list) else []
    if not ev and fm["status"] == "확인함":
        errs.append(("EV-001", "근거 없이 확인함으로 표시됨"))
    if ev and fm["status"] == "확인못함":
        errs.append(("EV-002", "근거가 있는데 확인못함으로 표시됨"))

    # 개념 1 : 문서 1
    if fm["layer"] == "정리" and "," in str(fm["concept"]):
        errs.append(("CP-001", "한 문서에 개념이 둘 이상"))
    return errs


def main(root):
    root = pathlib.Path(root)
    docs = sorted(p for p in root.rglob("*.md")
                  if not any(x in str(p) for x in EXCLUDE))
    passed, blocked = 0, []
    for p in docs:
        errs = check(p, root)
        if errs:
            blocked.append((p.relative_to(root), errs))
        else:
            passed += 1

    print(f"검사 {len(docs)}건 · 통과 {passed} · 차단 {len(blocked)}")
    for rel, errs in blocked:
        print(f"\n  ✗ {rel}")
        for code, msg in errs:
            print(f"      [{code}] {msg}")
    return 1 if blocked else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "."))

$ python3 00_규약/check_wiki.py .

검사 6건 · 통과 3 · 차단 3

  ✗ 20_정리/격국/정관격.md
      [GT-001] 계통 복수값은 30_종합/대비/ 에서만 허용

  ✗ 20_정리/일주/갑자일주.md
      [FM-001] 필수 필드 누락: concept
      [FM-001] 필수 필드 누락: evidence
      [FM-001] 필수 필드 누락: status
      [FM-001] 필수 필드 누락: verified_by
      [FM-001] 필수 필드 누락: verified_at
      [FM-001] 필수 필드 누락: version

  ✗ 20_정리/통변/육친론.md
      [EV-001] 근거 없이 확인함으로 표시됨

  ✗ 50_영수증/ingest/2026-08-06_샘플.md
      [FM-000] front-matter 없음

대상 20건 · 적재 17건 · 제외 3건
제외 사유: [EX-표지] 2 · [EX-중복] 1
보류: 회수실패 0건 / 계통상충 0건

| 계통 | 임시 표기 | 판별 신호 (작성 예정) |
| --- | --- | --- |
| 계통A | A | 고유 용어 목록 · source 범위 |