CLAUDE.md

CLAUDE.md — Interactive Novel Engine Backend

프로젝트 개요

원작 고전 소설(카르밀라)을 온톨로지 기반으로 형식화하여 "책을 읽는 느낌 + 핵심 씬에서의 상호작용"을 제공하는 인터랙티브 노벨 엔진. Google ADK 기반 파이프라인이 유저 입력을 받아 가드 → 캐릭터 응답 → 디렉터(수렴 판단) 순으로 처리하고, 원작·온톨로지 검색은 GraphRAG 계층이 담당.

최상위 가치: 원작 충실. 원작의 톤과 세계관이 깨지는 순간 실패다. LLM의 자유도는 기능이 아니라 리스크로 취급한다.

아키텍처 3층 구조

[밑단]  온톨로지/상태 설계 문서 → YAML v1.0 (대표님 산출물) → 엔진이 파싱
[중간]  GraphRAG: 온톨로지 YAML을 Neo4j에 적재 + 원문 발췌 벡터 검색
[앞단]  ADK 에이전트 파이프라인 (guard → character → director)

• 온톨로지의 내용은 대표님 소유, YAML **스키마(형식)**는 개발팀 소유. 스키마 변경은 양쪽 합의로만.
• 그래프는 원문에서 LLM이 자동 추출하지 않는다. 큐레이션된 YAML을 적재하는 것이 유일한 경로.

작업 원칙

1. 논의 → 설계 → 계획 → 구현 → 리뷰

코드를 먼저 작성하지 않는다. 반드시 이 순서를 따른다:

1. 논의: 요구사항을 정확히 이해하고 질문한다
2. 설계: 2-3개 접근법을 비교하고 추천한다
3. 계획: 구체적인 파일 목록과 변경 사항을 문서화한다
4. 구현: 계획대로만 구현한다. 범위를 벗어나지 않는다
5. 리뷰: 구현 결과를 spec과 대조하여 검증한다
6. 갱신: 커밋 및 코드 구현이 완료되면 해당 부분을 꼼꼼하게 단계별로 메모리에 반영 및 갱신하세요

이 사이클을 충분히 반복한다. 급하다고 건너뛰지 않는다.

2. 기존 코드의 일관성을 지킨다

• 새 코드는 기존 패턴을 따른다. 더 나은 패턴이 있어도 혼자 바꾸지 않는다
• 폴더 구조, 네이밍, import 스타일을 기존 코드에서 먼저 확인한다
• "개선"이라는 이름으로 기존 컨벤션을 무시하지 않는다

3. Google ADK 공식 패턴을 따른다

• ADK가 제공하는 기능(LlmAgent, ParallelAgent, SequentialAgent, LoopAgent, AgentTool, FunctionTool)으로 해결한다
• Python으로 ADK를 우회하거나 대체하는 코드를 작성하지 않는다
• 프롬프트로 해결하려 하기 전에, 에이전트 구조(계층, 타입, 조합)로 해결할 수 있는지 먼저 검토한다
• 조금이라도 의심되면 바로 ADK 공식문서를 확인한다: https://google.github.io/adk-docs/

4. 확인 없이 추측하지 않는다

• 파일을 수정하기 전에 반드시 읽는다
• ADK API를 사용할 때 기억에 의존하지 않고 문서나 소스를 확인한다
• Docker 로그, grep 결과 등 실제 증거를 기반으로 판단한다
• 원작 원문·온톨로지 내용을 기억으로 인용하지 않는다. 반드시 content/ 또는 그래프에서 조회한다

5. 서사 진행은 코드가, 대사는 LLM이

• 챕터/씬 전환, 분기 조건, 수렴 판정의 최종 결정은 결정적 코드(상태머신 + director 출력의 구조화된 검증)가 내린다
• LLM은 "지금 이 씬 안에서 이 캐릭터로 응답"하는 좁은 역할만 맡는다
• LLM 출력만 믿고 state를 전이시키지 않는다. 전이 조건은 반드시 코드에서 재검증한다

