---
title: "Hansbridge AI Development & Git Migration Playbook — 바이브코딩에서 Git 기반 AI Agent 체계까지"
category: "playbook"
document_type: "playbook"
source_status: "generated"
knowledge_group: "01_rules"
priority: "High"
purpose: "비개발자+AI 기반 프로젝트가 초기 바이브코딩→Git→AI Agent 협업→자동배포→자체 KB 운영으로 발전한 표준 프로세스. FactoPin·Hansbridge·신규 프로젝트 재사용 족보."
read_when: ["프로젝트개요","운영규칙·프롬프트작성","문서이전·KnowledgeBase"]
updated: "2026-06-04"
authors: "Claude.ai(초기 히스토리 증언) + 달록본레포CC(Git 이후 운영기록·git 이력 기준)"
source_of_truth: "https://dallog-tools.hansbridge.co.kr/"
---

# Hansbridge AI Development & Git Migration Playbook
### 바이브코딩에서 Git 기반 AI Agent 개발 체계까지 — 달록(PaceLog) 레퍼런스 케이스

> **문서 성격** — 단순 회고록이 아니라, 타 프로젝트(FactoPin·Hansbridge·신규)를 담당할 Claude Code·Codex·기타 LLM Agent에게 그대로 이관할 **실제 운영 가이드(족보/reference case)** 다.
> **작성 기준** — 성공 결과만이 아니라 **시행착오와 해결 과정**까지 기록한다. 같은 문제를 반복하지 않게 하는 것이 목적이다.
> **자료 통합** — Claude.ai 초기 히스토리(구상~Git 이전) + 달록본레포CC 운영기록(Git 이후~현재)을 통합한다. **충돌 시 git 이력·달록본레포CC 기록을 우선**하되, Claude.ai의 초기 기여·설계·시행착오는 삭제·축소하지 않는다.
> **대상 프로젝트** — 달록(PaceLog) · 개인 러닝/체성분 트래커.

---

## 0. 한눈에 보기 (TL;DR)

달록은 **개발 경험이 없는 1인 창업자**가 Claude.ai에서 대화만으로 코드를 직접 생성하고, Cloudflare Pages에 zip을 손으로 올리는 방식으로 시작했다. 이 방식은 초기 진입장벽을 낮췄지만 곧 한계에 부딪혔고, **GitHub + Claude Code + Cloudflare Git 자동배포 기반의 멀티 에이전트 개발 체계**로 전환했다.

이 전환은 추측이 아니라 **git 이력에 그대로 남아 있다.**
- 2026-05-13 — `Initial commit` → `Add files via upload`(×3) → `v1.0.0` → `Update Layout.tsx`(웹UI 업로드/zip 시대)
- 2026-05-15 — `7e4b825 feat: 작업지시서 #02 인증 시스템 구축`(Conventional Commit·작업지시서 체계 시작 = **전환 분기점**)
- 2026-06-02 — PR #30~#32, 정식 도메인 `dallog.kr` 라이브, OAuth 3종, 누적 **194 커밋 / 27 PR 머지**

최종 운영 구조

```
사용자 (방향·결정·검증)
   ↓
GPT / Claude.ai (설계·검토·프롬프트 작성·맥락 추적)
   ↓
Claude Code / Codex (로컬 repo에서 코드 실행)
   ↓
Git (commit 단위 이력 관리 · branch+PR)
   ↓
Cloudflare Pages (commit/push → 자동 배포 1~2분)
   ↓
달록KB (https://dallog-tools.hansbridge.co.kr/ · Source of Truth 기록)
```

신규 프로젝트는 이 과정을 **재현할 필요 없이 §7부터 시작**하면 된다.

---

## 1. 초기 AI 바이브코딩 단계 — "비개발자 + Claude.ai 직접 개발"

### 1.1 출발점
- 사용자는 **개발자가 아닌 상태**에서 시작했다. Git·GitHub·터미널·빌드 도구 사전 지식이 거의 없었다.
- 개발 방식은 **Claude.ai 대화 기반**이었다. 원하는 기능을 자연어로 설명하면 Claude.ai가 코드를 직접 작성했다.

