---
title: "달록KB 관리설명서"
category: "manual"
document_type: "manual"
source_status: "generated"
knowledge_group: "01_rules"
priority: "High"
purpose: "사용자가 달록KB를 직접 관리하고 LLM 컨텍스트복구·레포 역할분담(VSCode 레포 관리)·문서 갱신 절차를 이해하기 위한 운영 매뉴얼(관리설명서)."
read_when: ["운영규칙·프롬프트작성","컨텍스트복구","문서이전·KnowledgeBase"]
updated: "2026-06-04"
source_of_truth: "https://dallog-tools.hansbridge.co.kr/"
---

# 달록KB 관리설명서 (사용자/운영자용)

> 이 문서는 개발자용 코드 문서가 아니라 **사용자(사장님)가 직접 읽고 활용하는 운영 매뉴얼**이다.
> 달록KB가 무엇인지, VSCode에서 두 레포를 어떻게 관리하는지, 새 AI(GPT·Claude·Codex 등)에게 컨텍스트복구를 어떻게 시키는지, 작업보고·핸드오프를 어떻게 달록KB에 반영하는지를 다룬다.

---

## 1. 달록KB 기본 정의

- **달록KB = https://dallog-tools.hansbridge.co.kr/**
- 달록 프로젝트의 **유일한 문서·기록 Source of Truth(기준 원본)**다.
- **Notion은 더 이상 기준 원본이 아니다.** 과거 노션 데이터는 초기 이전 소스일 뿐이고, 지금의 기준 원본은 달록KB다.
- 달록KB는 **사람과 AI가 함께 읽는 운영 저장소**다. 사람은 뷰어(카드/리스트)로 보고, AI는 `ai-index`로 전체 문서를 읽는다.

핵심 한 줄: **"노션에서 확인" 개념은 폐기됐고, 앞으로는 "달록KB 기준 확인"으로 통일한다.**

---

## 2. 주요 URL 설명

| URL | 용도 |
|---|---|
| `/` (루트) | Claude Code **프롬프트 생성기** (작업·달록KB·검수·MCP QA·기능설계·배포점검 6탭) |
| `/knowledge/` | **달록KB 뷰어** — 카드/리스트 보기, 검색, 필터, 정렬, 사이드바(그룹·작업유형) |
| `/knowledge/ai-index` | **LLM 전용 정적 인덱스** — JavaScript 없이 전체 문서 링크를 한 페이지에 나열. 새 AI에게 가장 먼저 던지는 주소 |
| `/knowledge/pacelog-archive/manifest.json` | 전체 문서 색인(제목·분류·우선순위·경로). 카드·필터·검색·라우팅의 데이터 원본 |
| `/knowledge/pacelog-archive/context-router.json` | 작업유형별(smart_context) / 전체복구(full_restore_order) 읽기 순서 |
| 뷰어 상단 **START_HERE** | 프로젝트 개요·현재 상태·읽기 순서 (LEVEL 0 진입점) |
| 뷰어 상단 **navigation** | 상세 지도·카테고리 설명·상황별 가이드 |
| 뷰어 상단 **AI 협업 청사진** | Git 기반 AI Agent 개발 운영 족보(Playbook). 신규 프로젝트 시작·타 프로젝트 이전 기준 |

> 사람은 보통 `/knowledge/`로 들어가고, AI에게 시킬 때는 `/knowledge/ai-index`를 준다.

---

## 3. VSCode 레포 관리법

달록은 **두 개의 레포**로 나뉜다. 섞지 않는 것이 핵심이다.

