위키 사용 안내

휴넥시아 사내 지식 위키 운용 가이드. 단일 진실 공간을 유지하는 규칙을 담는다.

구조

knowledge/<category>/<slug>.md. 카테고리: brand · company · offering · marketing · cases · process · org · _meta.

새 문서를 만들 때 — 템플릿에서 시작한다

knowledge/_meta/_template-wiki.md를 knowledge/<category>/<slug>.md로 복사해 쓴다(케이스는 cases/_template.md· cases/_template-product-story.md). 빈 파일에서 프론트매터를 손으로 쓰지 않는다. 지켜야 하는 것 3가지: ⓐ 프론트매터 필드 구성(아래 스키마 절 그대로) ⓑ 저장 위치·파일명(영문 kebab slug) ⓒ 본문 골격(아래 3규칙). {{ }} 자리표시자는 전부 치환한다 — 남아 있으면 미완성이다. 설계 의도 = operations/doc-standard.md.

ⓒ 본문 골격 — 절 이름은 강제하지 않는다(공통 절 0개). 26건 전수에서 모든 문서가 공유하는 h2가 하나도 없었다. 이름을 억지로 맞추면 빈 절로 규칙을 통과시키게 되므로, 어휘가 아니라 구조 3가지만 잰다. 주제에 맞는 절 이름은 자유다.

규칙	지켜야 하는 것
ⓐ h1 유일	문서당 h1은 1개. 나머지 단계는 전부 h2 이하
ⓑ h1 직후가 비어 있지 않다	h1 바로 아래에 리드 문단 또는 status 배너(> 인용)가 온다. 배너를 h1 위(프론트매터와 h1 사이)에 두지 않는다 — 위키 사이트가 h1을 제목으로 렌더하므로 배너가 제목보다 먼저 나온다
ⓒ 레벨 점프 없음	헤딩 단계를 건너뛰지 않는다(h2 다음에 h4 금지). 내려갈 때는 제한 없음

기계 검사 = npm run docs:check R18(현재 심각도 info. warn/fail 승격은 대표 승인 사항). 코드펜스 안의 #는 세지 않는다. 관련 문서는 본문 절이 아니라 프론트매터 related가 정본이라 템플릿에 ## 관련 문서 절이 없다. 결정 경위(면제 3건·만료 2026-10-31 포함) = operations/reports/2026-07-23-위키-본문골격-표준.md.

문서 스키마 (YAML frontmatter, 필수)

title(한국어) · slug(영어, 전역 고유) · category · tags[](27) · owner · status(active|draft|stub|deprecated, 완성도 축) · artifact(real|sample, 산출물 신분 축 — 판정 기준 knowledge/org/governance.md:89 "판정 기준: 내용의 출처가 실제 대상(…)이면 실물, 지어낸 예시·검증용 픽스처면 샘플. 불명확하면 샘플(안전측)") · summary(12문장, 검색 스니펫) · updated(YYYY-MM-DD) · source(내부 기획|외부:URL|commit:sha|대표 결정|추정(미검증)). 선택: related[], subcategory.

3축은 역할이 다르다 — status=얼마나 완성됐나 · artifact=내용의 출처가 실제인가 지어낸 것인가 · source=어디서 왔나. 병존이 정상이다(예: status: draft + artifact: real = 내용은 실제 케이스이나 아직 초안). artifact: real은 상한이지 보증이 아니다 — 문서 전체의 출처를 말할 뿐, 본문 개별 수치의 인용 가능성을 보증하지 않는다. 문장 단위 신분 표기(인용 화이트리스트·[측정 대기] 등)를 대체하지 않는다.

slug 규칙

<category>-<filename-stem>, 소문자. 예: brand/identity-plan.md → slug: brand-identity-plan. 전역 고유. npm run wiki:check가 일치를 검증.

네이밍 규칙

• 디렉터리/파일: 영어 slug 단수명사. 본문: 한국어. (한글 NFD 정규화로 인한 glob/ripgrep 불안정 회피.)
• 숫자 접두어 금지. 순서는 INDEX.md(자동 생성)가 제어.
• _* 접두 파일(예 cases/_template.md)과 INDEX.md는 색인에서 제외(헬퍼/생성물).

빌드·검증

• npm run wiki:index → knowledge/INDEX.md(사람용 목차) + knowledge/.index.json(기계용 캐시, 스킬·웹이 공유). 커밋 대상.
• npm run wiki:check → 스키마 게이트(typecheck 대응). 필수필드·slug 규칙·category enum·owner 점검.

정보 승격 (계층)

.remember/(휘발 세션) → .claude/org/reviews/<name>.md(에이전트별 영속) → knowledge/(검증된 팀 팩트). 승격 조건(하나 이상): ① 2회 이상 재현 ② "팀 전체가 알아야 할 팩트" ③ 세션 메모 1일+ 생존·가치 확인.

회귀 테스트 시나리오 (스킬/스키마 변경 시 재실행)

1. 태그 매칭: "브랜드 슬로건이 뭐야?" → brand/identity-plan.md 1위 → "사람의 가능성을 AI와 연결하다" 인용.
2. 카테고리+다중문서: "Labs 개발 체인?" → org/ 2건 → "principal-architect → implementation-lead → code-reviewer".
3. 근거부재 정직응답: "AI 코딩 교육 가격표 줘" → offering/pricing.md(stub) → "정해진 가격표 없음(자리만). 담당 확인 권장."
   • 각주(2026-07-22): offering/pricing.md·services.md는 웹 비공개(audience: external × 미완성 status → hunexia.com/wiki 미노출)이나 .index.json에는 그대로 남아 이 시나리오는 종전대로 성립한다(재실행 확인: 스코어 11.0으로 1위, 차순 3.0). 규칙 scripts/wiki-publish.mjs.

두 뷰

• Q&A: 스킬 /wiki(에이전트/대표, Claude Code 세션).
• 브라우징·검색: 정적 사이트 web/(Vercel). 같은 knowledge/·.index.json 소비.