---

핵심 도메인 규칙

원작 충실 (Canon Fidelity)

• 캐릭터가 원작에 없는 사실을 단정하는 응답은 결함이다. 프롬프트에 주입된 온톨로지·원문 발췌 범위 안에서만 말하게 한다
• 유저가 세계관을 벗어난 행동을 하면 director가 세계관 내 화법으로 되돌린다. 메타 발화("저는 AI라서...")는 절대 금지
• 문체는 content/style/ 문체연출 가이드가 기준. style_critic 루프가 검수한다

스포일러 스코프 (매우 중요)

• 모든 원문 청크, 그래프 노드/엣지, 온톨로지 항목에는 state_id(서사 진행 단위)가 붙는다
• 모든 검색은 state_id <= 현재 state 필터를 강제한다. 필터 없는 검색 코드는 리뷰에서 반려
• 지식 상태: "state N 시점에 이 캐릭터가 아는 것"은 온톨로지의 지식 상태 항목이 권위. 캐릭터 프롬프트에는 해당 시점 지식만 주입한다

수렴 (Convergence)

• 씬마다 YAML에 정의된 목표 비트(goal beats)와 수렴 조건(exit condition)이 있다
• director는 매 턴 "목표 비트 달성 여부 / 이탈 정도 / 수렴 시점 도달 여부"를 구조화 출력으로 판단한다
• 최대 턴 수를 초과하면 director가 강제 수렴 내레이션으로 씬을 닫는다 (무한 체류 방지)

---

에이전트 폴더 규칙

에이전트 = 폴더 + agent.py            ← 하위 에이전트가 있는 계층형
하위 에이전트 = sub_agents/ 폴더        ← 부모-자식 계층
같은 뎁스 병렬 에이전트 = agents/ 파일  ← 자체 하위 없는 단순 에이전트 (가드 등)
도구 = tools/ 안에 1파일 = 1함수
instruction 10줄 초과 = instructions/ 폴더로 분리
팩토리 함수 = 조립만 담당 (클래스 정의/DB 헬퍼 포함 금지)

sub_agents/ vs agents/ 구분

• sub_agents/X/agent.py 패턴은 X가 추가로 하위 계층을 가질 때 사용. 예: sub_agents/director/sub_agents/style_critic/...
• agents/X.py 패턴은 X가 자체 하위 없이 단일 BaseAgent/LlmAgent로 끝날 때 사용. 팩토리 함수(create_X())와 클래스를 같은 파일에 모아둠. 예: engine/agents/input_guard.py, spoiler_guard.py, scene_context_loader.py

팩토리 파일 책임 분리

factory.py는 조립만 담당. 에이전트 클래스 정의·DB 헬퍼 함수는 agents/*.py나 sub_agents/*/agent.py에 위치. 팩토리는 그것들을 import해서 SequentialAgent(sub_agents=[create_guard(scene_id), create_character(scene_id), ...]) 형태로 엮는 역할만.

엔진 구조