| 레포 | 로컬 경로 | VSCode 창 |
|---|---|---|
| **달록 본레포** | `D:\dallog\dallog_git\` | 별도 창 1 |
| **달록툴레포** | `D:\hansbridge-tools\dallog-tools\` | 별도 창 2 |

원칙
- 두 레포는 **각각 별도 VSCode 창**으로 여는 것을 원칙으로 한다. 같은 창에 무분별하게 섞지 않는다.
- **달록 서비스 개발**(앱 기능·버그·UI)은 **본레포**에서 진행한다.
- **달록KB 관리·문서 등록·프롬프트 생성기 수정**은 **달록툴레포**에서 진행한다.
- 창을 헷갈리지 않도록, 작업 시작 전 VSCode 좌측 하단/제목표시줄의 폴더 경로를 한 번 확인하면 좋다.

---

## 4. 레포별 역할 분담

| 달록 본레포 (`D:\dallog\dallog_git`) | 달록툴레포 (`D:\hansbridge-tools\dallog-tools`) |
|---|---|
| 달록 서비스 개발 | 달록KB 관리 |
| 기능 구현 | Knowledge Base 문서 등록 |
| 버그 수정 | manifest/context-router/ai-index 재생성 |
| 앱 UI/UX | 프롬프트 생성기 관리 |
| Supabase/Workers/인증/서비스 코드 | 운영설명서(본 문서 포함) 관리 |
| 개발 결과 산출 | AI 컨텍스트 복구 체계 관리 |

> 쉽게 말해 **본레포 = 달록 앱을 만드는 곳**, **달록툴레포 = 그 기록과 운영 도구를 관리하는 곳**이다.

---

## 5. CC(Claude Code) 업무분장

| 달록본레포CC | 달록툴레포CC |
|---|---|
| 서비스 개발 담당 | KB 반영 담당 |
| 코드 수정 담당 | 문서 편입 담당 |
| 개발 결과 보고 | manifest/router/index 갱신 담당 |
| 필요 시 문서 초안 작성 | 달록KB 운영 시스템 유지관리 담당 |

**중요 — 교차 수정 금지**
- 달록본레포CC가 **dallog-tools 레포를 직접 수정하지 않도록** 한다.
- 달록툴레포CC가 **달록 서비스 코드를 직접 수정하지 않도록** 한다.
- 필요 시 **사용자 승인 후에만** 역할을 교차한다.

> 본레포CC가 작업보고 초안을 만들면, 사용자가 확인한 뒤 **달록툴레포CC가 달록KB에 등록**하는 흐름이 기본이다(§7 참조).

---

## 6. LLM 컨텍스트 복구 사용법

대상 — GPT · Claude.ai · Claude Code · Codex · Gemini · Grok · Manus 등 모든 LLM/AI Agent.

새 AI를 투입할 때 순서
1. **ai-index를 먼저 준다** — `https://dallog-tools.hansbridge.co.kr/knowledge/ai-index` (JS 없이 전체 문서 링크가 보이는 페이지)
2. **START_HERE 기준 복구** — 프로젝트 개요·현재 상태부터 파악
3. **context-router 기준 작업별 복구** — 하려는 작업유형(smart_context)에 맞는 문서만 순서대로
4. **manifest 기준 문서 탐색** — 제목·우선순위·경로로 필요한 md를 찾아 읽기

붙여넣어 쓰는 기본 프롬프트
```
달록KB 기준으로 프로젝트 컨텍스트를 복구해.
https://dallog-tools.hansbridge.co.kr/knowledge/ai-index
START_HERE → context-router → manifest → 필요한 md 문서 순서로 읽어.
Notion은 사용하지 말고 달록KB를 Source of Truth로 사용해.
```

> 프롬프트 생성기의 **달록KB 탭 → "🔄 새 AI 컨텍스트 복구 프롬프트"** 체크로도 같은 프롬프트를 즉시 생성·복사할 수 있다.

특정 질문 예시
- "달록KB의 최신 상태를 복구해. priority High + updated 최신 문서부터 읽어."
- "달록KB context-router의 smart_context['인증OAuth'] 순서대로 읽고 OAuth 현황을 정리해."

---

## 7. 기록 업데이트 흐름

작업 완료 후 달록KB에 반영하는 표준 흐름

```
달록 본레포 작업 (본레포CC)
        ↓
본레포 docs/kb-pending/ 에 YYYYMMDD_HHMMSS_문서명.md 저장 (편입 대기소)
        ↓
사용자 확인
        ↓
달록툴레포CC가 docs/kb-pending 문서를 달록KB에 편입 (pages/에 .md 추가)
        ↓
manifest / context-router / ai-index 재생성 (_gen 스크립트)
        ↓
commit · push → Cloudflare Pages 자동 배포
        ↓
웹에서 접근 확인 (/knowledge/ 에서 검색·열람)
```