### 1.2 코드 생성 방식
- Claude.ai가 `create_file` / `bash_tool`로 컨테이너 안에서 직접 프로젝트를 구성했다.
- 스택은 처음부터 **React 18 + TypeScript + Vite 5 + Supabase**로 잡혔다.
- 컨테이너 안에서 `npx tsc --noEmit` 타입체크 + `npm install`로 검증한 뒤, **zip으로 패키지**(node_modules 제외)해서 사용자에게 전달했다. 예: `dallog-v0.1.0.zip`.

### 1.3 초기 배포 방식 — zip 수동 업로드
1. Claude.ai가 코드를 zip으로 패키지·다운로드 제공
2. 사용자가 압축 해제
3. **GitHub 웹 UI `Add file → Upload files`** 로 파일 업로드
4. Cloudflare Pages가 연결된 repo를 감지해 빌드·배포

> git 이력 증거 — 초기 커밋 `Add files via upload`(×3), `v1.0.0`, `v1.1.0`, `Update Layout.tsx`, `Update CoachNotes.tsx`가 이 "웹UI 업로드/zip 시대"의 흔적이다. 커밋 메시지가 일반적("Add files via upload")이라 **무엇이 왜 바뀌었는지 추적이 안 되는** 문제가 메시지에서부터 드러난다.

### 1.4 환경변수 초기 설정
- Supabase 연동 값을 Cloudflare Pages 대시보드 환경변수로 주입한다 — `VITE_SUPABASE_URL`, `VITE_SUPABASE_ANON_KEY`.
- 로컬은 `.env.local`에 동일 값을 넣고 `npm run dev`로 구동한다.

---

## 2. 초기 방식의 한계

zip/웹UI 업로드 방식은 시작엔 충분했지만, 프로젝트가 커지면서 한계가 명확해졌다.

| 한계 | 내용 |
|---|---|
| **버전 관리** | 어떤 파일이 어떤 버전인지 추적 불가. `v0.1.0` 같은 zip 이름에만 의존. |
| **롤백** | 부분 롤백 불가. 잘못된 변경을 되돌리려면 이전 zip을 통째로 덮어써야 함. |
| **변경 추적** | "누가 언제 무엇을 왜 바꿨는지"가 남지 않음(commit 메시지 부재). |
| **웹UI 업로드 함정** | `Upload files`는 폴더 구조 유지가 까다로움. 실제로 신규 `src/pages/Settings.tsx`가 누락되는 사고 발생 → 결국 파일별 연필 편집/`Create new file`로 우회. |
| **컨텍스트 소실** | Claude.ai 대화 컨텍스트가 길어지면 한계 도달. 방을 옮길 때마다 코드·구조·결정사항이 소실. |
| **1인 zip 관리 한계** | 기능이 늘면서(대시보드/기록/히스토리/요약/코치노트/설정) 1인이 zip을 손으로 관리하기 어려워짐. |

> 이 한계들이 §3의 Git 전환을 **불가피하게** 만들었다.

---

## 3. Git 환경 도입 과정

### 3.1 전환을 결정하게 만든 동기 (사용자 본인 표현)
> "이제 달록을 통해서 github도 어느 정도 익숙해졌고, 디렉토리 잡아서 자동업로드도 편하고, 로그 확인도 편하고, 결론적으로 내 품(수고)이 줄으니까 이게 더 낫다."

| 동기 | 내용 |
|---|---|
| 코드 이력 관리 | commit 단위 변경 추적, 부분 롤백 가능 |
| 자동 배포 | 디렉토리 연결 후 commit/push만으로 Cloudflare 자동 빌드 → 수동 업로드 수고 제거 |
| 배포 로그 | Cloudflare가 빌드/배포 로그 실시간 제공 |
| 사고 감소 | zip 수동 업로드 대비 누락·구조 깨짐 방지 |
| AI Agent 협업 | Claude Code가 로컬 repo에서 직접 코드를 읽고 수정 → 대화 기반 코드 생성의 한계 돌파 |

> ⚠️ **의사결정 맥락** — FactoPin(팩토핀) 초기에도 "GitHub을 쓸 것인가 vs zip 직접 업로드"라는 동일 이슈가 있었고, 당시엔 zip이 낫다고 판단했다. 달록을 통해 GitHub 방식을 직접 경험한 뒤 "이게 더 낫다"는 재평가가 나왔다. 즉 **전환의 정당성은 추측이 아니라 실제 이전 경험에서 확인**되었다.

