Decisions
GoVail의 핵심 성과는 복잡한 AI 시스템을 만든 것이 아니라, 어떤 복잡도가 GoVail의 책임이 아닌지를 구분한 것이다.
아래 결정은 현재 모노레포의 ARCHITECTURE.md, BOUNDARIES.md, Gateway Execution Profile, Router /decide, Runtime conversational / governed path를 기준으로 정리했다.
D1. 모든 요청을 Runtime에 넣지 않는다
초기 접근. Gateway를 통과한 요청은 지능이 필요하니 Runtime을 거치게 했다.
문제. Coding Agent는 이미 계획·도구·저장소 루프를 가지고 있다. 그 위에 GoVail Runtime을 올리면 같은 일을 두 번 한다. 지연만 늘고 책임은 흐려진다.
결정. Credential metadata의 execution_profile로 경로를 나눈다.
agentic_coding— CODE Thin Path. Gateway 거버넌스만 적용하고 LLM으로 직접 보낸다.governed_web— WEB Governed Path. Router와 Runtime을 탄다.
키 prefix는 힌트일 뿐 SSOT가 아니다.
D2. Gateway는 의미를 해석하지 않는다
초기 접근. 빠른 분류기를 Gateway에 두면 왕복이 줄어든다.
문제. Gateway가 retrieval, planning, query rewrite, semantic routing을 갖는 순간 보안 경계와 지능 평면이 섞인다. 실패 모드가 한 프로세스에 쌓인다.
결정. Gateway는 Auth, DLP, rate limit, cost, audit, protocol adaptation만 소유한다. 의미 해석은 Router/Runtime이다.
관련 기록: Gateway vs Runtime
D3. Router는 답을 만들지 않는다
초기 접근. Router가 RAG를 조회하고 프롬프트를 조립하면 한 hop으로 끝난다.
문제. Router가 컨텍스트를 주입하는 순간, 라우팅 결정 서비스가 지식 평면이 된다. 상태와 지연이 Gateway 옆에 붙는다.
결정. Router는 RoutingSummary를 받아 route_target, execution_mode, side_effect, approval_required만 반환한다. Requested Interaction은 경로 후보이지 semantic truth가 아니다.
현재 설명: Architecture
초기 기록: Router 설계
D4. 모델 추천은 실행 권한이 아니다
초기 접근. 모델이 "이슈를 생성하겠다"고 하면 실행해도 된다고 보기 쉽다.
문제. LLM output은 확률적 제안이다. 그 문장을 외부 write 권한으로 승격하면 실행 경계가 사라진다.
결정.
Model Recommendation != Execution Authority해석·제안은 probabilistic zone에 남긴다. schema validation, authorization, policy, approval, payload integrity, provenance, idempotency, audit는 deterministic zone이다. LLM은 자신의 외부 side effect를 승인할 수 없다.
D5. 정밀 주장은 Evidence가 필요하다
초기 접근. 충분히 큰 모델이면 소속팀, 버전, 순위, Named Entity 사실을 답할 수 있다.
문제. parametric knowledge는 최신 사실에서 깨진다. 검색이 실패했다고 대상이 없다고 단정하는 오류도 생긴다.
결정. 최신성, 정밀 수치, Named Entity 사실은 Evidence Dependency로 다룬다. 검색 결과는 evidence producer이지 존재 증명이 아니다. 원문 user message와 explicit entity는 preprocessor가 치환하지 않는다.
검증: Validation
D6. Application State를 Core에서 뺀다
초기 접근. 프로젝트 RAG와 작업 기억을 Core Memory 서비스로 중앙화하면 모든 앱이 편하다.
문제. 소설 lore, 도메인 진행 상태, 앱 DB가 Core로 들어온다. GoVail이 플랫폼이 아니라 여러 앱의 백엔드가 된다.
결정. Application이 DB, workflow, business logic, 앱 RAG를 소유한다. GoVail Core는 Gateway, Evidence, Policy, Audit에 남는다. 앱 컨텍스트가 필요하면 GoVail MCP로 노출 계약만 맞춘다.
초기 기록: Memory RAG
D7. 범용 Workflow를 Core 제품에서 내린다
초기 접근. Temporal 위에 코드 스캔, 리뷰, PR, 소설 파이프라인 등 여러 워크플로우를 올렸다.
문제. Core가 워크플로우 플랫폼이 되면 도메인마다 상태가 생긴다. 제품 주장이 흐려진다.
결정. durable execution은 승인 대기, 재시도, 외부 write처럼 실행 거버넌스가 필요한 구간에만 쓴다. V1에서 제품으로 주장하는 governed capability는 repository review와 승인된 GitHub Issue 생성이다. 그 외 워크플로우는 frozen compatibility다.
초기 기록: Temporal 워크플로우
D8. Scanner를 Core 소개에서 내린다
초기 접근. 레거시 코드를 스캔해 Gateway 정책 힌트를 만들면 AI 도입이 안전해진다.
문제. Scanner는 유용한 실험이지만, 현재 Core의 요청 경로(Gateway → profile → Router/Runtime)를 구성하지 않는다. 정적 분석기를 제품 정체성으로 두면 Gateway/Governance가 가려진다.
결정. Scanner는 Experiments / Archived로 둔다. 기록은 남긴다.
초기 기록: Scanner → Policy
정리
| 초기 접근 (제거/격리) | 문제점 | 현재 아키텍처 결정 |
|---|---|---|
| 모든 요청의 Runtime 중첩 | Coding Agent의 자체 루프와 중복 | CODE Thin Path |
| 중앙 Memory | Application State 경계 침범 | App-owned State |
| 범용 Workflow 제품화 | Core 복잡도 및 도메인 종속성 증가 | Governed external action (Fail-closed) |
| LLM의 실행 승인 | 확률적 제안과 실행 권한의 혼동 | Deterministic boundary |
| Parametric 사실 확정 | 최신 사실 오류 및 환각 | Evidence dependency & Grounding |
| Scanner를 Core 축으로 소개 | 핵심 요청 경로와의 불일치 | Gateway / Governance 중심으로 축소 |
기능을 계속 추가하는 방식이 아니라, 실패와 실험을 거치면서 Core의 책임을 엄격히 제한하고 경계를 좁혀나갔습니다.
결론: 복잡도를 통제하는 도구들
1인 개발자가 여러 분산 서비스를 안정적으로 다루기 위해서는 뛰어난 기억력보다는 시스템적인 강제력이 필요합니다.
"1인 개발자가 여러 분산 서비스를 안정적으로 다루기 위해서는 뛰어난 기억력보다는 시스템적인 강제력이 필요합니다."
OpenAPI & JSON Schema SSOT
서비스 간 호출 규격을 코드 주석이나 문서가 아닌 스키마로 단일화. 코드 생성 및 런타임 직렬화 검증을 강제합니다.
Deterministic Policy Boundary
모델의 확률적 제안과 시스템 실행 권한을 물리적으로 분리. 외부 Write는 사용자 승인과 해시 검증을 통과해야만 실행됩니다.
Credential-driven Path Isolation
클라이언트 헤더에 의존하지 않고 서버측 자격증명 메타데이터(`execution_profile`)로 Thin Path와 Governed Path를 엄격히 분기합니다.
Executable Contract Tests
모든 라우팅 판정과 페일클로즈(Fail-closed) 동작을 CI/CD 파이프라인에서 자동 검증하여 회귀 버그를 원천 차단합니다.