# 위키 생성 프롬프트 전략

## 역할

HaBraid는 기억 저장소를 사람이 읽고 AI가 다시 활용할 수 있는 위키 표현층으로 바꾸는 엔진이다.

- 목표는 단순 요약이 아니라 **정리 + 재구성**
- raw memory를 topic / entity / decision / timeline 같은 의미 단위로 재편성
- 결과물은 human-readable 이면서 agent-readable 해야 함

## LLM 실행 방식

### 기본: host-following
- `llm.mode = host`
- 가능하면 host(Hermes/OpenClaw/Codex CLI)가 실제 생성 수행
- HaBraid는 prompt 생성, batching, 파싱, 저장을 담당

### fallback / standalone
- host route unavailable이면 `llm.fallback` 사용
- standalone mode에서는 habraid가 직접 backend 호출
- 지원 대상: `zai`, `openai`, `ollama`

```typescript
interface LLMClient {
  generate(systemPrompt: string, userPrompt: string, timeoutMs?: number): Promise<{
    text: string;
    metadata: {
      route: "host" | "fallback" | "standalone";
      provider?: string;
      model?: string;
      fallbackUsed: boolean;
    };
  }>;
}
```

## 프롬프트 구조

### 시스템 프롬프트 (항상 포함)

```text
당신은 HaBraid wiki 관리 에이전트입니다.

## 역할
memory backend에 저장된 인프라, 프로젝트, 의사결정 지식을 Obsidian 위키 페이지로 정리합니다.

## 철학
- "요약"이 아니라 "정리"가 목표입니다.
- 원본을 다시 열지 않아도 될 정도로 충분히 구조화하세요.
- 기술 결정: 왜 A를 선택했는지, 트레이드오프를 구체적으로
- 에러/해결: 에러 메시지, 원인, 해결 방법을 그대로
- 코드/설정: 스니펫, 명령어, 경로를 원문 그대로 포함
- 한국어 본문, 코드/경로/명령어는 영어 원문 유지

## 출력 형식
- YAML frontmatter 포함 마크다운
- Obsidian 백링크 [[]] 사용
- 마크다운 헤딩으로 구조화
```

### 증분 업데이트 프롬프트

```text
## 새로 수집된 데이터
- item 수: N개
- Wings: {wing 목록}
- Rooms: {room 목록}

## 새 item 내용
{각 item의 wing/room/content}

## 기존 위키 페이지 목록
{wiki/ 디렉토리의 파일 목록}

## 작업
1. 새 내용을 분석하세요
2. 기존 wiki/ 페이지와 관련 있으면 해당 페이지에 내용 추가
3. 새로운 주제면 적절한 카테고리에 새 페이지 생성
4. SCHEMA/frontmatter 규칙을 따르세요
5. sources에 source drawer/item ID를 반드시 포함하세요
```

## 증분 업데이트 로직

1. DB에서 `wiki_generated_at IS NULL` 아이템 조회
2. raw/ 또는 DB content를 prompt 컨텍스트로 구성
3. 기존 wiki/ 페이지 목록 포함
4. LLM 응답 파싱 → 파일로 저장
5. 생성된 아이템은 DB에 generated 상태 기록
6. `.sync-state.json`에 마지막 LLM route/provider/model 기록
7. overview/index/log 갱신

## 배치 전략

- room 단위 그룹핑
- room 내부는 subgroup/batch 분할
- 큰 초기 rebuild에서는 첫 room이 매우 커질 수 있으므로 `maxRooms=1`이 항상 가벼운 smoke test는 아님
- 진행 상황은 `/tmp/habraid-wiki-gen.log`에 기록

## 토큰/시간 관리

- 긴 content는 prompt용으로 잘라서 사용
- 초기 full generation은 시간이 오래 걸릴 수 있음
- host-following 구조에서도 batching은 유지한다
- route metadata를 남겨 실제 어떤 경로(host/fallback/standalone)로 생성됐는지 추적한다