brain-build

회사 공유폴더에는 워드·엑셀·PPT·PDF·txt 가 폴더마다 흩어져 있다. “최종”·”진짜최종”·”개정안” 같은 파일명은 어느 게 진짜 최신인지 알 수 없고, 계약 단가와 실제 발주 단가가 달라도 아무도 못 잡는다. brain-build 는 이 무더기를 근거 추적 가능한 업무DB(뇌)로 만든다 — 원본을 전수 읽어 주제별 위키로 정리하고, 문서 규약을 역공학하고, 끝에 독립 검수로 문서 사이 모순까지 잡는다.

itda-research 비정형 문서 vertical 의 빌드 담당. (SPEC-BRAIN-VERTICAL-001, #1122 — IGM 업무DB 실습키트 3차 리허설 실측 설계.)

Claude 오케스트레이션 지시서#

[HARD] 원본 불가침. 소스 폴더의 원본 파일을 절대 수정·이동·삭제·이름변경 하지 않는다. 읽기 전용으로만 접근한다. 산출물은 원본과 분리된 새 업무DB 폴더다. (SPEC INV-1) [HARD] 전수성. 원본을 하나도 건너뛰지 않는다. 읽을 수 없거나 정상 문서가 아닌 파일(손상·잠금 임시파일 ~$*·빈 문서)도 문제파일.md에 사유와 함께 기록해 커버한다. (REQ-022) [HARD] 근거 강제. 위키 본문의 모든 수치·금액·날짜·결정 뒤에 근거 원본 경로를 괄호로 인라인 표기한다. 근거 없는 값을 지어내지 않는다. (REQ-020) [HARD] 모순 보존. 서로 다른 문서가 같은 대상에 다른 값을 담으면 임의로 하나를 고르지 않고 양쪽 값·근거를 남긴다. 판정은 검수(brain-auditor)에 맡긴다. (REQ-021) [HARD] 빌드 끝에 brain-auditor 를 1회 자동 호출해 검수 4각도를 실행한다(관문7). 검수는 빌드 기억과 격리된 컨텍스트에서 원본을 다시 열어 수행한다.

입력#

• 소스 폴더 경로 (필수, 1개 한정 — v1 단일 소스) — 원본 문서 무더기가 있는 폴더. 하위 폴더 재귀 포함. 폴더 2개 이상을 요청받으면 명시 거부하고 폴더별로 뇌를 분리 빌드할 것을 제안한다 — 신선도 기준선(manifest)·근거 상대경로가 단일 루트 전제라, 다중 소스를 그대로 받으면 기준선이 한쪽 폴더만 대표하거나 상대경로가 충돌해 신선도 레이어가 조용히 틀린 답을 낸다(SPEC-BRAIN-VERTICAL-001 v1 범위).
• 뇌 이름 (선택) — 미지정 시 소스 폴더명 또는 사용자 확인으로 정한다.
• 업무DB 출력 경로 (선택) — 미지정 시 소스 폴더 옆에 <뇌 이름>_업무DB/ 로 만든다(원본 트리 밖 — 원본 불가침).

관문0 — 스킬 디렉토리(SKILL_DIR) 확정#

스킬 자산(템플릿·헬퍼 스크립트·에이전트 지시서)은 cwd 에 의존하지 않도록 절대경로로 읽는다. 실행 절 첫머리에서 SKILL_DIR 을 한 번 확정하고, 이후 모든 경로를 "$SKILL_DIR" 기준으로 쓴다:

# Claude Code(플러그인 설치) = $CLAUDE_PLUGIN_ROOT / Cowork = 세션 마운트 탐색
SKILL_DIR="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/brain-build}"
[ -n "$SKILL_DIR" ] || SKILL_DIR=$(find /sessions/*/mnt/.remote-plugins -type d -path '*/skills/brain-build' 2>/dev/null | head -1)
# 둘 다 아니면(저장소 체크아웃 등) 이 SKILL.md 가 있는 디렉토리 절대경로를 그대로 사용

$env:SKILL_DIR = "$env:CLAUDE_PLUGIN_ROOT\skills\brain-build"  # 미설정이면 SKILL.md 위치 절대경로 사용

관문1 — 전수 스캔 · 인벤토리#

소스 폴더를 재귀 스캔해 전체 파일 인벤토리를 만든다(전수성 기준선).

# macOS/Linux
find "<소스폴더>" -type f | sort        # 숨김/임시 포함, .DS_Store 는 인벤토리에만
# Windows
# Get-ChildItem -Recurse -File "<소스폴더>" | Select FullName

• 각 파일: 상대경로 · 확장자 · 크기 · 수정시각(mtime) 을 기록한다. 수정시각은 검수리포트 커버리지 표(관측 필드, REQ-032)와 신선도 점검(brain-audit)의 기준선이므로 반드시 캡처한다.
• ~$*(Office 잠금 임시파일)·0~수백 byte 손상 의심 파일은 표시해 둔다(관문3 문제파일.md 후보).

관문2 — 원본 판독 (읽기 전용, 유형별)#

각 원본을 유형에 맞게 읽는다. 에이전트가 문서를 판독한다(길 X — Python 이 문서를 직접 파싱하지 않는다). 관문1에서 표시한 문제 후보(~$* 잠금·0byte 등)는 유형별 판독을 시도하기 전에 실패(빈 파일·본체 아님)만 확정하고 관문3 문제파일.md 로 보낸다 — 문서 스킬 호출은 정상 후보에만 쓴다:

• .docx → document-skills:docx 스킬 또는 로컬 파서로 본문·표 추출.
• .xlsx/.csv → document-skills:xlsx. 정형 수치가 핵심이면 itda-data:data-verify(수치 검수)를 하위 활용 가능.
• .pptx → document-skills:pptx (슬라이드 텍스트 + 표지/슬라이드 내부 작성일 — 최신성 판별의 정본).
• .pdf → document-skills:pdf (텍스트 레이어 추출). 스캔 PDF(텍스트 레이어 부재)·이미지 위주 문서는 “내용 검색 불가”로 분류해 관문3 문제파일.md에 기록한다(OCR 필요 여부 관찰 병기, #1223) — 판독·적재 여부와 별개로, 이후 텍스트 검색이 이 파일 내용을 보지 못한다는 표시다.
• .txt → Read.
• 손상/잠금/빈 파일 → 판독 실패를 기록(관문3 문제파일.md).

판독 시 각 문서에서 주제·핵심 수치·날짜·결정·대상(거래처·품목 등)을 뽑고, 근거 경로(소스폴더 기준 상대경로)를 항상 함께 유지한다. 최신성은 파일명이 아니라 문서 내부 날짜로 판단한다.

관문3 — 주제별 위키 작성 (Layer 2)#

주제별로 .md 페이지를 만든다(실제 도메인에 맞게 — 거래처·계약·규정·매출·재고·인사·회의·제안 등). 각 페이지:

• 상단 머리말: 출처:(근거가 된 원본 경로 목록) · 최종갱신:.
• 본문: 모든 수치·금액·날짜·결정 뒤 괄호 인라인 근거. 예: 19,800원 (계약/대영인쇄_연간공급계약_2026.docx).
• 관련 페이지 [[페이지명]] 링크.
• 모순은 봉합하지 않고 양쪽 값·근거 병존.

페이지 실물 예시(형식 기준 — 머리말 + 인라인 근거 + 모순 병존):

출처: 계약/대영인쇄_연간공급계약_2026.docx, 발주/2026-03_발주서.xlsx
최종갱신: 2026-07-14

# 거래처 — 대영인쇄

- 품목: A4 복사용지, 박스당 2,500매 (계약/대영인쇄_연간공급계약_2026.docx)
- 매입 단가 — **모순 병존**: 계약 19,800원 (계약/대영인쇄_연간공급계약_2026.docx) vs
  발주 실적 21,000원 (발주/2026-03_발주서.xlsx) → 임의 판정하지 않음, 검수 대조 대상.

관련: [[사무용품-단가]]

이어서 카탈로그를 만든다:

• INDEX.md — 페이지 카탈로그(페이지·주제·주요 근거 원본) + 적재이력 절(언제 무엇이 들어왔나 — REQ-031, brain-ingest 증분의 데이터 소스) + 원본→페이지 커버리지 요약 + 알려진 핵심 모순 요약.
• 문제파일.md — 읽기 불가(손상·잠금)·내용 검색 불가(스캔 PDF·이미지 등 텍스트 추출 불가 — 판독은 됐어도 텍스트 검색의 사각, #1223)·주의(사본 접두·버전 파일명·무제 파일) 파일을 사유·조치와 함께 기록. 적재 집계(원본 총 N / 정상 적재 M / 읽기 불가 K / 내용 검색 불가 S).

관문4 — 규약 역공학 (규약 레이어)#

원본의 폴더 배치·파일명·문서 양식을 관찰해 규약을 역공학한다(REQ-010):

• 규약/폴더-지도.md — “어떤 문서가 어느 폴더에” 배치 체계. 명문 규정 존재 여부부터 확인.
• 규약/명명-규칙.md — 파일명 패턴 + 관찰된 위반 사례(무제·사본 접두·버전 지옥·”개정안” 오도·연도 누락·임시/손상 파일).
• 규약/양식/{유형}.md — 반복 유형(회의록·견적서·품의서 등)의 레이아웃(모범 원본 지정).

각 규약 항목에 **근거·표본 수·상태(추정/확정)**를 붙인다. 우선순위: 명문 규정 > 관찰된 다수 패턴 > 단일 사례 추정.

[HARD] 명문 규정과 실제 관찰이 불일치하면(예: 온보딩 가이드 “부서별” vs 실제 폴더 “유형별”) 명문을 기계적으로 확정하지 말고 불일치를 보존·명시하고 사용자 확인을 권고한다. (REQ-011)

관문5 — Layer 3 스키마 (CLAUDE.md) + 뇌 메타 자기서술#

"$SKILL_DIR/../../references/CLAUDE-template.md"(정본 — 플러그인 루트의 references/, 스킬 디렉토리 내부가 아님)를 업무DB 폴더의 CLAUDE.md로 심는다. {{...}} 플레이스홀더를 실제 값으로 치환:

• 머리말(frontmatter) 뇌 메타 (REQ-030 자기서술): brain(뇌 이름) · sources(소스 폴더 — 절대경로로 항목 1개, v1 단일 소스. brain-audit 가 이 값만으로 소스 폴더를 찾으므로 상대경로를 쓰면 실행 위치에 따라 해석이 갈린다) · last_updated · source_files(원본 파일 수). 파일시스템 스캔만으로 뇌를 발견·식별할 수 있게 하는 필드 — 임의로 비우지 않는다.
• 본문의 {{소스 폴더}}·{{뇌 이름}}도 치환. 주석 블록은 생성물에서 제거.

이 CLAUDE.md가 질답 규율의 담당자다(스킬이 아니라 DB 스키마가 질답을 담당 — Cowork 이 폴더를 열면 자동 적용, 스킬팩 없는 동료에게 폴더만 줘도 규율을 따름). 템플릿의 「신규 열람자 온보딩(인수인계) 규칙」도 함께 심긴다 — 이 뇌를 처음 받는 사람(신입·후임)이 폴더를 열면 근거 기반 브리핑·이해 확인을 받을 수 있다(사람↔뇌 이해 격차 해소, 상태는 뇌에 비저장).

관문6 — 신선도 기준선(manifest) 저장#

[HARD] 빌드 시점 정수 mtime 기준선을 저장해야 이후 brain-audit 신선도 점검이 “무엇이 바뀌었나”를 판정할 수 있다. 기준선이 없으면 신선도는 판정 불가(unknown)가 된다. 검수(관문7)보다 먼저 저장한다 — 검수관이 참조하는 기계 기준선이 검수 시점에 존재해야 하고, 커버리지 표와 manifest 의 스냅샷 시점도 일치한다.

위키·카탈로그가 확정되면 freshness.py scan 으로 소스 폴더 스냅샷을 떠 <업무DB>/.brain-manifest.json 에 저장한다(절대경로 실행). scan 이 실패해도 깨진/빈 manifest 가 남지 않도록 임시 파일에 쓴 뒤 성공 시에만 이동한다:

# macOS/Linux
python3 "$SKILL_DIR/../brain-audit/scripts/freshness.py" scan "<소스폴더>" \
  > "<업무DB>/.brain-manifest.json.tmp" && mv "<업무DB>/.brain-manifest.json.tmp" "<업무DB>/.brain-manifest.json"
# Windows (py -3 "$env:SKILL_DIR\..\brain-audit\scripts\freshness.py" scan ... — 동일하게 .tmp 후 move)

이 manifest 가 신선도 기준선의 정본이다(정수 epoch mtime — 타임존 무관). 검수리포트.md 커버리지 표의 수정시각 열은 사람 가독용 관측 필드(REQ-032)이고, 기계 대조는 manifest 로 한다. brain-audit 은 이 기준선을 갱신하지 않으며(현재값으로 덮으면 미적재 변경이 사라짐), 갱신은 brain-ingest 가 적재 성공 시에만 한다.

관문7 — 독립 검수 자동 호출 (brain-auditor)#

[HARD] 빌드 산출을 믿지 말고 검수한다. 빌드 기억과 격리된 컨텍스트에서 원본을 다시 열어야 자기검증 편향이 차단된다.

Agent 도구로 brain-auditor 서브에이전트를 1회 디스패치한다. 프롬프트에 넘길 것:

• 업무DB 폴더 경로 + 소스 폴더 경로.
• 관문1 인벤토리(파일 목록 + 수정시각) — 커버리지 표의 관측 필드(REQ-032) 기준선. 기계 기준선 manifest 는 관문6에서 이미 저장돼 있다.
• 검수 4각도 지시(전수성·수치 재대조·근거 추적·교차 모순)와 산출 파일(검수리포트.md).

brain-auditor 가 검수리포트.md를 쓰면, 발견된 핵심 모순 요약을 INDEX.md의 “알려진 핵심 모순”에 반영한다. brain-auditor 의 최종 텍스트는 AUDIT_SCHEMA JSON(verdict·findings·recomputed·unverifiable, #1621)이다 — 검수 통과 여부는 리포트 문장에서 추론하지 말고 verdict 필드로 읽는다(critical 1건 = FAIL, unverifiable 비어 있지 않으면 PASS 아님).

2차 경로 (에이전트 타입 부재 시) — 환경에 itda-research:brain-auditor 에이전트 타입이 없으면(스킬팩 미설치·소스 저장소 등), general-purpose 서브에이전트에 "$SKILL_DIR/../../agents/brain-auditor.md" 지시서를 먼저 읽고 그대로 따르라고 프롬프트로 명시해 디스패치한다. 새 컨텍스트의 서브에이전트가 지시서를 따르므로 격리 검수가 동등하게 성립한다(빌드 기억 미공유) — 이 경로는 배너 대상이 아니다.

[HARD] fail-visible fallback. 서브에이전트 디스패치 자체가 불가한 환경(Agent 도구 부재 등)이면 격리 독립 검수는 성립하지 않는다(자기검증 편향 미차단 — SPEC REQ-002 위반). 이때는 검수를 “통과”로 제시하지 말고, 검수리포트.md 최상단에 ⚠️ 격리 검수 미수행 — 자기검증 편향 미차단, 독립 재검수 필요 배너를 달고 종합 요약을 검증 불가로 표기한다. 본 컨텍스트에서 임시로 각도를 훑더라도 그 결과는 “미검증”이다.

완료 보고#

빌드 끝에 사용자에게 요약한다: 업무DB 경로 · 원본 N개(정상 M / 문제 K) · 위키 페이지 수 · 검수 결과(모순 건수·심각도) · 뇌 이름. 원본은 무수정임을 확인한다. 후임·신입에게 넘길 때는 폴더를 열고 “인수인계 브리핑 해줘”라고 하면 CLAUDE.md 온보딩 규칙이 근거 기반 안내·이해 확인을 제공한다고 덧붙인다.

원칙#

• 원본 불가침이 최우선. 검수·정정 권고도 원본 수정을 포함하지 않는다(정정은 원본 소유 부서 확인 후 사람이).
• “동작함” ≠ “정확함” — 위키가 그럴듯해 보여도 원본과 일치하는지는 검수(관문6)가 판정한다.
• 길 X thin skill — hyve 무의존. Cowork 에 스킬팩만 있으면 동작. 결정론 헬퍼(신선도)는 brain-audit 소관.