engine/
├── agent.py              ← 루트 에이전트 (턴 파이프라인)
├── app.py                ← ADK App + Runner + Plugin 등록
├── model.py              ← LLM 모델 설정 (env에서 읽음)
├── router.py             ← FastAPI 엔드포인트 (HTTP만 담당)
├── instructions/         ← instruction 텍스트 (캐릭터/디렉터/가드)
├── callbacks/            ← 에이전트별 콜백
├── plugins/              ← ADK Plugin (횡종단 관심사)
│   └── logging.py        ← 턴 로깅 (입력/컨텍스트/응답/가드발동/수렴) — 연구 데이터 겸용
├── services/             ← 비즈니스 로직
│   ├── story.py          ← 카드 진행 상태머신 (canon 읽기/next 전이/엔딩 판정)
│   ├── pocket.py         ← 개입 포켓: ADK 세션 관리 + run_turn() + 수렴 코드 재검증
│   ├── state.py          ← 숨은 상태 (신뢰축/쇠약도/앎) 커밋
│   └── retrieval.py      ← 검색 오케스트레이션 (스포일러 필터 강제 지점, GraphRAG는 2단계)
├── repositories/         ← 데이터 접근
│   ├── ontology.py       ← 온톨로지 조회 인터페이스 (구현: yaml_direct / neo4j)
│   ├── manuscript.py     ← 원문 청크 + 벡터 검색
│   └── playlog.py        ← 턴 로그 저장
├── tools/                ← 1파일 = 1도구함수
│   ├── retrieval/        ← query_ontology, search_excerpt
│   └── state/            ← set_flag, update_affinity, mark_beat
├── sub_agents/           ← 에이전트 트리
│   ├── character/        ← 캐릭터 응답 (인물 시트 + 씬 브리프 + 발췌 주입)
│   ├── director/         ← 비트 달성/이탈/수렴 판단 (구조화 출력)
│   └── style_critic/     ← LoopAgent (generator + critic) 문체 검수
├── schemas/              ← Pydantic: 콘텐츠 3레이어 스키마 + validate CLI
└── content/              ← (읽기 전용) 엔진의 유일한 서사 입력 — 원천은 비트카드 MD(대표님 소유)
    ├── beatcards/        ← 비트카드 YAML (scripts/beatcard_convert.py 산출물, E01~)
    ├── chapters/         ← 챕터 메타 (entry/exit beats, ending_rules, R카드 등록)
    ├── characters.yaml   ← 인물 정체성 시트 (ENOS, 지식경계, kb_query 훅)
    ├── style/            ← 문체연출 가이드
    └── narrative/        ← 서사/핸드오프 문서

ADK App + Plugin 규칙

• app.py에서 App 객체 + Runner를 정의한다
• 횡종단 관심사(로깅, 모니터링 등)는 Plugin으로 분리한다 (plugins/)
• Runner는 App 기반으로 초기화한다 (Runner(app=app, ...))
• agent를 Runner에 직접 전달하지 않는다 (레거시 패턴)
• 스캐폴드 파일(미구현 도구, 빈 콜백, 빈 instruction)은 삭제하지 않는다
  • Claude Code가 ADK 패턴을 벗어나지 않도록 하는 가드레일 역할
• 호출 흐름: Agent → Tool(FunctionTool) → Service → Repository → 데이터(YAML/Neo4j/DB)

---

콘텐츠 파이프라인 (A안 아키텍처 — 2026-07-03 확정)

콘텐츠 3레이어