### 3.2 Git 도입 절차 (실제 수행)
- GitHub **Private repo** `github.com/ccy-hansbridge/dallog`를 기준 저장소로 사용.
- 초기 웹UI 업로드 → **로컬 작업 디렉토리 + GitHub Desktop 푸시** 방식으로 전환.
- 전환 분기점(git): **`7e4b825`(2026-05-15) feat: 작업지시서 #02 인증 시스템 구축** — 이때부터 Conventional Commit(`feat:`/`fix:`) + 작업지시서 기반 체계가 시작됨.

### 3.3 로컬 workspace 구성
- 로컬 경로 — **`D:\dallog\dallog_git`**
- ⚠️ **핵심 교훈 — OneDrive 경로 금지** — GitHub Desktop이 OneDrive로 라우팅되는 경로에서는 **변경 감지에 실패**하는 문제가 있었다. 그래서 OneDrive를 거치지 않는 로컬 경로(`D:\dallog\...`)를 표준으로 삼았다. (이 위치는 이후 모든 한스브릿지 프로젝트 공통 원칙이 됨.)

---

## 4. AI Agent 개발 환경 구축

### 4.1 핵심 구조 — "Claude Code workspace = git repo 일치"
가장 중요한 구조적 결정은 **Claude Code가 도는 폴더와 git repo를 같은 위치로 일치**시킨 것이다. 별도 작업 폴더에서 만든 파일을 git repo로 복사하는 단계를 없앴다.

```
D:\dallog\dallog_git\          ← Claude Code workspace = git repo (일치)
├── src\                       ← 소스 (App.tsx, components, hooks, lib, pages, studio-overrides.css)
├── public\
├── workers\                   ← Cloudflare Workers
│   ├── brief-proxy\           ← AI 브리프 프록시 (CORS·API키 보호)
│   └── auth-proxy\            ← 카카오 OAuth 자체처리 (/kakao/exchange)
├── docs\                      ← 개발 산출물·KB 이전본(pacelog-archive)
├── .claude\CLAUDE.md          ← 프로젝트 전용 규칙
└── CLAUDE.md / MEMORY.md      ← 본레포 운영 규칙(달록KB SoT 각인)
```

작업 흐름이 한 곳으로 단순화됨

```
Claude Code (dallog_git에서 직접) → 파일 수정·저장 → GitHub Desktop commit·push → Cloudflare Pages 자동 배포(1~2분)
```

### 4.2 CLAUDE.md 2단(+1) 구조
- **글로벌 헤더** — `C:\Users\ccy48\.claude\CLAUDE.md` (한스브릿지 공통 행동지침: 코딩 전 생각·단순함·외과적 변경·목표중심·한국어 규칙)
- **프로젝트 전용** — `D:\dallog\dallog_git\.claude\CLAUDE.md` (달록 스택·디렉토리·규칙)
- **본레포 운영 규칙** — `D:\dallog\dallog_git\CLAUDE.md` / `MEMORY.md` (2026-06-04 추가: **달록KB = 유일 Source of Truth**, 노션 탈피)
> 💡 글로벌 헤더 복사 시 `dir $HOME\.claude`로 **용량(byte) 일치까지 검증**할 것. `.claude` 폴더만 생기고 파일 복사가 누락된 것처럼 보이는 상황이 있었다.

### 4.3 Agent 역할 분담
| Agent | 역할 |
|---|---|
| **GPT / Claude.ai** | 설계·조율, 프롬프트 작성, 검토, 맥락 추적 |
| **Claude Code** | 로컬 repo에서 실제 코드 실행·수정·테스트·산출물 생성 |
| **Codex** | 리뷰·보조 (Plus Plan 일일 토큰 한도 있어 대규모·복잡 작업 단독 투입엔 비추천. 버그 수정·단위 변경·소규모 독립 작업에 적합) |

