SKIX Harness 구성요소 원장과 감축 관리
이 문서는 SKIX Cloud A2A를 둘러싼 prompt, cue, selector, repair, retry, context, contract와 평가 도구를 한 종류의 "하네스"로 뭉뚱그리지 않고 관리한다. 목적은 하네스를 키우는 것이 아니라 모델이 좋아질 때 지워도 되는 요소와 제품이 끝까지 소유해야 하는 요소를 구분하는 것이다.
관리 원칙
모든 구성요소는 네 분류 중 하나를 가져야 한다.
| 분류 | 의미 | 기본 정책 |
|---|---|---|
| 안전 invariant | 권한, 개인정보, 물리 안전, 금지 행동을 보장 | 모델과 무관하게 유지하고 우회 금지 |
| 제품 계약 | capability, schema, state, evidence, legacy 호환을 보장 | 구현과 테스트로 유지 |
| 모델 보정 | 특정 모델의 의미·형식·추론 한계를 보완 | 모델 교체 때 우선 감산 실험 |
| 관측·검증 | trace, replay, eval, 비용과 회귀를 측정 | 유지하되 제품 동작에 불필요하게 개입하지 않음 |
유지와 삭제 사이에는 격리가 있다. 특정 모델에만 필요한 보정은 공통 runtime에
남기지 않고 model profile이나 adapter로 옮긴다.
현재 코드 기준 초기 원장
2026-08-23 feature_task_orchestration_on_new_logic 소스에서 확인한 시작점이다.
완전한 전수조사 결과가 아니라 감산 작업의 우선순위를 정하기 위한 1차 원장이다.
줄 수는 품질 판정이 아니라 책임 혼합 가능성을 찾는 복잡도 신호로만 사용한다.
| ID | 구성요소 | 현재 위치 | 1차 분류 | 조치 방향 |
|---|---|---|---|---|
| H-001 | Main Router prompt와 response schema | planner/assets/main_router.*, main_router_api.py |
모델 보정 + 제품 계약 혼합 | instruction과 schema validation을 분리 |
| H-002 | Preclassifier semantic cue | planner/preclassifier.py |
모델 보정 + 후보 축소 최적화 | rule별 기여도를 측정하고 중복 cue 감산 |
| H-003 | Flow ranking과 owner 보정 | flow_selection_core.py, _apply_ranked_flow_center() |
모델 보정 + owner 정책 혼합 | catalog owner 권위를 하나로 수렴 |
| H-004 | DEF/STT, ODL/STT second-pass judge | second_pass_*_judge.system_prompt.txt |
모델 보정 | 신규 모델의 첫 ablation 후보 |
| H-005 | Plan normalize·repair 함수군 | main_router_api.py |
계약 + semantic repair 혼합 | 구조 검증은 유지하고 의미 재작성은 별도 측정 |
| H-006 | Context compact·cache | context_cache.py, _compact_device_context_for_planner() |
제품 계약 + 효율화 | freshness·source를 보존하며 유지 |
| H-007 | Global response policy | shared/assets/global_response_policy_* |
안전 invariant + 표현 정책 | 금지·privacy와 말투·스타일을 분리 |
| H-008 | Specialist prompt | agents/*/assets |
도메인 지시 + 모델 보정 | owner별 최소 계약만 유지 |
| H-009 | Gemini transport retry | gemini_client.py |
제품 신뢰성 | retryable 오류만 bounded retry 유지 |
| H-010 | Experience admission·grounding·temporal review | experience_admission.py, main_router_api.py |
실험적 모델 보정 + 목표 계약 | shadow·live tier와 호출 예산으로 제한 |
| H-011 | Experience Supervisor | runtime/experience_supervisor.py |
제한된 의미 loop | 정상 progress 호출 금지, 최대 replan 유지 |
| H-012 | Workflow·Task event state | runtime/workflow_state.py, runtime/task_manager.py |
제품 실행 계약 | 모델과 분리된 deterministic core로 유지 |
| H-013 | Event simulator·contract verifier | tools/task_event_* |
관측·검증 | callback과 replan 회귀 검증에 유지 |
| H-014 | Holdout·shadow·live artifact | artifacts/a2a_* |
관측·검증 | dataset·정책·모델·harness version을 함께 기록 |
현재 주요 파일 규모는 다음과 같다.
| 파일 | 확인 규모 | 해석 |
|---|---|---|
planner/main_router_api.py |
약 11,795줄 | owner, normalize, repair, Experience review 책임 분리 필요 |
planner/preclassifier.py |
약 4,608줄 | semantic cue의 기여도와 중복을 측정할 필요 |
planner/flow_selection_core.py |
약 2,502줄 | policy ranking과 모델 ranking의 권한 경계 확인 필요 |
planner/assets/main_router.system_prompt.txt |
약 354줄 | 모델 개선 시 prompt 감산 후보 |
runtime/orchestrator.py |
약 3,161줄 | 실행 순서와 응답 조합 책임을 runtime 관점에서 검토 |
runtime/workflow_state.py |
약 3,156줄 | 장기 상태와 evidence 처리의 제품 계약 자산 |
원장 필드
각 항목은 다음 필드를 채운다.
| 필드 | 기록 내용 |
|---|---|
component_id |
변경되지 않는 원장 ID |
name |
사람이 이해할 수 있는 구성요소명 |
source_path |
실제 코드·prompt·config 위치 |
owner |
변경 승인과 장애 대응 책임자 |
category |
invariant, contract, model_compensation, observability |
trigger |
어떤 요청·상태·모델에서 활성화되는가 |
decision_authority |
결과를 보조하는가, 최종 판단을 바꾸는가 |
model_profile |
공통 또는 특정 모델 전용 여부 |
cost |
호출 수, token, latency, 유지보수 비용 |
risk_if_removed |
안전, 품질, 호환, 운영 위험 |
evidence |
추가 당시 해결한 실패와 현재 회귀 데이터 |
ablation_test |
제거·단순화했을 때 실행할 테스트 |
rollback |
원복 flag, commit, artifact 위치 |
decision |
keep, simplify, isolate, retire |
review_at |
다음 모델 교체 또는 정기 검토 시점 |
구성요소 카드 예시
component_id: H-004
name: ODL-STT second-pass judge
source_path: gemini/a2a/planner/assets/second_pass_odl_stt_judge.system_prompt.txt
owner: Cloud A2A
category: model_compensation
trigger: first pass가 ODL/STT 경계 조건을 만족할 때
decision_authority: route family를 변경할 수 있음
model_profile: current-gemini-profile
cost: 조건 충족 turn에서 모델 호출 1회 추가
risk_if_removed: ODL/STT 경계 회귀 가능
evidence: 경계 holdout과 route trace
ablation_test: DEF/STT·ODL/STT holdout + 일반 ODL 회귀
rollback: feature flag 복원
decision: review
review_at: next-model-upgrade
감축 우선순위
P0 · 중복 판단 제거
동일 turn에서 Router, ranked flow, second pass와 post-repair가 같은 의미를 다시 판단하면 최종 authority와 실패 원인 추적이 어려워진다.
- 최종 owner를 바꾸는 지점을 모두 trace에 표시한다.
- owner 변경 횟수와 모델 호출 횟수를 turn별로 집계한다.
- 동일 오류를 두 단계가 함께 보정하면 하나를 shadow로 내린다.
- catalog owner, Planner plan과 safety gate의 Who·How·Can 경계를 유지한다.
P1 · Rule·cue 기여도 측정
Preclassifier cue는 한꺼번에 제거하지 않는다. 의미군 단위로 묶어 ablation한다.
| 의미군 | 예 | 검증 세트 |
|---|---|---|
| 대화 회복 | 짧은 인사, 반응, 후속 표현 | DEF ↔ STT_NULL |
| 기기 실행 | 공간, 설정, 이동, 상태 확인 | ODL ↔ DEF/STT_NULL |
| 외부 조회 | 뉴스, 공인, 날씨, 검색 | FRG ↔ DEF/STT_NULL |
| 스케줄 | 시간, 예약, 등록·조회·수정 | SCH ↔ DEF/ODL |
| 제품 설명 | 사용법, 기능, 업데이트 | DQR ↔ FRG/DEF |
각 의미군은 제거 전, 제거 후, 강한 모델 + 제거를 비교한다. 전체 정확도가
같아도 특정 family의 치명적 회귀가 있으면 삭제하지 않는다.
P2 · Prompt 감산
- 중복된 global policy를 route prompt에서 제거한다.
- 예시 목록보다 capability와 출력 계약을 우선한다.
- 모델이 이미 지키는 형식 지시는 줄인다.
- 삭제한 문장을 별도 backup prompt로 누적하지 않고 Git history로 관리한다.
P3 · Experience 호출 제한
Experience 관련 grounding, temporal review와 Supervisor는 목표 가치가 있는 turn에만 허용한다.
- 단일 명령은 기존 owner 경로로 마감한다.
- 정상 task progress는 로컬에서 처리한다.
- 실패가 retry 가능한 실행 문제면 TaskManager가 처리한다.
- 목표 의미가 바뀌거나 사용자 결정이 필요한 경우만 모델 재판단 후보가 된다.
삭제하면 안 되는 요소
다음 항목은 모델 성능 비교만으로 제거하지 않는다.
- 인증·권한과 caller 검증
- capability allowlist와 schema validation
- unsafe side effect 차단
- device state freshness와 source 표시
- queue, timeout, cancel, preemption과 resource policy
- ACK와 물리 완료를 구분하는 terminal evidence
- legacy app·IoT·PUI 호환 계약
- trace, artifact, rollback과 release audit
표현이 장황하면 단순화할 수 있지만 책임 자체는 남겨야 한다.
Retirement 판정
| 판정 | 조건 | 처리 |
|---|---|---|
| Keep | 안전·권한·제품 계약에 필수 | hard invariant 또는 contract로 명시 |
| Simplify | 목적은 유효하나 구현이 과도 | prompt·rule·호출 수 축소 |
| Isolate | 특정 모델에서만 필요 | model profile과 adapter로 이동 |
| Shadow | 효과가 불명확하거나 교체 후보 | 결과만 기록하고 live authority 제거 |
| Retire | 제거 후 품질·안전·운영 회귀 없음 | 코드·flag·문서·metric을 함께 제거 |
retire는 코드를 주석 처리하는 것이 아니다. 호출 경로, feature flag, dead config, 관련 prompt와 trace field까지 정리하고 rollback 가능한 tag 또는 commit만 남긴다.
Complexity Budget
원장은 정확도뿐 아니라 구조 비용을 관리한다.
| 예산 | 측정 단위 | 경고 조건 |
|---|---|---|
| 모델 호출 | calls / goal |
단순 명령에서 1회를 초과 |
| 재계획 | replans / workflow |
정상 progress에서 발생하거나 설정 상한 초과 |
| Context | input tokens / turn |
동일 상태·history가 중복 주입 |
| Rule | active semantic cue 수 | 근거 artifact·owner·review date가 없음 |
| Graph | steps·edges·branches | owner, input, terminal evidence 없는 node 존재 |
| Adapter | model-specific component 수 | 공통 contract보다 adapter가 빠르게 증가 |
| 운영 | failure reason coverage | fallback 문자열만 남고 원인 분류가 없음 |
예산 초과는 즉시 장애를 의미하지 않는다. 다음 모델·기능 추가 전에 구조 감축을 먼저 수행해야 한다는 신호다.
운영 주기
기능 또는 모델 변경
-> 원장 항목 추가·갱신
-> baseline artifact 고정
-> 구성요소 단위 ablation
-> keep / simplify / isolate / shadow / retire
-> 비용·회귀·rollback 결과 기록
검토 시점은 모델 교체, prompt 대규모 변경, family 정책 변경, 실기기 capability 추가, 토큰·지연 예산 초과와 반복 장애 발생 시점이다.
다음 작업
preclassifier.py의 cue를 의미군과 source line 기준으로 추출한다.- owner를 바꾸는 함수와 모델 호출 지점을 자동 계측한다.
- second-pass judge 두 개부터 Harness Ablation을 수행한다.
- 구조 validation과 semantic repair를 분리한다.
- 결과를 모델 교체 Ablation과 승격 플레이북의 release gate로 넘긴다.