> **달록 v1 과도기 규칙** — Hansbridge AI Hub 구축 이전 달록 프로젝트에서는 본레포 `docs/kb-pending` → 툴레포 KB 편입 방식으로 운영한다. 본레포CC가 만든 KB 반영 예정 문서는 반드시 `D:\dallog\dallog_git\docs\kb-pending\` 에 `YYYYMMDD_HHMMSS_문서명.md`로 저장하고, 툴레포CC는 업로드 시간이 아니라 **문서명 timestamp 기준**으로 순서를 보존해 편입한다. (생성기의 "KB 편입" 탭 프롬프트 사용.)
>
> 핵심 — 문서 .md만 손으로 쓰고, manifest/router/ai-index는 **스크립트로 재생성**한다. JSON을 손으로 고치지 않는다.

---

## 8. 문서 추가/수정 시 원칙

- **기존 문서 확인** — 같은 주제 문서가 이미 있는지 먼저 본다.
- **중복 생성 금지** — 있으면 새로 만들지 말고 최신화한다.
- **기존 문서 보존** — 통째로 바꿀 때는 이전 버전을 archive/version으로 남기고 변경 사유를 적는다.
- **manifest 직접 수정 금지** — `pacelog-archive/_gen_manifest.cjs` → `_gen_router.cjs`, `knowledge/_gen_ai_index.cjs`로 재생성한다.
- **schema 변경 시 명시적 bump** — 필드를 늘릴 때만 `_gen` 스크립트 수정 후 `schema_version`을 올린다. 현재는 **v4**.
- **Notion 링크 복구 금지** — 본문 내부 링크는 달록KB 내부 경로(`#/doc/<url_slug>`)로 둔다. 노션 주소로 되돌리지 않는다.
- **Source of Truth 원칙 유지** — 모든 흐름의 기준 원본은 달록KB다.
- **KB 문서 .md는 frontmatter가 맨 앞** — 파일 첫 줄을 `---`로 시작한다. 선행 HTML 주석을 넣으면 색인 등록에서 누락된다.

---

## 9. 자주 쓰는 프롬프트 예시

**새 GPT에게 달록KB 읽히기**
```
달록KB 기준으로 컨텍스트를 복구해.
https://dallog-tools.hansbridge.co.kr/knowledge/ai-index 를 먼저 읽고
START_HERE → context-router → manifest 순서로 파악해. Notion 금지.
```

**Claude.ai에게 특정 이슈 찾기**
```
달록KB(/knowledge/ai-index)에서 OAuth(인증) 관련 문서를 찾아
context-router의 smart_context['인증OAuth'] 순서대로 읽고 현재 상태·남은 작업을 정리해.
```

**달록본레포CC에게 작업 시키기** (본레포 VSCode 창에서)
```
달록 서비스 코드 작업이다. (작업 내용)
작업 후 작업보고 초안을 작성하되, dallog-tools 레포는 건드리지 마.
```

**달록툴레포CC에게 문서 등록 시키기** (달록툴레포 VSCode 창에서)
```
이 작업보고 초안을 달록KB에 등록해.
pages/에 md로 추가하고 manifest/context-router/ai-index를 재생성한 뒤 배포·접근 확인해.
JSON 직접 수정 금지, schema v4 유지.
```

**작업 종료 후 핸드오프 작성시키기**
```
이번 컨텍스트 핸드오프를 작성해. 현재 상태·완료/진행/남은 작업·변경 파일·결정·주의사항·다음 추천 작업 포함.
달록KB 기준으로 작성하고, 등록은 달록툴레포CC가 한다.
```

---

## 10. 향후 확장

- 달록KB의 운영 방식(단일 KB = Source of Truth)은 **FactoPin KB · Hansbridge KB · 신규 프로젝트 KB**로 그대로 복제할 수 있다.
- 달록KB를 **레퍼런스**로 삼아 같은 구조(pages/ + manifest + context-router + ai-index + 뷰어)를 복제하면 된다.
- 각 프로젝트의 Source of Truth는 **각 프로젝트 KB**가 담당한다. 한 KB가 모든 프로젝트를 떠안지 않는다.
- 구축 절차는 **AI 협업 청사진(Playbook)** 의 §7 "신규 프로젝트 표준 시작 절차"를 따른다.

---

*본 문서는 달록KB 운영을 위한 사용자/운영자 매뉴얼이다. 절차·역할이 바뀌면 본 문서를 최신화하고 manifest/context-router/ai-index를 재생성한다.*