시스템 아키텍처

계층 구조 (기획서 9.1)

[도메인 계층]   의심도·신뢰도 산정, 발화 예산, 루프 상태 전이
                  → 순수 함수. LLM 없이 유닛테스트 가능

[애플리케이션]  Planner / Agent / Evaluator 오케스트레이션 + 도구 디스패치
                  → 포트 인터페이스에만 의존

[어댑터]        LLM 포트 · 도구 포트 · 도메인 포트 · 저장소 · 프론트엔드

어댑터 위 계층 전체 = BeyondBob Engine 도메인을 교체해도 이 경계 안쪽은 코드가 바뀌지 않습니다. 게임 · 감사 대응 · 커리어 대화가 이것을 공유합니다. 전이 시연(방어선 ⑤)의 근거가 여기입니다.

포트는 세 곳만 둔다

레이어를 늘리는 것 자체가 목적이 아닙니다. 나머지는 실용적으로 처리합니다.

포트	무엇을 갈아끼우나
① LLM 포트	모델 교체 (model-agnostic)
② 도구 포트	도구 등록·호출 규약
③ 도메인 포트	전이 시연 — 게임 ↔ 감사 대응 ↔ 커리어

도구 포트를 왜 따로 두나 — 전이 때문입니다

도구의 시그니처는 도메인과 무관하게 고정되고, 구현만 어댑터에서 갈립니다.

고정 시그니처	게임	전이 도메인
`ask_third_party`	NPC에게 묻는다	제3자에게 확인한다
`search_history`	루프 노트 검색	이전 대화 기록 조회

판정 구조 — 계산은 코드, 판단은 LLM

이 분리가 없으면 답할 수 없는 질문이 생긴다 “의심도 34는 어디서 나온 숫자인가”

	담당	예
수치 근거	코드 (순수 함수)	의심도 누적, 신뢰 임계, 발화 예산 감소·회복, 루프 잔류율
해석과 행동 결정	LLM	이 발화를 의심할 것인가, 계획을 바꿀 것인가

도메인 계층이 결정론적이므로 LLM 없이 유닛테스트가 가능합니다. 9.3의 근거입니다.

에이전트 하네스

모든 LLM 출력에 JSON 스키마를 강제하고 유효성 검증과 재시도를 겁니다. 자유 텍스트 응답을 허용하지 않아 게임 상태가 깨지지 않게 합니다.

도구 호출도 같은 하네스를 통과합니다 — 존재하지 않는 도구, 인자 스키마 위반, 예산 초과 호출은 실행 전에 거부되고 재시도됩니다.

아키텍처 테스트를 CI에 건다 (9.2)

import-linter로 의존성 방향 위반을 자동 검출
도메인 계층이 LLM 어댑터를 참조하면 CI 실패
배지를 README에 노출

의도: AI가 생성한 코드의 아키텍처 준수 여부를 눈이 아니라 기계로 검증한다. 세션마다 스타일이 흔들리는 아키텍처 드리프트를 방지하는 실질적 장치다.

도메인 규칙은 테스트 우선 (9.3)

의심도 누적, 신뢰 임계 판정, 발화 예산 감소·회복, 루프 잔류율은 전부 결정론적입니다.

명세와 검증은 사람이 소유하고, 구현은 AI에 위임한다.

이 분리 덕분에 “이 코드 AI가 짰죠?”에 대한 답이 명확해집니다 — 생성은 AI, 검증은 아키텍처 테스트와 도메인 테스트.

Fractal 11-File Set과의 관계

기존 백엔드 규약(테이블 1개 = 파일 11벌)은 저장소 어댑터와 도메인 엔티티 쪽에 그대로 적용합니다. 다만 이 프로젝트의 위임 단위는 테이블만이 아닙니다.

위임 단위	예
테이블 1개 = 11-File Set	`loop`, `utterance`, `note`, `judgement_log`
에이전트 역할 1개	Planner / Agent / Advisor / Re-plan / Evaluator
도구 1개	`ask_npc` / `search_notes`
도메인 어댑터 1개	게임 / 감사 대응 / 커리어

클라이언트

모바일 앱은 범위에서 빠졌습니다 기획서는 텍스트 전면 · 화면 5장 · 로그인/설치 없이 즉시 진입(12.2, 12.4)만 요구합니다. 네이티브 앱은 언급이 없고, 설치를 요구하는 순간 불특정 방문자의 진입률이 무너집니다.

프론트엔드는 어댑터 계층의 한 조각입니다. 화면 5장은 화면·기능 요구에 정리돼 있습니다.

전이는 언제 착수하나

코어가 돌기 시작하면 즉시 첫 어댑터를 시도한다 그때 막히면 도메인 개념이 코어로 새어 들어간 것이므로 고칠 시간이 있습니다. 3주차에 발견하면 고칠 수 없습니다. 14일 일정에서는 더 그렇습니다.

결정 로그

날짜	결정	이유
2026-09-03	포트 3개로 제한 (LLM·도구·도메인)	레이어 증식 자체가 목적이 되지 않게
2026-09-03	도구 시그니처를 도메인 중립 이름으로 고정	전이 때 어댑터만 갈아끼우기 위해
2026-09-03	import-linter CI 게이트 채택	아키텍처 드리프트를 사람 눈이 아니라 기계로 막는다
2026-09-03	모바일 네이티브 제외	12.4 즉시 진입 요구와 충돌