레이어	파일	내용	대응 스키마
정체성 (불변)	content/characters.yaml	인물 시트(ENOS), player=laura, 지식경계, kb_query 훅	schemas/character.py
챕터 메타	content/chapters/*.yaml	entry/exit beats, beat_range, 엔딩 규칙, R카드 등록	schemas/chapter.py
내러티브	content/beatcards/E##/*.yaml	카드: narration 블록/choices/next/canon/복선 태그/연출	schemas/beatcard.py

• 콘텐츠 원천(권위)은 비트카드 MD(카르밀라/.../비트카드/, 대표님 소유). 변환 YAML은 파생물이며 scripts/beatcard_convert.py(개발팀 소유)로만 생성
• 콘텐츠 내용 수정은 개발팀이 하지 않는다. 스키마 위반 발견 시 검증 리포트로 대표님께 전달
• python -m engine.schemas.validate content/ 가 통과하지 않는 YAML은 적재하지 않는다
• MVP의 서사 진행 단위는 비트카드 순서: 스포일러 필터의 state_id는 beat_id ≤ 현재로 해석한다

숨은 상태 모델 (P0 4종 엔진 명세 준거)

• 신뢰축(의심↔신뢰 시소) · 쇠약도(단조 증가, 신뢰와 독립 — 핵심 아이러니) · 앎(유저, 도입 1회 확립 후 불변)
• 숫자·게이지·시스템 메시지를 유저에게 절대 노출하지 않는다. 상태는 내레이션 톤·카르밀라의 결·해금으로만 드러낸다
• 엔딩 판정은 챕터 메타의 ending_rules 조건식을 코드로 평가한다 (LLM 판정 금지)

GraphRAG 계층 (2단계 — MVP 제외)

• MVP는 pre_kb 상태: content/의 kb_query 훅(source: kb_query, status: pending)은 채우지 않고 그대로 둔다
• MVP 콘텐츠 로더는 repositories/content.py(YAML 메모리 로드). 이후 GraphRAG 도입 시 kb_query 훅을 채우는 구현으로 교체. 상위 계층은 구현을 몰라야 한다 (ablation 실험 요건)
• Neo4j 적재 시 LLM 자동 추출 KG 빌더(SimpleKGPipeline 류)는 사용 금지 — 큐레이션 콘텐츠와 충돌
• 독자 상호작용 데이터의 그래프화도 2단계. MVP에서는 playlog 스키마 설계까지만

---

ADK 핵심 규칙

Instruction

종류	용도	주의
instruction	동적. {var}로 state 변수 치환	{}는 state 변수로 파싱됨. 예시 텍스트에 {} 쓰지 말 것
global_instruction	전체 sub_agent에 전파	의도적으로 사용할 때만 채울 것
static_instruction	고정. 멀티모달 지원	캐릭터 시트처럼 씬 내 불변 컨텍스트에 검토

• 원작 발췌·온톨로지 컨텍스트를 instruction에 넣을 때 원문에 {, }가 포함될 수 있으므로 주입 전 이스케이프 처리를 거친다 (전처리 유틸 필수)

Callback (8종)

before_agent, after_agent, before_model, after_model, before_tool, after_tool, on_model_error, on_tool_error

• before_model: 스포일러 필터 최종 방어선 (주입 컨텍스트의 state_id 검사)
• after_model: 턴 로깅 훅

에이전트 타입

타입	용도	예시
LlmAgent	LLM이 판단/도구 호출	character, director
ParallelAgent	하위 에이전트 병렬 실행	(필요 시) 다중 검색
SequentialAgent	하위 에이전트 순차 실행	turn_pipeline (guard → character → director)
LoopAgent	하위 에이전트 반복 (escalate로 탈출)	style_critic (generator + critic), 씬 내 턴 루프
BaseAgent	LLM 없이 코드로 직접 처리	input_guard(규칙 기반 1차), scene_context_loader, 상태 전이 검증
CustomAgent	BaseAgent 확장. 조건 분기, 동적 에이전트 선택	씬 타입별 파이프라인 선택

절대 하지 말 것

• output_schema와 tools 동시 사용 — Gemini 3.0만 지원, 다른 모델에서는 안 됨. 필요하면 sub-agent로 출력 포맷팅을 분리할 것
• mode="ANY" 사용 (무한 루프 발생)
• instruction 안에 예시 텍스트로 {한국어} 사용 (state 변수로 파싱됨 → 에러)
• Python 코드로 ADK 워크플로우를 대체 (keyword matching, hardcoded fallback 등)
• LlmAgent의 output_key로 구조화된 값을 기대 — LLM 텍스트만 저장됨. director의 수렴 판정처럼 구조화 값이 필요하면 FunctionTool이 tool_context.state에 직접 쓰거나 BaseAgent로 구현
• 검색/컨텍스트 주입 경로에서 state_id 필터를 생략 (스포일러 사고)
• LLM 판단만으로 씬/챕터 전이 (반드시 services/scene.py의 코드 검증을 거칠 것)
• 원작 원문을 프롬프트에 기억으로 재현 (반드시 repository 조회)

Escalate scope 격리 (매우 중요)

ADK LoopAgent는 sub_agent의 escalate=True 이벤트를 상위로 yield한다. 즉 중첩 LoopAgent가 있으면 바깥 루프까지 함께 탈출한다(전 프로젝트 실측 확인). 이로 인해:

• SequentialAgent는 escalate를 인식하지 않음. escalate가 필요한 자리에 놓으려면 해당 범위만 LoopAgent(max_iterations=1)로 감쌀 것
• 내부 LoopAgent의 성공-escalate가 바깥을 오염시키면 안 되는 경우엔 반드시 바깥을 SequentialAgent로 두고, escalate를 소화할 scope만 LoopAgent로
• 씬 턴 파이프라인 설계 시 이 규칙을 적용한 기준 구조:

  scene_session (SequentialAgent)
  ├── scene_context_loader                  ← BaseAgent, YAML/그래프에서 씬 브리프 로드
  ├── turn_loop (LoopAgent max=씬별 max_turns) ← director의 수렴-escalate가 여기서 그침
  │   ├── input_guard
  │   ├── character
  │   └── director                          ← 수렴 판정 시 escalate
  └── scene_closer (LoopAgent max=1)        ← 강제 수렴 내레이션 + 상태 전이 커밋
  

권위 소스 원칙

"한 정보의 진실은 한 곳에만 있어야 한다."

• 서사 내용(인물/관계/사건/지식상태) 권위: content/yaml/ (적재된 Neo4j는 그 사본). 코드에 서사 내용 하드코딩 금지
• 씬 진행 상태 권위: session.state (씬 내) → 씬 종료 시 scene.py가 DB에 커밋 (영속). 두 곳을 동시에 갱신하는 코드 금지
• 현재 유저의 서사 위치 권위: DB play_session.current_state_id. 검색 필터는 이 값으로만
• 문체 기준 권위: content/style/. 프롬프트마다 문체 지시를 즉흥 작성하지 않는다
• 수렴 판정 권위: director의 구조화 출력 + scene.py의 코드 검증. LLM 텍스트 파싱으로 판정 금지

---

LLM 모델

# engine/model.py
from google.adk.models.lite_llm import LiteLlm
_MODEL_ID = os.environ.get("LLM_MODEL", "openai/gpt-5.4-nano")
LLM_MODEL = LiteLlm(model=_MODEL_ID)

• 로컬 테스트: 저비용 모델로 파이프라인 검증
• 캐릭터/문체 품질이 중요한 character, style_critic은 상위 모델을 별도 env로 분리 가능하게 (CHARACTER_MODEL)
• 모델 교체가 잦으므로 프롬프트에 특정 모델 의존 문법을 넣지 않는다

---

테스트 & 검증

# 단위 테스트
python3 -m pytest tests/ -v

# 콘텐츠 스키마 검증
python3 -m engine.schemas.validate content/

# 스포일러 필터 회귀 테스트 (state N에서 N+1 정보 누출 여부)
python3 -m pytest tests/test_spoiler_scope.py -v

# 평가 하네스 (LLM judge: 원작 충실도 / 문체 / 수렴 성공률)
python3 -m eval.run --scene <scene_id> --n 10

# Docker 빌드 확인
docker compose up -d --build backend
docker compose logs --tail=20 backend

• 프롬프트 변경은 평가 하네스 점수와 함께 PR에 첨부한다 (감이 아니라 숫자로)
• 턴 로그는 삭제하지 않는다 (연구 데이터)

---

커밋 규칙

• main에 직접 푸시 금지. 작업은 무조건 feature 브랜치에서 하고 PR로 올린다
• 파일 수정 전 반드시 Read로 현재 내용 확인
• 구조 변경 시 "복사 → 전환 → 삭제" 순서 (기존 기능 유지)
• Docker 빌드로 검증 후 커밋
• 비트카드 MD 원본과 content/ 하위 콘텐츠 내용은 개발 커밋에서 수정하지 않는다 (콘텐츠 변경은 별도 PR + 대표님 승인. 변환 스크립트 재실행 산출물 갱신은 예외)

---

참고 링크

• ADK 공식문서: https://google.github.io/adk-docs/
• ADK GitHub: https://github.com/google/adk-python
• Neo4j GraphRAG Python: https://github.com/neo4j/neo4j-graphrag-python
• LiteLLM 문서: https://docs.litellm.ai/docs/providers