# REFLEX v2 시스템 설계

REFLEX는 반복 경험을 좁은 행동 경로로 전환하고, 작업 환경에 맞게 지식·스킬·서브에이전트의 경계와 연결을 진화시킨다. 각 판단 단계에서 적용 조건을 만족하는 경로를 찾아 실행하고, 결과를 검증해 다음 경로 선택에 반영한다.

## 네 계층

| 계층 | 역할 | 입력 | 출력 |
| --- | --- | --- | --- |
| L3 숙고 | 새로운 목표와 전략을 해석 | 목표, 관측, 제약, 기존 스킬 | 계획, 행동 제안, 성공 조건 |
| L2 숙련 | 익숙한 절차에 문맥을 적용 | 관측, 검색한 절차, 예시 | 절차 선택, 구조화된 인자 |
| L1 결정 | 제한된 선택지에서 행동을 선택 | 구조화된 상태, 가능한 행동 | 선택값, 이유 코드, 이관 여부 |
| L0 실행 | 명시된 조건과 절차를 수행 | 검증된 인자, 도구 계약 | 결과, 검증값, 오류 코드 |

하나의 작업에서도 여러 계층을 조합한다. 새로운 문서의 의미는 L3가 해석하고, 해시 계산과 승인된 파일 복사는 L0가 처리할 수 있다.

## 실행 경로

```text
요청과 환경 상태
    ↓
입력 정규화 → 구조 버전 선택 → 활성 모듈·연결 선택
    ↓
모듈 내부 스킬 검색 → 적용 조건 검사
    ↓
판단 처리기 L0 / L1 / L2 / L3
    ↓
행동 제안 → 권한·예산 검사 → 공통 실행기
    ↓
사후 조건 검증 → 결과 반환
    ↓
경험 원장에 관측·판단·행동·결과 저장
```

라우터는 입력 스키마, 작업군, 환경 버전, 스킬의 검증 상태를 확인한다. 적용 가능한 경로 가운데 품질 기준과 예산을 만족하는 경로를 선택한다. 불확실한 판단은 상위 계층으로 이관하며, 정보 부족과 권한 부족은 요청 또는 보류 상태로 반환한다.

모든 판단 처리기는 같은 실행기를 사용한다. 실행기는 허용된 도구·인자·효과를 확인하고, 재시도와 중복 실행을 통제한다. 결과 검증은 문서 분류의 정답, 실제 목적지, 파일 내용 해시처럼 관측 가능한 기준으로 수행한다.

## 학습 경로

```text
경험 원장 → 작업군별 사례·실패 묶음
    ↓
고정 조건과 변동 인자 추출
    ↓
L2 예시·템플릿 / L1 정책 / L0 코드 후보
    ↓
독립 평가 → 과거 입력 재생 → 그림자 실행
    ↓
제한 적용 → 활성 스킬 등록
    ↓
표본 감사와 환경 감시 → 유지 / 격리 / 재검증
```

학습은 실행과 별도의 루프로 진행한다. 실행 중인 에피소드는 스킬 버전을 고정하고, 평가를 통과한 새 버전을 다음 에피소드부터 사용한다. 전환 단계는 작업 성격에 따라 선택한다. 명확한 알고리즘은 L3에서 L0로 직접 전환할 수 있다.

## 경험의 데이터 계약

| 항목 | 저장할 내용 |
| --- | --- |
| 식별과 연결 | 에피소드 ID, 상위 작업 ID, 시각, 구조·모듈·연결 ID |
| 입력 | 목표, 관측, 원본 참조, 작업군, 환경 버전 |
| 판단 | 선택한 계층, 스킬·모델 버전, 인자, 선택 근거 |
| 행동 | 도구, 허용 효과, 실행 인자, 멱등성 키 |
| 결과 | 관측 결과, 검증기 버전, 성공·실패·보류 상태 |
| 피드백 | 독립 정답, 사용자 수정, 오류 유형 |
| 자원 | 호출 비용, 지연, 재시도, 검증·복구 비용 |

실패를 입력 해석 오류, 정책 오류, 실행 오류, 검증 오류로 나누어 원인을 추적한다. 성공 라벨은 관측 결과와 독립 정답에서 얻는다.

## 스킬의 데이터 계약

| 항목 | 의미 |
| --- | --- |
| 이름과 버전 | 스킬 ID, 버전, 책임자, 원본 경험 참조 |
| 적용 조건 | 발동 신호, 입력 계약, 작업군, 환경 버전, 유효 기간 |
| 판단과 행동 | 담당 계층, 선택지, 인자 스키마, 실행 절차 |
| 검증 근거 | 평가 세트, 반례, 품질 하한, 사후 조건 |
| 실행 경계 | 권한, 예산, 재시도 한도, 멱등성 조건 |
| 복귀 경로 | 거절 조건, 상위 이관 대상, 이전 버전 |
| 상태 | 후보, 검증 중, 제한 적용, 활성, 격리 |