### 4.4 멀티 에이전트 동시 운영 규칙 (실제 충돌 후 정착)
전환 후 여러 Claude Code 에이전트를 병렬로 돌리며 커밋 충돌을 겪었고, 그 결과 다음 규칙이 정착했다. (모든 Claude Code 프롬프트 맨 앞에 주의사항으로 붙임)
- **병렬 충돌 방지** — 같은 파일을 동시에 수정하는 조합 금지. 작업 시작 전 `git status` 확인, 충돌 시 즉시 중단·보고.
- **`git add` 개별 파일만** — `git add .` / `git add -A` **절대 금지**. 다른 에이전트의 미완성 변경이 섞여 들어가는 사고 방지.
- **원격 동기화는 `git fetch`로만**, `git pull` 임의 실행 금지.
- **데스크탑 우선 설계 → 모바일 반응형** 적용. 모바일 퍼스트 금지(데스크탑 변경이 모바일에 잘못 적용돼 768px 이하 롤백한 사고 있었음).

---

## 5. 배포 시스템 변화

| 구분 | 전환 전 | 전환 후 |
|---|---|---|
| 코드 생성 | Claude.ai 대화 → zip | Claude Code가 로컬 repo에서 직접 수정 |
| 전달 | zip 다운로드 | 로컬 파일 직접 저장 |
| 업로드 | GitHub 웹 UI 수동 | GitHub Desktop commit/push (branch+PR) |
| 배포 | repo 감지 후 빌드 | Cloudflare Pages 자동 빌드 (1~2분) |
| 이력 | zip 파일명 | git commit 이력(해시·메시지) + PR |

### 5.1 빌드/배포 설정
- Cloudflare Pages — Framework `Vite` / Build `npm run build` / Output `dist`.
- 환경변수(`VITE_SUPABASE_URL`, `VITE_SUPABASE_ANON_KEY` 등)는 **대시보드에서 주입**, 코드 하드코딩 금지.
- 백엔드 프록시는 Cloudflare **Workers**로 분리 — `brief-proxy`(AI 브리프, CORS·키 보호), `auth-proxy`(카카오 OAuth 자체처리 `/kakao/exchange`, KOE205 회피).
- 인증은 Supabase OAuth — **구글·네이버·카카오 3종**. 카카오는 자체처리 B안(auth-proxy 경유).

