🗂️ 세부 상의 — SARA 시스템 설계

이 페이지 = SARA 시스템 전체 개발 계획 (설계 결정 + 페이즈 로드맵 + 구현 단위). 지금 진행 상태/착수 시드는 📦 SARA 통합 인수인계서, 세부 작업 추적은 ✅ 작업 트래커. 재정리: 2026-05-27 (KST) — 페이즈 우선 구조로 정리. 이전 버전은 노션 버전 기록 보존.

0. 목표 (4)

컨텍스트 부족 시 자동 새 세션 인계 — 한 대화방 경험 유지
프로젝트 구분 유지하며 연속 진행
노션보다 빠른 메모리/인계 저장소 (노션 속도·타임아웃 회피)
멀티에이전트 하네스 — 대화 지시만으로 코디(Claude Code) 작업 통합

1. 아키텍처 결정 (확정)

방안 B 채택: 채티 역할 커스텀 에이전트를 Agent SDK로 직접 제작. (방안 A = 브라우저 자동화 의존 → 불안정, 기각)
VS Code 안 채팅 패널이면 충분 (claude.ai 그대로일 필요 없음)
패널 = VS Code Webview 익스텐션 (Simple Browser 폐기, 풀 네이티브는 과도 → 기각)
저장소 = cmdboard RDS 단독 (로컬/혼합 미사용)
인계 임계치 = 65% (모델 컨텍스트 대비 누적 토큰, ResultMessage.usage로 산출)

2. 런타임 · 인증

Python claude-agent-sdk (Claude Code 동일 엔진): query()로 session_id 획득 → resume로 자동 인계, subagent 컨텍스트 격리, mcp_servers 외부도구, PreToolUse 훅 → broker 게이트
기본 AskUserQuestion(TTY 필요)은 금지 → 자체 패널 UI/대기큐로 질문 라우팅
인증: 구독 OAuth / setup-token(1년), API 키 미사용. ANTHROPIC_API_KEY는 비움(구독 OAuth 보호)
비용·적법성: 2026-06-15부터 Agent SDK 전용 월 크레딧(Pro $20 / Max5x $100 / Max20x $200 / Team Premium $100). 본인 단독 사용 적법, 타인에게 서비스 제공 시 Console API 키 필요

3. 노션 비동기 구조 (목표)

[빠른 경로]   기록 발생 → cmdboard RDS 큐에 즉시 write → 작업 계속 (지연 0)
[느린 경로]   백그라운드 워커가 '미반영' 행 polling → notion-bulk로 노션 반영 → '동기화 완료'

병목 = 노션 MCP 호출당 ~60초 동기 처리. RDS(수 ms)를 1차 저장소로 통일 → 체감 지연 0, 저장소 단일화, 다중 PC 동기화 자동
적용 범위 = 모든 노션 문서 갱신 (인수인계서·세부상의·아카이브 포함)
인계 요약 원칙: 최근 작업(NOW) 중심 구성 + 불변 핵심(인증 방식·경로/포트·위험작업 규칙·확정 사실)은 길이와 무관하게 항상 보존. 권장 구조 = ① NOW → ② 직전 결정·맥락 → ③ 불변 핵심 → ④ 과거 이력(링크/요약)

4. 페이즈 로드맵 (큰 흐름 — 계획변경 시에도 이 골격 우선)