## 국소 적응

중복 이벤트 억제, 제한된 백오프, 혼잡에 따른 처리율 조절은 L0에서 작동한다. 제어기는 지정된 범위 안에서 대기시간과 처리량을 조절한다. 의미 판단 정책과 권한은 해당 스킬의 계약을 따른다.

## 초기 구현 단위

첫 구현은 입력 어댑터, 스킬 색인, 네 계층 처리기, 공통 실행기, 검증기, 경험 원장, 오프라인 후보 생성기로 나눈다. 경험은 SQLite 또는 JSONL로, 스킬은 버전 관리되는 파일로 저장한다. 모델은 공통 어댑터 뒤에 두어 교체와 비교 실험을 가능하게 한다.

관련 연구와 시각적 설명은 [컨셉 문서](../index.html#sources)에서 확인할 수 있다.


## 두 개의 적응 축과 세 시간척도

판단 계층 L3/L2/L1/L0는 모듈 안에서 선택한다. 문서·이미지·일정 모듈은 각각 필요한 계층을 가질 수 있다. 서로 다른 계층을 서로 다른 서브에이전트로 고정하지 않는다.

| 시간척도 | 변경 대상 | 지속되는 결과 |
| --- | --- | --- |
| 매 요청의 활성화 | 현재 입력에서 열 연결과 호출할 모듈 | 에피소드의 경로 기록 |
| 경험 기반 학습 | 지식, 스킬, 예시, 제한 정책, 실행 코드 | 스킬 버전 |
| 세대별 구조 진화 | 모듈 경계, 지식 범위, 역할, 연결 조건 | 구조 버전과 부모 계보 |

구조 진화는 후보 변형·다중 작업 평가·선별·계승으로 구현한다. 초기에는 모델 가중치를 고정하고 그래프와 접근 범위만 탐색한다. 현재 요청에서 활성화가 달라지는 것과, 다음 세대로 구조를 바꾸는 것을 구분해 기록한다.

공통 라우터는 모듈의 역할·입출력 계약·검증된 적용 범위 목록을 검색한다. 각 영역의 원본 지식은 공유하지 않는다. 알맞은 협업 경로가 없는 요청은 L3 통합 검토로 보내고, 구조 설계자가 추가·분리 후보를 오프라인에서 제안한다. 별도의 평가자가 후보를 검증한 뒤 다음 요청부터 적용한다.

## 구조의 데이터 계약

구조 G는 모듈 V, 허용 연결 E, 지식 접근 범위 K, 메시지 계약 C, 연결 발동 조건 T, 복귀 경로 F로 구성한다. 실행·검증의 공통 기반도 G의 필수 의존성으로 명시한다.

```yaml
structure_id: office-bridge-v2
parent_id: office-dense-v1
modules:
  document:
    knowledge_namespace: docs-only
    skills: [classify-receipt-v3]
    allowed_tools: [local-copy]
    runtime: skill-module
  image:
    knowledge_namespace: images-only
    skills: [extract-receipt-v2]
    allowed_tools: [local-ocr]
    runtime: independent-agent
edges:
  - from: image
    to: document
    trigger: goal.requires_image_and_classification
    message_schema: receipt-fields-v1
    fields: [document_type, amount, source_ref]
    max_messages: 2
fallback: integration-review
verification: receipt-result-v1
lifecycle: candidate
```

이 계약의 내용과 형식은 구현 시 스키마로 검증한다. 구조 탐색기가 출력한 코드는 격리된 평가 환경에서만 실행한다. 스킬 버전과 지식 색인 버전을 구조에 함께 고정해 재현성을 확보한다.

## 격리의 집행

- 지식: 저장소와 검색 색인을 네임스페이스로 분리하고, 검색 계층에서 허용 범위를 적용한다. 다른 모듈의 전체 메모리나 대화를 자동 첨부하지 않는다.
- 스킬: 허용된 호출 목록과 의존성 목록을 검사한다. 반환은 정의된 메시지 스키마와 필드 목록을 따른다.
- 서브에이전트: 별도 컨텍스트·메모리·자원 예산·작업 종료 조건을 갖는다. 필요하면 실행 프로세스와 도구 자격도 분리한다.
- 중개기: 목적·출처·필수 필드를 검증하고 승인된 연결만 열어준다. 다른 모듈의 원본 자료가 꼭 필요한 경우 명시된 요청과 일회성 접근 범위를 기록한다.
- 실행·검증: 도구 권한과 외부 효과는 별도 계약으로 집행한다. 구조 변형은 기존 권한을 확대할 수 없다. 정답·행동 결과의 독립 검증 경로와 오류 관측 경로는 제거할 수 없다.

격리는 프롬프트 문구만으로 구현하지 않는다. 저장소·검색 계층·호출 중개기·실행기의 접근 제어가 경계를 유지한다. 역할의 목표와 수명주기가 같고 짧은 결정만 필요하면 함수·스킬 모듈을 우선 사용한다.

## 구조 변형 연산

| 연산 | 발동 근거 | 확인할 위험 |
| --- | --- | --- |
| 모듈 분할 | 서로 다른 작업군의 규칙 간섭과 목표 충돌 | 분할 후 복합 작업에 필요한 지식 단절 |
| 모듈 통합 | 역할 중복과 불필요한 왕복 | 컨텍스트 확대와 오류 전파 |
| 지식 범위 축소 | 자주 검색되지만 판단에 기여하지 않는 자료 | 드문 예외를 위한 근거 제거 |
| 연결 삭제 | 반사실 제거 실험에서 품질 유지, 비용 감소 | 복구·희귀 작업·새 조합의 실패 |
| 연결 추가·조건화 | 분리된 하위 목표의 통합 필요 | 권한·스키마 위반, 순환 호출 |
| 전문 주체 분화·재조합 | 독립 목표와 반복적인 작업 패턴 | 조율·유지 비용, 동일한 오류의 증폭 |

연결 기여는 제거·복원 실험과 독립 결과 검증으로 추정한다. 드문 호출의 삭제 여부는 사용 빈도만으로 정하지 않는다. 변형 하나씩의 실험과 결합 실험을 구분한다.

## 변형·선별·계승 루프

1. 부모 구조와 실패·비용 기록을 고정한다.
2. 허용 연산으로 후보를 만들고 구조·권한 계약을 정적으로 검사한다.
3. 후보 생성용 사례와 분리된 평가 작업에서 재생한다. 구조 선별용 검증 세트와 마지막 보고용 테스트 세트도 분리한다.
4. 새 시간대, 희귀 유형, 이전에 없던 하위 목표 조합을 포함해 정답과 실제 결과를 검증한다.
5. 작업군별 품질 하한·권한·복구 가능성 기준 미달 후보를 제외한다.
6. 남은 후보의 총비용·지연·간섭·변화 대응을 비교하고 장점이 다른 후보를 보관한다.
7. 제한 적용과 감사를 통과한 후보를 다음 구조 버전으로 등록한다. 부모·변형 연산·평가 자료·결과를 함께 보존한다.

총비용은 추론·라우팅·통신·검증·복구에 구조 탐색 및 유지 비용의 배분을 더한다. 구조가 더 희소해도 품질 하한을 통과하지 못하면 채택하지 않는다. 후보를 반복 선별한 평가 세트만으로 최종 성능을 보고하지 않는다.

## 복귀와 다양성

작업군별 후보 보관소에는 독립 업무 구조, 복합 업무 구조 등 서로 다른 비용·품질 장점을 가진 구조를 둔다. 라우터는 현재 환경에서 검증된 구조를 선택하고 한 에피소드 동안 버전을 고정한다. 모르는 작업군은 통합 검토 경로로 이관한다.

표본 감사와 변화 탐지가 품질 하락을 발견하면 해당 구조를 격리한다. 구조·스킬·지식 색인 버전을 일관된 묶음으로 이전 검증 버전에 되돌린다. 진행 중인 작업은 고정된 버전을 끝까지 쓰거나 취소·재시작 계약에 따라 처리한다.

## 브라우저 실험의 범위

A는 경험 단계와 입력 조건을 바꾸어 계층 선택·예시 분류·보류 기록을 확인한다. 새로운 서식과 환경 변경은 검토 큐로 보내며 모델 추론을 흉내 내 성공으로 기록하지 않는다.

B는 서로 다른 모듈이 처리하는 고정된 세 단일 작업과 한 복합 작업을 실행한다. 복합 작업은 이미지 모듈의 필드를 문서 모듈에 전달할 연결이 있어야 정답에 도달한다. 후보는 전부 공유(영역 간 3개 연결), 완전 격리(0개), 조건부 연결(1개)이다. 연결 수는 영역 쌍 기준이며 메시지는 이미지→문서 방향이다.

복합 환경에서 전부 공유는 4/4, 완전 격리는 3/4, 조건부 연결은 4/4를 통과한다. 독립 환경에서는 모두 3/3을 통과하며 완전 격리가 가장 비용이 낮다. 비용은 저장된 연결 수와 불필요하게 활성화된 영역 수의 합이다. 실제 모델·파일 도구·영구 경험 저장소·후보 자동 생성은 아직 구현 대상이다.

연구의 결과와 적용 연결은 [연구 노트](research.md)에 정리한다.