에이전트 아키텍처
에이전트는 Lumie 라우팅 시스템 뒤에 있는 역할 범위 어댑터입니다. 디스패처 계층도, 주 실행 루프의 대체물도, 승인 메커니즘도 아닙니다. 주 에이전트는 여전히 Dispatch Lock, 루프 상태, 범위 제어, 최종 보고를 소유합니다.
역할 모델
| 역할 | 책임 | 경계 |
|---|---|---|
| 주 에이전트 | 작업을 정리하고, 소유 영역을 확인하고, 승인된 루프를 적용하고, 증거를 통합하고, 결과를 보고합니다 | Plan Mode, hook, check, human-owner 적용 범위를 우회하지 않습니다 |
| 전문 작성자 | 명시된 저장소, 모듈, 파일 범위 안에서 제한된 편집을 수행합니다 | 관련 없는 파일을 소유하거나 사용자 변경을 되돌리지 않습니다 |
| 리뷰어 에이전트 | diff 또는 문서 영역을 읽고 심각도순 지적사항을 반환합니다 | 증거를 생성하며 작업을 승인하지 않습니다 |
| 체커 에이전트 | 정책, 위험, 보안, 계약, 일관성 증거를 생성합니다 | test, hook, human-owner review를 대체할 수 없습니다 |
| Human owner | 변경된 영역의 필수 리뷰 소유권을 가집니다 | 필수 owner coverage는 에이전트 증거로 충족되지 않습니다 |
이 모델은 에이전트를 유용하게 유지하면서도 검토 불가능한 워크플로 하네스로 만들지 않습니다.
라우팅 계층
에이전트 선택은 세 가지 라우팅 계층을 통과합니다.
.codex/AGENTS.md가 진입 게이트, 소유 영역, Dispatch Lock, 전문 역할 필요 여부를 정합니다..codex/routing/repos/*.md가 제품 저장소 작업을 작성자 지침, 검증자 지침, 저장소별 규칙으로 매핑합니다..codex/routing/review-matrix.md가 실제 diff를 필수 human owner, 리뷰어 에이전트, 체커 에이전트, Verify 단계 증거로 매핑합니다.
이 라우팅의 출력은 증거 계획입니다. 검증이나 소유권을 건너뛸 권한을 주지 않습니다.
에이전트 계열
| 계열 | 목적 | 예시 |
|---|---|---|
| 작성자와 스캐폴더 | 라우팅된 쓰기 범위 안에서 제한된 편집 수행 | frontend-scaffolder, backend-scaffolder, worker-scaffolder, lumie-doc-author, codex-md-author |
| 리뷰어 | diff 또는 문서 영역을 읽고 지적사항 반환 | frontend-reviewer, backend-reviewer, worker-reviewer, lumie-doc-reviewer, lumie-doc-i18n-reviewer |
| 체커와 tripwire | 정책, 위험, 보안, 계약 증거 생성 | security-tripwire, anti-pattern-tripwire, api-contract-checker, lumie-risk-scorer |
| 검증 전문 역할 | 저장소 영역에 맞는 영향을 받은 검사 실행 또는 요약 | frontend-test-orchestrator, backend-test-orchestrator, worker-test-orchestrator, performance monitor |
| 탐색자와 도메인 전문 역할 | 편집 없이 탐색, 용어, 아키텍처 질문에 답변 | codebase-explorer, infra-explorer, lumie-domain-expert, lumie-architect |
| 큐레이터 | 규칙, 참고 문서, 학습 산출물 유지 | reference-curator, lumie-rulebook-curator, lumie-rulebook-pruner, post-mortem-author |
쓰기 가능한 에이전트에는 명시적인 소유 단위가 필요합니다. 읽기 전용 에이전트는
심각도순 지적사항이나 명확한 No findings 결과를 반환해야 합니다. 두 종류 모두
관련 없는 변경을 되돌리지 말고 기존 사용자 변경과 함께 작업해야 합니다.
권한이 아니라 증거
중요한 경계는 에이전트 출력이 권한이 아니라 증거라는 점입니다. 리뷰어나 체커는
지적사항을 만들거나, 지적사항 없음으로 확인하거나, 전문 신호를 제공할 수
있습니다. 그러나 필수 human-owner:* 행을 대체하거나, 커밋을 승인하거나, hook,
lint, test, checker 게이트를 우회할 수 없습니다.
그래서 Lumie는 dispatcher agent와 워크스페이스 워크플로 하네스를 피합니다. 오케스트레이션은 라우팅된 loop에 두고, 전문 역할 동작은 작고 검토 가능하게 유지하며, 문서를 읽지 않아도 반드시 지켜져야 하는 규칙은 Tier 0 메커니즘에 둡니다.
피해야 할 패턴
| 패턴 | 거부 이유 |
|---|---|
| Dispatcher agent | 라우팅 결정을 또 다른 프롬프트 계층 뒤에 숨겨 소유권 감사를 어렵게 만듭니다 |
| 에이전트 난립 | 겹치는 전문 역할이 너무 많으면 리뷰 라우팅이 모호해집니다 |
| Slash-command harness | 워크플로 제어를 관찰된 loop state가 아니라 호출 의식으로 만듭니다 |
| 리뷰어를 승인자로 취급 | 증거와 권한을 혼동해 human-owner coverage를 우회할 수 있습니다 |
| 문서만 있는 가드레일 | 중요한 규칙이 prose를 읽는 사람에게만 의존하면 실패합니다 |