Phase 1 (완료): 단독 SARA 패널 + MCP/커스텀 도구 + 파일 업로드. C:\dev\tools\vscode_sara :8770
Phase 2b (완료): PreToolUse 훅 → cody-permission-broker :7777 텔레그램 게이트
Phase 2a (완료): RDS 연동 자동 세션 인계 (sara_continuation 017 RDS 적용, 65% 인계). G1·G5 완료
Phase 2a-ext (완료): ① Webview 익스텐션 전환 ② 노션 갱신 비동기화(큐 018·워커 B-2 완성) ③ Claude Desktop 수준 UI/기능. G2~G6 + G7~G15 + UI 핫픽스 전부 완료·push (상세는 이력 아카이브)
Phase 3 (착수 — 2026-05-30 합의 확정): 채티↔GPT 자동 협의(agent-dialogue-hub, :8780)로 4미결 결론. 실행순서 = ③노션캐시 전문화+자식크롤(G2 큐) → ②계측 → (차단해제: cmdboard 하네스 실파일 대조) → ①ROUTER(chat/task/verify_required 3분류)+EVALUATOR(task성만) 이식. 외부 /chat 응답 불변·내부계약만, PLANNER/CODI disabled adapter, 스키마 cmdboard 단일소유·하네스 vendored. 상세 = 멀티에이전트 세부 상의 §10

5. 구현 단위 (착수 순서 = 트래커 그룹 G1~G7)

G1. 마이그레이션 017 sara_continuation (Phase 2a) — 비파괴 테이블 생성. 코디 = 파일 작성·커밋·master push·정적검증, SQL 적용 = 사용자 DBeaver 수동
G2. 노션 비동기 큐 (Phase 2a-ext) — notion_sync_queue 테이블 + 백그라운드 워커(notion-bulk 호출), 기록 write 지점 큐 전환
G3. Webview 익스텐션 골격 (Phase 2a-ext) — package.json + Webview 패널, 기존 FastAPI/agent 자산 재활용, Simple Browser 제거
G4. SDK 멈춤 전환 (Phase 2a-ext) — agent.py query() → ClaudeSDKClient(인터럽트), 멈춤 버튼 연동
G5. continuation_manager.py (Phase 2a) — persist(매 턴 갱신) / restore(재시작 resume·시드) / handoff(65% 요약·chain_id 상속), agent.py·server.py 연동
G6. UI/기능 이식 (Phase 2a-ext) — Claude Desktop 풍 채팅 UI · MCP 커넥터 설정 · 파일/이미지 업로드 · 모델 셀렉터 · cmdboard 프로젝트 연결 = projects 직접 조회(원천: poindev 하위 페이지 전부 시드) (+ 토큰사용량/세션목록/인라인 승인 등 추천)
G7. 멀티에이전트 하네스 (Phase 3, 합의 확정 2026-05-30) — ROUTER(chat/task/verify_required 3분류)+EVALUATOR(task성만) 1차 이식, PLANNER/CODI disabled adapter. 외부 /chat 응답 불변·결과계약은 activity_logs/HandoffArtifact 내부 기록. 코디 자동화(bridge)는 broker 경유 강제+EVALUATOR 통과 조건을 갖춘 뒤 별도 단계. 상세 = 멀티에이전트 세부 상의 §8·§10

6. 핵심 위치

SARA C:\dev\tools\vscode_sara (:8770) · broker C:\dev\tools\cody-permission-broker (:7777) · cmdboard C:\dev\cmdboard (RDS, BOARD_DB_*) · notion-bulk C:\dev\tools\notion-bulk

7. 미결 / 주의

✅ '기존 계정 프로젝트 연결' 확정(2026-05-27): (b) cmdboard projects 직접 조회. 원천 = 노션 poindev 하위 페이지 전부를 projects(code/name/repo_url)로 시드(신규 INSERT, 비파괴). (a) claude.ai Projects는 공개 API 없어 기각. claude-code MCP는 SARA 연결 제외.
마이그레이션 SQL 적용은 항상 DBeaver 수동 (cmdboard 규칙)
위험작업(DB DROP · force push · 운영배포)은 broker / 별도 세션. push는 master만

8. 되돌리기

신규 테이블/큐는 비파괴 (DROP으로 원복, 기존 cmdboard 무영향)
익스텐션 전환은 기존 vscode_sara 자산 보존 후 점진 이행
인계 요약 생성 실패 → 인계 보류, 기존 세션 유지 (맥락 손실 방지)