Architecture deep-dive

이 페이지의 쓰임

이 페이지는 코드베이스에 처음 들어오는 사람을 위한 지도입니다. 모든 서브시스템을 파일 경로와 함께 평면으로 나열한 시스템 색인과는 다릅니다. 색인은 카탈로그입니다. 이 페이지는 경로입니다. 무엇부터 읽을지, 그리고 코드가 실제로 어떻게 흐르는지 보여 줍니다. 카탈로그가 필요하면 색인으로 가세요.

서브시스템 지도

프로덕션 코드는 두 패키지로 나뉩니다. core/는 일반 목적의 자율 에이전트 런타임이고, plugins/는 1차 보조 플러그인입니다.core/ 안의 서브시스템은 4-계층 스택에 맞춰 정렬됩니다.

Agent     core/agent/        while(tool_use) 루프
Harness   core/cli/          thin CLI + serve 데몬 + IPC
          core/hooks/        라이프사이클 이벤트
          core/wiring/       부트스트랩 주입
          core/ui/           터미널 렌더
Runtime   core/llm/          프롬프트 조립 + 프로바이더 라우터
          core/tools/        도구 레지스트리 + 지연 로딩
          core/mcp/          MCP 서버 오케스트레이션
          core/memory/       다계층 컨텍스트
          core/skills/       스킬 디스커버리
          core/orchestration/ StateGraph 파이프라인
          core/scheduler/    예약 작업
          core/verification/ 가드레일 + cross-LLM
          core/integrations/ 메신저 게이트웨이
          core/automation/   드리프트 감지 + 모델 프로모션
          core/self_improving_loop/ 아우터 루프 설정
          core/audit/        Petri 감사 연결
          core/observability/ runlog + 진단
Model     core/llm/providers/ Anthropic / OpenAI / Codex / GLM 어댑터

최상위에는 진입 모듈 몇 개가 있습니다. core/runtime.py의 GeodeRuntime이 부트스트랩이고, core/state.py는 모든 파이프라인 노드가 받는 상태 형상을 선언하며, core/paths.py는 모든 디렉터리 경로를 한곳에서 해석합니다. 계층 경계가 왜 이렇게 그어졌는지는 왜 4-계층인가에 있습니다.

흐름 추적 하나. CLI 작업

요청 하나가 코드를 어떻게 지나는지 따라가면 지도가 살아 움직입니다. 먼저 평범한 CLI 작업입니다.

geode "<작업>"  (thin CLI, core/cli/)
   │  Unix 소켓 IPC
   ▼
GeodeRuntime  (core/runtime.py)  ── core/wiring/ 가 컨텍스트 주입
   ▼
AgenticLoop  (core/agent/loop/agent_loop.py)
   ▼  매 턴마다
컨텍스트 조립  (core/memory/ + core/llm/prompts/)
   ▼
LLM 호출  (core/llm/ 라우터 → core/llm/providers/)
   ▼
도구 호출?  ── 예 → core/tools/ 실행 → 결과 관찰 → 루프
   │
   └ 아니오 → 답변

thin CLI는 직접 일하지 않습니다. IPC로 geode serve 데몬에 붙고, 데몬 안의 단일 GeodeRuntime이 작업을 실행합니다. 매 턴마다 메모리 계층과 프롬프트 레이어가 토큰 예산 안에서 컨텍스트로 합쳐지고, 라우터가 프로바이더를 고르고, 모델이 도구를 요청하면 core/tools/가 실행합니다. 끝나는 경로는 안쪽 agentic 루프에 자세히 있습니다.

흐름 추적 둘. 자기개선 실행

아우터 루프는 같은 코어를 다른 입구로 지납니다.

예약 트리거  (core/scheduler/)
   ▼
정책 변형  (core/self_improving_loop/ 설정 로드)
   ▼
Petri 감사  (core/audit/ → plugins/petri_audit)
   │  같은 AgenticLoop를 측정 대상으로 실행
   ▼
결과 귀속  (차원 점수 → fitness)
   ▼
승격 또는 되돌림  (게이트 통과 시에만 SoT 갱신)

핵심은 두 루프가 코드를 공유하지 않고 기록을 주고받는다는 점입니다. 감사는 안쪽 루프와 같은 AgenticLoop를 측정 대상으로 돌립니다. 결과가 게이트를 통과해야만 정식 결과로 승격되고, 실패하면 변형 전으로 되돌립니다. 전체 흐름은 폐루프에 있고, 측정 프레임워크는 Petri × GEODE에 있습니다.

더 깊이

시스템 색인. 모든 서브시스템과 파일 경로의 평면 카탈로그.
왜 4-계층인가. 경계가 그 자리에 있는 이유.
왜 self-hosting 하네스인가. 런타임과 빌드 라인이 기본 단위를 공유하는 이유.
왜 ratchet 규율인가. drift를 막는 형태.

아키텍처 심화

이 페이지의 쓰임

서브시스템 지도

추천 읽기 순서

흐름 추적 하나. CLI 작업

흐름 추적 둘. 자기개선 실행

더 깊이