용어: harness와 scaffold
2026년 기준 에이전트 커뮤니티의 용어 관례는 두 층을 구분합니다. harness는 실행 계층입니다. 루프를 돌리고, 도구를 실행하고, 언제 멈출지 결정합니다. scaffold는 행동 정의 계층입니다. 프롬프트, 도구 설명, 지침 파일이 여기 속합니다. 에이전트는 model, scaffold, harness의 합입니다 (HuggingFace agent glossary, Firecrawl).
GEODE가 메타 하네스인 이유는 세 겹의 관계 때문입니다.
- 제작. GEODE의 코드는 다른 하네스(Claude Code, Codex CLI)가
CLAUDE.md와AGENTS.md라는 scaffold를 읽으며 생산합니다. 아래 Scaffold 부문이 이 제작 하네스의 카탈로그입니다. - 실행. GEODE 자체가 하네스입니다. Context Control, Plan and Execute, Verify, Observe 네 부문의 런타임 메커니즘이 모델의 발산을 묶습니다.
- 자기개선. self-improving outer 루프가 자기 자신의 runtime scaffold(시스템 프롬프트 섹션, behaviour kinds)를 변이하고 감사해 승격하거나 되돌립니다. 하네스가 자기 scaffold를 다시 쓰는 구조입니다.
표 읽는 법
각 행은 메커니즘 하나입니다. 어떤 발산을 묶는지, 운영자가 만지는 제어 지점이 무엇인지, 코드가 어디 있는지를 담습니다. 모든 행은 코드에서 클래스와 제어 지점의 존재를 확인한 것만 실었습니다. 수치(임계값, 캡, 기본값)는 소스의 상수를 그대로 옮긴 것입니다.
1. Context Control
모델 컨텍스트에 무엇이 들어가는지를 묶는 메커니즘들입니다. 루프와 가드레일이 출력의 상한을 결정한다는 원칙의 구현부입니다. 배경 설명은 컨텍스트 조립과 도구와 툴셋 문서에 있습니다.
| 메커니즘 | 묶는 발산 | 제어 지점 | 위치 |
|---|---|---|---|
| ContextWindowManager | 컨텍스트 총량이 임계선을 넘으면 emergency prune과 recovery를 발화 | CONTEXT_CRITICAL / CONTEXT_OVERFLOW_ACTION hooks | core/agent/context_manager.py |
| Context budget policy | 모델 window에서 토큰 상한, warning, critical 밴드를 유도하는 단일 SoT | ceiling 200k, warn 50/70/80%, crit 90%, output reserve 20k | core/orchestration/context_budget.py |
| Message prune policy | first-user, bridge, 최근 N개만 유지해 히스토리를 예산 안에 고정 | activation at 30 msgs, keep-recent 5/8, floor 3 | core/orchestration/context_budget.py |
| Deferred tool loading | 도구가 임계 초과면 스키마를 검색 도구 뒤로 지연시켜 컨텍스트 범람 차단 | TOOL_DEFER_THRESHOLD=16, always-loaded set | core/llm/tool_defer.py |
| Cache breakpoint policy | trailing cache_control breakpoint 수를 제한해 캐시 적중과 호출 오버헤드를 교환 | cache-policy.json messages_breakpoints, 0..3 | core/llm/cache_policy.py |
| System-reminder injection | 말미 고정 주입이 prefix-stable이라 프롬프트 캐시 키를 깨지 않음 | cache contract pinned by tests | core/agent/system_injection.py |
| System prompt modes | persona 주입과 audit strip으로 모델이 수렴할 identity를 제어 | GEODE_PERSONA=off, GEODE_AUDIT_UNRESTRICTED=1 | core/agent/system_prompt.py |
| ToolResultOffloadStore | 대형 tool result를 디스크로 이관하고 컨텍스트에는 ref만 남김 | threshold 5000 tokens, TOOL_RESULT_OFFLOADED hook | core/orchestration/tool_offload.py |
| Result token guard | tool result 단건에 모델 파생 토큰 상한을 적용해 절단 | max_tool_result_tokens setting | core/agent/tool_executor/result_token_guard.py |
| compact_conversation | server-side compaction이 없는 프로바이더용 4단계 클라이언트 압축 | keep_recent arg, Anthropic no-op (server-side) | core/orchestration/compaction.py |
| SessionManager | 메시지 상태를 checkpoint로 저장, 복원해 긴 실행을 유한 지점에서 재개 | geode_checkpoints.db, cleanup 72h | core/memory/session_manager.py |
| EpisodicStore | 회전 캡이 있는 episodic 메모리 tier, 무한 성장 없이 recall 공급 | JSONL rotation cap | core/memory/episodic.py |
| DreamingService | 세션을 배경에서 압축 artifact로 통합 | dream artifact via SessionManager | core/memory/dreaming.py |
2. Plan and Execute
모델 출력을 통제된 행동으로 바꾸는 메커니즘들입니다. 중심은 AgenticLoop, 곧 inner 루프입니다. outer 루프(self-improving)가 시스템 자체를 다듬는 동안, inner 루프는 작업 하나를 끝까지 처리합니다. 루프는 ReAct 계열의 reason과 act 교차 패턴을 따르되, 그 위에 명시적 cognitive 층이 얹혀 있습니다.
Cognitive 사이클: reflection, plan, verify, replan
한 라운드는 도구 실행 결과를 관측하고, reflection으로 믿음을 갱신하고, 트리거가 서면 plan을 다시 씁니다. 네 조각이 하나의 사이클로 묶입니다.
- Planning. 명시적
Plan객체가 세션에 붙고 replan마다 revision이 증가합니다. 다단계 작업의 승인 게이트는 별도 메커니즘인 PlanMode가 맡습니다. - Reflection (cognitive). 도구 라운드마다
record_reflection구조화 호출 1회가 CognitiveState를 갱신합니다. hypotheses 5개 이하, confidence 0..1, next_action_hint가 subgoals로 들어갑니다. 전체 대화가 아니라 상태 스냅숏과 도구 요약만 봅니다(clean-context 규율). - verify 후 replan. replan은 세 트리거로 발화합니다. verify FAIL(다음 실행의 첫 라운드), cadence(
replan_interval라운드마다), low-confidence (confidence 0.4 미만, edge-trigger라 회복 전 재발화가 없어 replan 폭풍을 방지). replan 실패는 루프를 죽이지 않습니다. - 지속화. CognitiveStateStore가 스냅숏과 이벤트 스트림을 SQLite에 저장하고, 세션 재개의 DB-first 소스가 됩니다.
기본 round 상한이 0(무제한)이라 실질적 경계는 시간과 비용 예산입니다. 루프가 정직하게 끝나는 명명된 종료 경로는 아래 16개에 정상 완료(도구 호출 없는 텍스트 응답)를 더한 것입니다.
max_roundstime_budget_expiredsession_time_budget_handoffsession_time_budget_expiredinput_blockedbilling_erroruser_cancelledmodel_action_requiredactionable_partialcontext_exhaustedtool_use_yieldcost_budget_exceededuser_clarification_neededmodel_refusalconvergence_detectedrepeated_success_no_progress
| 메커니즘 | 묶는 발산 | 제어 지점 | 위치 |
|---|---|---|---|
| AgenticLoop | perceive, plan, act, observe inner 루프. round, time, cost 가드가 폭주를 절단 | max_rounds (default 0=unlimited), time_budget_s, cost_budget | core/agent/loop/agent_loop.py |
| Plan + Dynamic Replan | 명시적 Plan 객체를 세션에 유지하고 verify FAIL, cadence, low-confidence 세 트리거로 planner LLM을 재발화 | replan_interval, REPLAN_LOW_CONFIDENCE=0.4 | core/agent/plan.py |
| Reflection node | 도구 라운드마다 record_reflection 구조화 호출 1회로 CognitiveState의 가설과 confidence를 갱신 | cognitive_reflection_enabled, max_tokens 512 | core/agent/loop/_reflection.py |
| CognitiveState + store | hypotheses, confidence, subgoals 믿음 상태를 SQLite에 지속화. 세션 재개의 DB-first 소스 | snapshot + append-only event stream | core/memory/cognitive_state_store.py |
| ConvergenceDetector | 동일 도구 에러 3연속 또는 무진전 성공 반복에서 루프를 종료 | REPEATED_SUCCESS_THRESHOLD=5 | core/agent/convergence.py |
| TimeBudget | 세션 wall-clock 예산. 만료 전 임계에서 handoff를 먼저 발화 | budget_seconds, handoff threshold, HANDOFF_TRIGGERED hook | core/agent/budget.py |
| Cost budget guard | 세션 USD 상한. 80%에서 경고, 초과 시 루프 정지 | cost.limit_usd config, COST_LIMIT_EXCEEDED hook | core/agent/loop/agent_loop.py |
| Lane / LaneQueue | 세마포어로 세션 간 동시 실행을 제한 | max concurrent 50, max sessions 256 | core/orchestration/lane_queue.py |
| Audit lane | Petri 감사 서브프로세스를 직렬화해 cron과 수동 감사의 충돌, 이중 지출 차단 | max_concurrent 1, 15-min timeout | core/orchestration/audit_lane.py |
| SubAgentManager + roles | 서브에이전트의 도구 표면과 재귀 위임을 role allowlist로 제한 | SUBAGENT_ROLES, role_denied_tools | core/agent/sub_agent.py |
| Candidate sampling | 같은 작업 best-of-N 팬아웃과 judge 선택. N 상한으로 비용 제한 | hard cap N=4, diversity lens per index | core/agent/candidate_sampling.py |
| ToolExecutor denylist | safety gate와 handler 조회 이전에 도구를 거부하는 headless denylist | denied_tools frozenset (ctor) | core/agent/tool_executor/executor.py |
| Safety classification | 도구별 위험 분류. DANGEROUS 도구는 HITL 승인 필수 | DANGEROUS_TOOLS set, GEODE_DANGEROUSLY_SKIP_PERMISSIONS | core/agent/safety.py |
| Computer-use HITL | 화면 제어 도구는 명시적 사용자 거부 경로가 있는 게이트를 통과 | 600s tool deadline, denied result contract | core/agent/tool_executor/executor.py |
| Approval FSM | HITL 승인 상태기계. 3-strike 자동 거부, 모든 전이를 기록 | legal-transition table, APPROVAL_TRANSITION hook | core/agent/approval_fsm.py |
| Hook interceptor | interceptor 모드 훅이 도구, LLM 호출을 실행 중에 차단하거나 수정 | handler returns block:true, per-handler timeout_s | core/hooks/system.py |
| PlanMode | 다단계 작업의 plan, approve, execute 게이트 | MANUAL (default) vs AUTO execution mode | core/orchestration/plan_mode.py |
| SchedulerService | lock과 jitter로 반복 작업의 동시 발화를 억제 | enable_jitter, max_jitter_ms, SchedulerLock | core/scheduler/service.py |
| Model switching | /model 전환 시 drift-health 체크와 캐시 안전 breadcrumb 주입 | /model command, MODEL_SWITCHED hook | core/agent/loop/_model_switching.py |
3. Verify
비결정론적 출력을 신뢰 가능한 수준으로 수렴시키는 메커니즘들입니다. 턴 단위 검증부터 self-improving 루프의 fitness 게이트, critical floor, 대조군까지 이어집니다. 차원 체계는 Judge 차원 문서를 참고하십시오.
| 메커니즘 | 묶는 발산 | 제어 지점 | 위치 |
|---|---|---|---|
| VerifyMode | 턴 단위 rubric 검증. 회복 가능한 miss는 재시도로 수렴 | GEODE_VERIFY_MODE (off / rule_based / llm_judge) | core/agent/verify.py |
| compute_fitness | per-dim 감사 점수를 stability 가중으로 단일 fitness 스칼라에 집계 | critical_margin 0.5, MC margin 1000 samples | core/self_improving/fitness.py |
| AXIS_TIERS + critical floors | 차원을 tier로 분류. critical 5개 dim은 후퇴 시 무조건 거부 | CRITICAL_DIMS, tier weights | core/self_improving/fitness.py |
| Promotion margin gate | gain 대 stderr margin으로 승격 판정. critical veto가 항상 선행 | fitness_margin_floor, hard-contract veto | core/self_improving/gate.py |
| Promote-policy control arm | gate, random, never 3-arm으로 이득을 무변이 바닥과 대조 측정 | --promote-policy, --promote-policy-seed | core/self_improving/gate.py |
| Rollback condition | 자유 서술 롤백 조건을 파싱해 veto 신호로 평가 | regression-pattern grammar | core/self_improving/loop/observe/rollback_condition.py |
| Statistical power | 목표 효과 검출에 필요한 표본 수를 산출해 노이즈발 승격을 억제 | --replicate M, alpha/power defaults | core/self_improving/loop/observe/statistical_power.py |
| Petri adversarial audit | 적대 감사가 per-dim 안전 점수를 생산. 루프의 측정 계층 | geode audit CLI, petri role config | core/self_improving/measure.py |
| Champion chain | champion baseline을 변이, 감사 후 승격 또는 되돌림. (1+1) 체인 | baseline.json vs tracked baseline_archive.jsonl | core/self_improving/campaign.py |
| Seed survivor selection | seed 생성 루프의 생존자를 감사 seed 풀로 교체하는 cross-loop handoff | AUTORESEARCH_SEED_SELECT, seed_limit | core/self_improving/train.py |
| Judge selection | cross-LLM judge가 N개 후보 출력을 하나로 수렴. 실패는 관측 가능 | select_candidate judge tool | core/agent/candidate_sampling.py |
4. Observe
실제 작동을 계측하는 메커니즘들입니다. 65개 훅 이벤트 버스가 중심이고, 모든 계측 저장소에 보존 캡이 있습니다. 운영 관점은 관측성 문서에 있습니다.
| 메커니즘 | 묶는 발산 | 제어 지점 | 위치 |
|---|---|---|---|
| HookSystem | 65개 이벤트의 중앙 계측 버스. observe, feedback, interceptor 3채널 | trigger / trigger_with_result / trigger_interceptor | core/hooks/system.py |
| Event persistence spec | 이벤트별 보존 클래스와 SQL, transcript 지속 여부를 선언하는 카탈로그 | 4 retention classes (high-volume/standard/audit/transient) | core/hooks/catalog.py |
| HookEventStore | row, age, payload 캡이 있는 SQLite 이벤트 보존 | 7/30/180d retention, max 100k rows, 8KB payload | core/observability/event_store.py |
| HookPersistenceSink | 각 dispatch를 spec에 따라 SQL과 transcript로 라우팅 | persist_sql / mirror_transcript flags | core/observability/hook_persistence.py |
| SessionTranscript | 세션 이벤트의 append-only JSONL 감사 추적 | transcript dir, per-event truncation | core/observability/transcript.py |
| SessionMetrics | 토큰, 캐시, thinking, 비용, 도구 호출, 시간 예산의 누적 ledger | ContextVar-scoped, estimated_cost_usd | core/observability/session_metrics.py |
| JobRunLog | 스케줄 job별 실행 이력. 크기와 행 수로 자동 prune | get_runs(limit), size/row prune | core/observability/run_log.py |
| UsageStore | 일, 월 롤링 사용량 ledger. geode history의 데이터 소스 | ~/.geode/usage/*.jsonl, eval-id dedup | core/llm/usage_store.py |
| Token tracker | 호출당 로컬 비용 계산과 cache-hit-rate 집계 | per-provider cost tables | core/llm/token_tracker.py |
| OAuth usage windows | 5시간, 7일 quota 버킷을 추적해 rate-limit 전에 backoff | quota-aware backoff windows | core/llm/oauth_usage.py |
| OTel export | 런타임 이벤트의 선택적 OpenTelemetry span, metric 내보내기 | env/config gated exporter | core/observability/otel_export.py |
| ActivityRegistry | 지금 실행 중인 도구를 보여주는 라이브 activity 레지스트리 | updated per tool execution | core/observability/activity_registry.py |
5. Scaffold, 제작 하네스
위 네 부문이 GEODE가 작업을 실행할 때의 하네스라면, 이 부문은 GEODE 자신이 만들어질 때의 하네스입니다. 코드 생성 절차(CLAUDE.md 룰북, Socratic Gate), 검증 절차(품질 게이트, CI ratchet, cross-LLM 검증), 커밋과 PR flow(worktree 격리, squash merge)가 에이전트 빌더의 발산을 묶습니다. 표의 실패 모드 상당수는 실제 사고에서 나온 것이고, CLAUDE.md의 각 룰이 원인 사고를 인용합니다. 이 규율의 배경은 왜 ratchet 규율인가와 왜 self-hosting 하네스인가 문서에 있습니다.
| 메커니즘 | 막는 실패 모드 | 게이트 | 위치 |
|---|---|---|---|
| CLAUDE.md | 제작 룰북. CANNOT 35룰(8영역)이 incident 인용과 함께 게이트 우회, SoT 드리프트, over-engineering을 차단 | CANNOT/CAN tables, wiring invariants | CLAUDE.md |
| AGENTS.md | 코드 루트 내비게이션 맵과 Codex operating loop. 구조를 모른 채 수정하는 실패를 차단 | module map, non-negotiables | AGENTS.md |
| GEODE.md | 런타임 identity와 RUNTIME CANNOT. 개발용 CANNOT의 실행 시점 대응물 | Tier-0 injection, GEODE_PERSONA opt-out | GEODE.md |
| Workflow 0-8 + Socratic Gate | GAP audit과 5질문 게이트가 이미 있는 것의 재구축, 불필요 구현을 사전 차단 | Socratic Q1-Q5, GAP 3-way classify | CLAUDE.md, docs/workflow.md |
| Scaffold skills | gitflow, workflow, anti-deception, verification-team 등 절차 스킬의 progressive disclosure | skill triggers per session | docs/scaffold-skills.md |
| Local quality gates | lint, format, type, imports, test, CLI smoke 6종. 파이프로 감싼 게이트는 금지 | exit codes asserted bare | CLAUDE.md (Quality Gates) |
| CI ratchet suite | legacy import, repo hygiene, slop growth, llms 버전, petri bundle, hero layout 커스텀 ratchet이 침묵 퇴행을 차단 | scripts/check_*.py wired into ci.yml | .github/workflows/ci.yml |
| Prompt integrity pins | runtime 프롬프트 변경은 같은 커밋에서 해시 pin 갱신을 강제. 의도치 않은 drift는 빌드 실패 | _PINNED_HASHES (4 pins), verify_prompt_integrity | core/llm/prompts/__init__.py |
| Test-count floor | 테스트 수 하한 ratchet. 테스트 삭제로 만드는 가짜 green을 차단 | pytest count floor in CI | .github/workflows/ci.yml |
| Worktree isolation + .owner | 작업 단위마다 worktree 격리. 타 세션 소유물 보호, orphan은 hygiene ratchet이 검출 | .owner convention, check_repo_hygiene.py | .claude/worktrees/ |
| Merge flow | feature는 develop에 squash, develop은 main에 pass-through. 매 사이클 main에서 develop로 선동기화 | CI 5/5 required, PR template | CLAUDE.md (PR & Merge) |
| Version SoT fan-out | 버전 스탬프 5위치와 파생 파일 재생성. stale 스냅숏은 CI ratchet이 차단 | sync-stats.mjs, check_llms_version.py | site/scripts/sync-stats.mjs |
| Cross-LLM verification | PR마다 Codex MCP 교차 검증을 병행. 로컬 게이트 단독 종결 금지 | top-tier reviewer model pinned | docs/workflow.md |
관련 문서
- 두 개의 루프. 이 카탈로그가 기대는 멘탈 모델.
- 프론티어 비교. 각 메커니즘이 어느 frontier 시스템에서 왔는지.
- 장기 실행 안전. round, time, cost 가드의 운영 관점.
- 서브에이전트 오케스트레이션. Lane과 role allowlist의 상세.