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

> # 📝 KHub 직접 등록 표준 가이드 > 최종 업데이트: 2026-02-17 KST > KHub 검색: khub_search("KHub 직접 등록", project_code:"COMMON") --- ## 왜 직접 등록인가 | 경로 | 방식 | 소요 | 부하 | 추천 용도 | 

## 핵심 요약


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

> 최종 업데이트: 2026-02-17 KST
> KHub 검색: khub_search("KHub 직접 등록", project_code:"COMMON")

---

## 왜 직접 등록인가

| 경로 | 방식 | 소요 | 부하 | 추천 용도 |
|------|------|------|------|----------|
| Notion 경유 | Notion 작성 → KHUB-002 동기화 | 1시간 | 높음 (방 죽음 발생) | 외부 파트너 공유 문서만 |
| **직접 등록** | Supabase INSERT (HTTP or MCP) | **즉시** | 없음 | DevLog, 기술문서, 작업기록 |

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

---

## 등록 방법

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

execute_sql로 직접 INSERT:

```sql
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:

```bash
# 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\": [\"태그\"]}
  }"
```

---

## 필수 필드

| 필드 | 값 | 설명 |
|------|-----|------|
| title | 문서 제목 | 이모지 포함 가능 |
| content | 마크다운 본문 | 길이 제한 없음 |
| project_code | COMMON, GEOCARE, DATA_ENG, PREMIUM_GEO, GEO_COMMERCE | 필수 |
| source_type | **manual** | ⚠️ 반드시 manual (notion이면 동기화 충돌) |
| environment | **qa** | CHECK 제약조건: qa만 허용 |
| is_active | true | false면 검색 제외 |

## 선택 필드

| 필드 | 값 | 설명 |
|------|-----|------|
| category_id | UUID | 아래 카테고리 참조 |
| metadata | JSONB | tags, version, author 등 |
| source_url | URL | 원본 링크 (있으면) |

## 카테고리 ID

| 코드 | ID | 이름 |
|------|-----|------|
| GUIDE | 753edf2d-171d-4edb-87a0-20fe9e875712 | 가이드 문서 |
| TECH | 5f5efdea-2a5d-47bb-ae70-25ee0d3ff7de | 기술 문서 |
| PRODUCT | 8145df4d-65ce-4d8e-bdf3-c637a80d531b | 제품 전략 |
| FAQ | b717c327-451a-44e8-a2a1-cc9c1fea42b0 | FAQ |

---

## DevLog 등록 템플릿

### Snapshot (Tier 1) — 덮어쓰기

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

```sql
-- 기존 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) — 신규 생성

```sql
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 문서만)

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

### 비활성화 (삭제 대신)

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

---

## 충돌 방지 규칙

| source_type | Supabase 직접 수정 | Notion 수정 | 비고 |
|-------------|-------------------|-------------|------|
| manual | ✅ 자유 | ❌ 해당 없음 | 직접 등록 문서 |
| notion | ⛔ 금지 | ✅ | 다음 동기화 시 Notion 내용으로 원복됨 |

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

---

## 검색 확인

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

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

---

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

```markdown
## 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만 사용
```


## FAQ


---
출처: https://bizspring.ai/kb/ref/khub/common-khub-직접-등록-표준-가이드-notion-우회 · 최종 갱신 2026-08-24T11:53:44.908861+00:00