지식센터 / 레퍼런스

📝 KHub 직접 등록 표준 가이드 (Notion 우회)

# 📝 KHub 직접 등록 표준 가이드

> 최종 업데이트: 2026-02-17 KST

> KHub 검색: khub_search("KHub 직접 등록", project_code:"COMMON")

---

왜 직접 등록인가

현재 문서 분포: manual 41개 vs notion 37개 — 이미 직접 등록이 과반

---

등록 방법

방법 A: Supabase MCP (supabase-growthplatform) — 짧은 문서

execute_sql로 직접 INSERT:

INSERT INTO khub_documents (
  title, content, project_code, source_type, environment,
  is_active, category_id, metadata
) VALUES (
  '{제목}',
  '{마크다운 내용}',
  '{프로젝트코드}',
  'manual',
  'qa',
  true,
  '{카테고리ID}',
  '{"tags": ["태그1", "태그2"], "version": "1.0"}'::jsonb
) RETURNING id, title;

방법 B: HTTP API (bash_tool) — 긴 문서용 (권장)

파일로 만든 후 curl POST:

# AP-08: API 키 조회
SB_KEY=$(Supabase gp_admin_secrets에서 조회)
SB_URL="https://ihzttwgqahhzlrqozleh.supabase.co"

# 파일 내용을 JSON 이스케이프
CONTENT=$(cat 파일.md | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))")

# AP-01: 3헤더 필수
curl -s -X POST "${SB_URL}/rest/v1/khub_documents" \
  -H "apikey: ${SB_KEY}" \
  -H "Authorization: Bearer ${SB_KEY}" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d "{
    \"title\": \"문서 제목\",
    \"content\": ${CONTENT},
    \"project_code\": \"COMMON\",
    \"source_type\": \"manual\",
    \"environment\": \"qa\",
    \"is_active\": true,
    \"category_id\": \"753edf2d-171d-4edb-87a0-20fe9e875712\",
    \"metadata\": {\"tags\": [\"태그\"]}
  }"

---

필수 필드

선택 필드

카테고리 ID

---

DevLog 등록 템플릿

Snapshot (Tier 1) — 덮어쓰기

기존 Snapshot이 있으면 UPDATE, 없으면 INSERT:

-- 기존 Snapshot 찾기
SELECT id FROM khub_documents
WHERE title LIKE '%DevLog Snapshot%'
  AND project_code = '{코드}'
  AND is_active = true;

-- 있으면 UPDATE
UPDATE khub_documents
SET content = '{새 내용}', updated_at = now()
WHERE id = '{기존ID}';

-- 없으면 INSERT
INSERT INTO khub_documents (
  title, content, project_code, source_type, environment,
  is_active, category_id, metadata
) VALUES (
  '📸 {프로젝트} DevLog Snapshot',
  '{내용 — 3000자 이하}',
  '{코드}', 'manual', 'qa', true,
  '753edf2d-171d-4edb-87a0-20fe9e875712',
  '{"tags": ["DevLog", "Snapshot"], "tier": "1"}'::jsonb
) RETURNING id, title;

Task DevLog (Tier 2) — 신규 생성

INSERT INTO khub_documents (
  title, content, project_code, source_type, environment,
  is_active, category_id, metadata
) VALUES (
  '📋 {작업명} — DevLog',
  '{마크다운 내용}',
  '{코드}', 'manual', 'qa', true,
  '753edf2d-171d-4edb-87a0-20fe9e875712',
  '{"tags": ["DevLog", "Task"], "tier": "2"}'::jsonb
) RETURNING id, title;

---

수정/삭제

수정 (manual 문서만)

UPDATE khub_documents
SET content = '{새 내용}', title = '{새 제목}', updated_at = now()
WHERE id = '{문서ID}' AND source_type = 'manual';

비활성화 (삭제 대신)

UPDATE khub_documents
SET is_active = false, updated_at = now()
WHERE id = '{문서ID}';

---

충돌 방지 규칙

절대 규칙: source_type=notion 문서를 Supabase에서 직접 UPDATE하지 말 것

---

검색 확인

등록 후 바로 검색 가능 (키워드 검색 즉시, 시맨틱 검색 ~30분 후):

khub_search("{키워드}", project_code:"{코드}")
khub_get_document("{반환된 ID}")

---

각 프로젝트 Instructions에 복붙할 섹션

## KHub/DevLog 등록 규칙

등록: Supabase 직접 INSERT (Notion 경유 금지 — 부하로 방 죽음 발생)
- DB: supabase-growthplatform (ihzttwgqahhzlrqozleh)
- source_type: 'manual' 필수
- environment: 'qa' 필수
- 가이드: khub_search("KHub 직접 등록", project_code:"COMMON")

DevLog:
- Snapshot(Tier1): 기존 문서 UPDATE (같은 제목 유지, 3000자 이하)
- Task(Tier2): 신규 INSERT (📋 {작업명} — DevLog)
- ⛔ Notion 경유 금지 — 직접 INSERT만 사용

관련 문서

이 문서를 참조하는 문서 (역링크)

• 없음

다른 표현: Markdown · JSON · 최종 갱신 2026-08-24