### 5.2 도메인 — 본레포CC 보정 사항 ⚠️
- Claude.ai 초기 히스토리는 배포 주소를 `https://dallog.pages.dev`로 기록했다. 이는 **초기/프리뷰 주소**다.
- **현재 운영(production) 기준은 `https://dallog.kr`** — 2026-06-02 정식 도메인 라이브(git: PR #30 oauth-dallog-kr-golive). OAuth 콘솔·Supabase에도 dallog.kr 등록.
- 즉 배포 SoT는 `dallog.kr`이며 `pages.dev`는 레거시 프리뷰로 본다.

---

## 6. 현재 한스브릿지 AI 개발 운영 구조

```
사용자 (방향·결정·검증)
   ↓
GPT / Claude.ai (설계·검토·프롬프트 작성·맥락 추적)
   ↓
Claude Code / Codex (로컬 repo 코드 실행)
   ↓
Git (commit 단위 이력 + branch/PR · 현재 194 커밋 / 27 PR)
   ↓
Cloudflare Pages (자동 배포) + Workers(brief/auth proxy)
   ↓
달록KB (https://dallog-tools.hansbridge.co.kr/ · Source of Truth)
```

### 6.1 기술 환경 (현재)
| 항목 | 값 |
|---|---|
| 로컬 경로 | `D:\dallog\dallog_git` |
| 스택 | React 18 + TypeScript + Vite 5 + Supabase(Auth/DB/RLS) + Cloudflare Pages/Workers |
| 도메인 | https://dallog.kr (production, 2026-06-02 라이브) |
| GitHub | github.com/ccy-hansbridge/dallog (Private) |
| 인증 | Supabase OAuth — 구글·네이버·카카오(자체처리) |
| AI 브리프 | OpenAI gpt-5.4-mini 라인(E-7 전환) + Claude fallback, CF Worker brief-proxy 경유 |
| KB(SoT) | https://dallog-tools.hansbridge.co.kr/ (Notion 탈피) |

### 6.2 특징적 운영 자산
- **/studio** — 마스터 전용 UI 토큰 편집 툴(색·폰트·버튼·자간·반응형, `uiCatalog.ts`). 앱 토큰화의 수혜자이자 동인.
- **인라인→CSS/토큰 마이그레이션** — 약 1,584곳 인라인 style → 78로. 달록 전용이 아니라 **FactoPin·Hansbridge에 재사용 가능한 디자인시스템 전환 이력**.
- **SAFEZONE** — 멀티유저 데이터 분리·RLS 보안 기반.
- **달록KB 전환** — Notion → `docs/pacelog-archive`(142개 무손실 추출, manifest+context-router) → dallog-tools.hansbridge.co.kr 단일 SoT.

### 6.3 Source of Truth 원칙 (2026-06-04 확정)
- **달록KB = 유일 원본.** Notion은 과거 시스템(초기 이전 소스)일 뿐 더 이상 기준 원본·AI 컨텍스트 복구 기준이 아니다.
- `docs/pacelog-archive`는 "이삿짐"(초기 이전 데이터)이며 최종 운영 원본이 아니다.
- 작업보고·작업일지·핸드오프·기능/UI설명서·MCP보고서·운영지침·의사결정 기록 → **모두 달록KB 기준**으로 관리·업로드.

---

## 7. 신규 프로젝트 표준 시작 절차 (FactoPin / Hansbridge / 신규)

달록은 "zip 수동 → Git 전환"을 **사후에** 겪었다. 신규 프로젝트는 **처음부터 Git 기반으로 시작**하면 된다.

### Step 1 — Git repo 먼저 생성
- 프로젝트 시작 시점에 GitHub Private repo부터 만든다. (zip 단계를 아예 건너뛴다)

### Step 2 — 로컬 workspace 구성
- **OneDrive를 거치지 않는** 로컬 경로에 작업 폴더를 만든다 (예: `D:\<project>\<project>_git`). GitHub Desktop 연결.

### Step 3 — Claude Code workspace = git repo 일치
- VSCode로 그 폴더를 열고, Claude Code를 그 위치에서 구동한다(파일 복사 단계 제거).
- `.claude\CLAUDE.md`에 프로젝트 전용 규칙, `$HOME\.claude\CLAUDE.md`에 글로벌 헤더, repo 루트 `CLAUDE.md`/`MEMORY.md`에 SoT·운영 규칙.

### Step 4 — AI Agent 연결 & 분업
- Claude.ai(설계) / Claude Code(실행) / Codex(리뷰·보조) 역할 분담.
- 멀티 에이전트 규칙(§4.4) 그대로 적용 — `git status` 선확인, `git add` 개별 파일만, 동일 파일 동시작업 금지, 데스크탑 우선.

### Step 5 — 배포 자동화
- Cloudflare Pages에 repo 연결 + 환경변수는 **대시보드에서 주입**(하드코딩 금지). 백엔드 키는 Workers로 분리.
- Framework `Vite` / Build `npm run build` / Output `dist`. 이후 commit/push → 자동 배포.

### Step 6 — KB(Source of Truth) 시스템 구축
- 프로젝트 시작과 동시에 **단일 KB**를 SoT로 세운다(달록처럼 Notion을 거치지 말고 처음부터 단일 KB 권장). 핸드오프·작업보고·개발일지를 KB에 기록해 컨텍스트 복구가 가능하게 한다.

> ✅ **FactoPin 참고** — 팩토핀은 달록 전환 경험을 받아 "GitHub 전환 검토" 이슈가 이미 전달된 상태다. 본 문서 Step 1~6이 그 적용 가이드가 된다.

---

## 8. 시행착오 및 교훈 (가장 중요 — 신규 프로젝트의 족보)

> 성공한 결과만 적지 않는다. 달록이 실제로 막혔던 지점과 해결 방법을 남긴다.

### 8.1 GitHub 웹 UI 업로드 누락 사고
- **증상** — `Upload files`로 폴더째 올렸는데 신규 파일(`Settings.tsx`)이 반영 안 됨.
- **원인** — 웹 UI 업로드는 폴더 구조 유지가 까다로움.
- **해결** — 파일별 직접 편집/`Create new file`로 경로 직접 입력. → 궁극적으로 GitHub Desktop + 로컬 repo 방식으로 전환하는 계기.

### 8.2 OneDrive 경로에서 변경 미감지
- **증상** — GitHub Desktop이 변경을 감지하지 못함.
- **원인** — OneDrive 라우팅 경로.
- **해결/원칙** — 작업 디렉토리는 OneDrive를 거치지 않는 로컬 경로로 고정.

### 8.3 데스크탑 변경이 모바일에 오적용
- **증상** — 데스크탑 레이아웃 변경이 모바일에도 잘못 적용.
- **해결** — 768px 이하 롤백. "데스크탑 우선 설계 후 모바일 반응형" 원칙 명문화.

### 8.4 `.env.local` 누락으로 흰 화면
- **증상** — 로컬 `npm run dev`에서 흰 화면.
- **원인** — `.env.local`에 Supabase URL/anon key 미설정.
- **해결** — `VITE_SUPABASE_URL`/`VITE_SUPABASE_ANON_KEY` 입력 후 dev 재시작.

### 8.5 멀티 에이전트 병렬 충돌
- **증상** — 동일/인접 파일을 여러 에이전트가 건드려 충돌·오반영.
- **해결** — 프롬프트 맨 앞 git 충돌 경고 헤더, `git status` 선확인, `git add` 개별 파일, 동일 파일 동시작업 금지.

### 8.6 가짜 벡터(SVG) 자산
- **증상** — repo의 SVG가 실제로는 PNG를 감싼 1.3MB 가짜 벡터였음.
- **해결** — 진짜 벡터(`fill="currentColor"`, 1~6KB)로 재제작·교체, 구버전은 `_outline_bak` 백업.
- **교훈** — 자산 파일은 "확장자"가 아니라 "실제 내용"을 확인할 것.

### 8.7 컨텍스트 소실 & "핵심 요약을 누가 정의하나"
- **증상** — 방을 옮길 때마다 이전 맥락 소실. 핸드오프 요약 시 "무엇이 핵심인지"를 AI가 임의 판단하면 누락 발생.
- **결론** — AI가 임의로 "핵심"을 정의해 축약하지 않는다. 누락 없는 기록을 위해 **새 컨텍스트가 이전 대화를 다시 검색·맥락 파악**하는 것을 원칙으로 삼음. 이 깨달음이 **단일 KB(SoT)로 컨텍스트 복구를 보장**하려는 동기로 직결됨 → 달록KB 체계의 출발점.

### 8.8 Notion 의존 회귀 사고 (KB 이전 중)
- **증상** — KB 뷰어에서 문서 클릭/내부 링크가 Notion 앱으로 이동. "노션 탈피"가 목적인데 오히려 노션 의존.
- **결론** — notion_url을 운영 데이터에서 배제(제거/격리), MD 내부 링크도 내부 경로로 변환. **달록KB가 유일 SoT**임을 모든 흐름에서 관철.

---

## 부록 A — 달록 개발 단계 요약 (git 이력 기준)

| 단계 | 시기 | 핵심 | git 흔적 |
|---|---|---|---|
| v0.x | 2026-05-13 | Claude.ai 직접 생성·zip·웹UI 업로드 | `Initial commit`, `Add files via upload`×3, `v1.0.0`, `v1.1.0` |
| v2.0 | 2026-05-14 | 섹션1 개편(기록탭/히스토리/Summary/Claude API) | `달록 v2.0 섹션1 …` 서술형 커밋 |
| **전환 분기점** | **2026-05-15** | 작업지시서 + Conventional Commit + 인증 시스템 | **`7e4b825 feat: 작업지시서 #02`** |
| 본격 운영 | 2026-05-16 ~ 06-02 | branch+PR, 멀티 에이전트, /studio, 디자인시스템, SAFEZONE, OCR/엑셀, OAuth 3종 | PR #1~#32, 194 커밋 |
| KB 전환 | 2026-05~06 | Notion → pacelog-archive → 달록KB 단일 SoT | `docs/pacelog-archive` |

## 부록 B — 자료 우선순위 및 본레포CC 보정 사항

- **Claude.ai 문서** = 초기 개발 히스토리 증언 자료(구상·바이브코딩·Git 이전). 적극 참고하되 현재 운영 기준은 아님.
- **현재 운영 기준** = 달록KB + 달록본레포CC 기록 + git 이력.
- **충돌 시 본레포CC·git 우선.** 단 Claude.ai의 초기 기여·시행착오는 보존(역할 변경과 기록 정확성 기준은 분리).
- 본 문서에서 본레포CC가 보정한 항목
  1. 배포 SoT — `dallog.pages.dev`(프리뷰) → **`dallog.kr`(production, 2026-06-02)**
  2. 프로젝트 git 시작일 — **2026-05-13**(최초 커밋 기준)
  3. 현재 SoT — Notion → **달록KB(dallog-tools.hansbridge.co.kr)** 단일 체계
  4. 백엔드 — CF **Workers 2종**(brief-proxy/auth-proxy) 분리, OAuth 3종 명시

---

## 9. 기준 문서로서의 효력 (Scope & Update Policy)

이 문서는 달록 프로젝트를 통해 정립된 Git 기반 AI Agent 개발 운영체계의 기준 문서다. 본 문서에 정리된 내용은 작성 시점까지의 달록 개발 운영체계를 기준으로 한다. 이후 달록의 일반 기능 개발 영역에서 이 문서가 별도로 업데이트되지 않는 한, 본 문서의 작업 시스템 기준은 변하지 않는 것으로 본다.

다만 FactoPin, Hansbridge, 기타 향후 프로젝트에서는 각 프로젝트 진행 중 사용자 직접 지시, 또는 담당 AI Agent/Claude Code/Codex/LLM의 필요성 제안에 따라 운영 시스템이 개선·확장될 수 있다. 그 경우 해당 프로젝트에서 공식 반영된 새로운 시스템 업데이트가 이후 기준이 될 수 있다.

---

## 10. 달록KB v1 과도기 운영 참고사항

달록 프로젝트는 Hansbridge AI Hub 탄생 **이전의 최초 레퍼런스 프로젝트**이다. 따라서 일부 운영 규칙은 달록 전용 보완책이다.

대표 — **문서명 timestamp 강제 규칙**(`YYYYMMDD_HHMMSS_문서명.md`).

발생 이유 — 서비스 레포(`dallog_git`)와 KB 관리 레포(`dallog-tools`)가 분리되어 있고, 작업 기록 생성 시점과 KB 반영 시점이 달라질 수 있기 때문이다(일정 기간 쌓인 뒤 일괄 등록 가능). 따라서 파일명 timestamp로 원래 발생 순서를 복원할 수 있어야 한다.

향후 Hansbridge AI Hub 적용 프로젝트에서는 더 발전된 기록 관리 체계를 적용할 수 있으며, 그 시점의 최신 Hub 운영 규칙을 우선한다. **즉 달록 방식은 복사 대상이 아니라 발전 기준점이다.**

**기록 파이프라인** — Hub 구축 이전 달록 프로젝트에서는 **본레포 `docs/kb-pending` → 툴레포 KB 편입** 방식으로 운영한다. 본레포CC가 만든 KB 반영 예정 문서는 `D:\dallog\dallog_git\docs\kb-pending\` 에 `YYYYMMDD_HHMMSS_문서명.md`로 저장하고, 툴레포CC가 문서명 timestamp 순서로 달록KB에 편입한다.

---

## 다음 문서 (FactoPin·차기 프로젝트 담당자 필독)

신규 프로젝트를 시작하거나 다른 프로젝트로 이전할 담당자(AI Agent 포함)는 본 문서 다음으로 아래를 읽는다.

- **[Hansbridge AI Hub 전환 설계서](#/doc/playbook-02)** — 달록KB v1 이후 중앙 AI 운영 허브로의 발전 방향. 달록은 복사 대상이 아니라 발전 기준점.
- 참고: [달록KB 관리설명서](#/doc/manual-01) — 레포 역할분담·LLM 컨텍스트 복구·문서 갱신 절차(사용자/운영자용).

> 권장 진입 흐름: **START_HERE → AI 협업 청사진(본 문서) → Hansbridge AI Hub 전환 설계서**

---

*본 문서는 달록의 실제 개발 대화·git 이력·운영기록을 기반으로 작성되었으며, 타 프로젝트의 Git 기반 AI Agent 개발 환경 구축 시 그대로 참조·이관하기 위한 실제 가이드다. 달록KB 마스터 문서 영역 등록 완료(2026-06-04).*