◯ ─────────── ◯
L U N A R I A
◯ ─────────── ◯
판단은 Sol에, 경계가 분명한 실행은 Luna Max에.
Sol이 목표와 통합을 유지하고, 독립적으로 검증할 수 있는 작업만 Luna Max에 위임하는 Codex orchestration skill.
npx skills add https://github.com/SWARVY/Lunaria -g --all
빠른 시작 · 철학 · 구조 · 사용 조건 · 운영 효율 · 안전장치 · 명령어
메인 에이전트는 더 많은 일을 직접 하는 대신, 더 중요한 판단을 계속 소유해야 합니다.
Lunaria는 gpt-5.6-sol을 메인 에이전트로 유지하고, 범위와 성공 조건이 명확한 작업만
gpt-5.6-luna의 Max reasoning worker에 맡기는 Codex skill입니다.
Sol은 요구사항, 아키텍처, 작업 분해, 결과 검증과 최종 통합을 소유합니다. Luna Max는 코드 리뷰, 모듈 분석, 독립 구현, 테스트처럼 경계가 분명한 작업을 별도 컨텍스트에서 수행합니다.
Lunaria는 두 단계로 설치합니다.
npx skills add https://github.com/SWARVY/Lunaria -g --all설치 후 새 Codex 작업을 시작해 $lunaria가 검색되는지 확인합니다. 설치 도구가 다른
skill 디렉터리를 선택했다면 아래 명령의 경로도 그 위치에 맞춥니다.
python3 -B ~/.agents/skills/lunaria/scripts/manage_luna_worker.py checkcheck가 설치 누락이나 drift를 보고하면 먼저 변경 내용을 확인합니다.
python3 -B ~/.agents/skills/lunaria/scripts/manage_luna_worker.py plandiff가 의도와 맞을 때만 worker를 설치합니다.
python3 -B ~/.agents/skills/lunaria/scripts/manage_luna_worker.py install
python3 -B ~/.agents/skills/lunaria/scripts/manage_luna_worker.py verify
python3 -B ~/.agents/skills/lunaria/scripts/manage_luna_worker.py check설치 기본 대상은 ~/.codex/agents/luna-worker.toml입니다. 설치 후 현재 작업이 custom
agent 목록을 갱신하지 못했다면 새 Codex 작업을 시작합니다.
$lunaria를 사용해서 독립적으로 검증 가능한 작업만 Luna Max에 위임하고,
요구사항과 아키텍처 판단, 최종 검증과 통합은 Sol이 유지해줘.
Skill이 적용돼도 모든 작업을 Luna에 강제로 위임하지 않습니다. 위임 준비와 검증 비용이
Sol의 직접 처리보다 작을 때만 luna_worker를 사용합니다.
큰 작업을 하나의 스레드에서 처리하면 코드 탐색, 테스트 로그, 실패 분석과 중간 추론이 요구사항과 아키텍처 결정을 밀어낼 수 있습니다. 반대로 기준 없이 여러 에이전트를 실행하면 범위 확대, 중복 작업, 쓰기 충돌과 검증 책임의 공백이 생깁니다.
Lunaria는 역할과 책임을 먼저 고정합니다.
| Sol | Luna Max |
|---|---|
| 목표와 성공 조건 이해 | 전달받은 작업 패킷 수행 |
| 요구사항과 아키텍처 결정 | 범위가 명확한 분석·구현·테스트 |
| 작업 분해와 의존성 관리 | 허용된 파일만 편집 |
| 결과 재검증과 최종 통합 | 검증 결과와 위험 보고 |
| 외부 상태와 Git 결정 | Git 상태 변경 금지 |
이 구조의 주된 가치는 다음과 같습니다.
- 메인 컨텍스트 보호: 원시 탐색 로그 대신 검증 가능한 요약만 Sol에 반환
- 병렬 처리: 서로 독립적인 읽기·검토·테스트 작업을 동시에 수행
- 독립 검토: 별도 컨텍스트에서 구현과 가정을 다시 확인
- 책임 유지: 최종 판단과 통합 책임이 메인 에이전트에서 사라지지 않음
- 범위 통제: 파일 소유권, 제외 범위, 검증과 에스컬레이션 조건을 작업 전에 명시
사용자 요청
↓
Sol — 목표 · 요구사항 · 아키텍처 · 성공 조건
↓
독립적으로 완료하고 검증할 수 있는가?
├─ 아니오 → Sol이 직접 처리하거나 결정을 요청
└─ 예
↓
작업 패킷 작성
↓
Luna Max — 제한된 분석 · 구현 · 테스트
↓
결과 계약으로 보고
↓
Sol — 실제 diff · 파일 범위 · 테스트 재검증
↓
최종 통합과 사용자 보고
Luna의 완료 보고는 검증 전까지 주장으로 취급합니다. Sol은 실제 파일과 전체 diff를 확인하고 필수 검증을 직접 다시 실행한 뒤에만 결과를 수용합니다.
작업 패킷
Objective:
Allowed scope:
Excluded scope:
Files and ownership:
Interfaces:
Inputs and known decisions:
Expected duration and stop condition:
Validation tier:
Orchestration owner and mode:
Active worker and wait budget:
Stage boundary and review trigger:
Deliverable:
Required validation:
Escalate when:
결과 계약
Status: complete | blocked | needs_decision
Summary:
Files changed:
Validation run and results:
Unresolved risks:
Decision requested from Sol:
- 특정 파일이나 모듈의 코드 리뷰
- 특정 모듈의 구조와 동작 분석
- 파일 소유권이 분리된 독립 기능 구현
- 테스트 작성, 실패 원인 조사와 검증
- 서로 의존하지 않는 읽기 전용 조사
- 여러 결과를 Sol이 최종 비교·통합해야 하는 작업
읽기 전용 작업은 병렬 실행할 수 있습니다. 쓰기 작업은 논리적인 파일 소유권이 겹치지 않고 공유 lockfile, 생성물, 마이그레이션, 포맷 출력이나 Git 상태 변경이 없을 때만 병렬로 실행합니다.
- 요구사항이나 성공 조건을 결정해야 하는 작업
- 아키텍처와 공용 인터페이스를 선택해야 하는 작업
- 동일 파일, lockfile, 생성물이나 마이그레이션을 함께 수정하는 작업
- 외부 부수 효과나 최종 승인이 필요한 작업
- 의존성이 강해 순차적으로 처리해야 하는 작업
- 작업 패킷과 재검증 비용이 더 큰 작은 단일 단계 수정
Luna는 목표를 확장하거나 불명확한 아키텍처를 임의로 결정하지 않습니다. 경계를 넘는
판단이 필요하면 needs_decision으로 Sol에 반환합니다.
다른 오케스트레이션 스킬과 함께 사용할 때 각 스킬의 구현자·리뷰어 루프를 더하지 않습니다. 현재 단계의 작업 분배, 리뷰, 재시도와 대기는 실행 오케스트레이터 하나가 소유합니다.
품질 게이트 모드에서는 Lunaria가 실행 예산을 소유합니다. 다른 스킬은 계획과 기법만 사용하고, 자체 구현자·작업별 리뷰어·수정/재리뷰 루프는 실행하지 않습니다. Sol 또는 경계가 명확한 Luna가 구현하고, Sol이 결과를 수용한 뒤 단계 경계에서 독립 리뷰어 1명을 사용합니다. 이때 단계는 개별 task가 아니라 사용자 가치나 milestone 하나를 완료해 하나의 통합 검증을 실행하는 작업 묶음입니다. 첫 위임 전에 단계 경계와 리뷰 시작 조건을 고정합니다. 외부 workflow의 final whole-branch reviewer가 필요하면 Lunaria의 단계 리뷰어 1명으로 간주하고 별도로 추가하지 않습니다.
다른 workflow의 전체 작업별 루프를 그대로 실행해야 한다면 Lunaria 조합 모드를 사용하지 않습니다. 두 모드를 동시에 적용하지 않으며, 어느 쪽을 적용할지 불명확하면 첫 에이전트를 만들기 전에 결정합니다.
기본 운영 예산은 활성 Luna 2명입니다. 플랫폼에 세 번째 슬롯이 있으면 구현 작업으로 채우지 않고 리뷰어용 슬롯으로 남깁니다. 독립 읽기·분석·QA는 이 범위에서 병렬화할 수 있지만 공유 파일과 순차 상태 전환은 직렬로 처리합니다.
Sol이 직접 진행할 일이 없을 때만 실행 중인 worker를 묶어서 기다립니다. 상태 변화 없이 개별 worker를 반복 polling하지 않으며, 수용과 동일 목표의 보정이 끝난 worker는 닫아 슬롯을 반환합니다.
예상 5분 미만이면서 기계적인 단일 단계인 작업은 Sol이 직접 처리합니다. 시간이나 파일 수만으로 복잡도를 판단하지 않으며, 깊은 분석과 독립 검증의 가치가 준비·대기·재검증 비용보다 클 때만 Luna에 위임합니다.
한 구현 단계의 기본 예산은 구현자 1명과 리뷰어 1명입니다. Minor 지적은 Sol이 직접 수정·검증하고, Important 또는 Critical 문제가 남을 때만 재리뷰를 한 번 요청합니다. 완료된 워커에 대한 후속 지시는 동일 목표의 보정 1회까지만 허용합니다. 목표나 파일 소유권이 바뀌면 새 작업 패킷을 만들거나 Sol이 직접 처리합니다.
| 단계 | 검증 |
|---|---|
| 워커 | 작업 범위의 좁은 테스트 |
| Sol 수용 | 실제 diff·소유권 확인과 좁은 테스트 재실행 |
| 단계 통합 | 전체 test, typecheck, build를 한 번 실행 |
| 최종 통합 | commit, PR, 배포 workflow가 요구하는 최신 검증 |
새 변경이나 실패 수정 없이 동일한 전체 검증을 반복하지 않습니다. 큰 통합이나 PR이 끝나고 다음 목표가 독립적이면 결정 문서를 인계점으로 삼아 새 Codex 작업을 시작하는 것을 권장합니다.
단계가 끝나면 Sol은 위임·완료·취소 수, worker 시간, 후속 지시·중단·재시도, 실행한 검증을
오케스트레이션 요약으로 보고합니다. 토큰과 메인 턴 수는 공개 metadata에서 확인될 때만
기록하고, 확인할 수 없으면 unavailable로 남깁니다. 대기 비용은 Peak active workers와
Wait calls / unchanged timeouts로 함께 기록합니다.
- 메인 모델:
gpt-5.6-sol - worker 역할:
luna_worker - worker 모델:
gpt-5.6-luna - reasoning:
model_reasoning_effort = "max"
모델이나 역할이 확인되지 않으면 값을 추정하지 않습니다. 다른 worker로 조용히 대체하지도 않습니다.
check는 현재 Codex CLI 버전, multi_agent 기능, worker 설치 여부와 관리 템플릿의
일치 상태를 읽기 전용으로 검사합니다. exit code가 0일 때만 위임합니다.
- 하나의 명시적인 목표와 산출물만 허용
- 허용·제외 범위와 파일 소유권을 사전 선언
- 겹치는 쓰기는 직렬화
- 다른 작업자나 사용자의 변경을 되돌리지 않음
- Luna가 다른 에이전트를 생성하지 않음
Luna는 일반 파일 편집은 할 수 있지만 working tree, index, refs, branch, tag, stash, worktree를 변경하는 Git 명령은 실행할 수 없습니다. commit, add, reset, merge, rebase, stash, clean, cherry-pick, revert, tag, switch, checkout, push와 worktree 작업이 모두 금지됩니다.
관리 스크립트는 ~/.codex/config.toml을 수정하지 않습니다. 기존 worker를 기본적으로
덮어쓰지 않으며, 교체가 명시된 경우에도 기존 파일의 백업을 만든 뒤 원자적으로
설치합니다.
| 명령 | 상태 변경 | 역할 |
|---|---|---|
manage_luna_worker.py check |
없음 | CLI, multi_agent, 설치 상태와 template drift 확인 |
manage_luna_worker.py plan |
없음 | 현재 대상과 관리 template의 unified diff 출력 |
manage_luna_worker.py install |
있음 | 기본 target에 worker 설치, 기존 파일 덮어쓰기 거부 |
manage_luna_worker.py verify |
없음 | 설치 후 환경과 worker 설정 유효성 검증 |
기본 경로가 아닌 별도 설치 위치를 사용한다면 모든 명령에 --template과 --target을
명시할 수 있습니다. 기존 worker 교체는 diff를 검토하고 백업 정책을 이해한 경우에만
install --replace를 사용합니다.
Lunaria는 토큰 절약을 보장하는 도구가 아닙니다. 각 worker가 별도 컨텍스트에서 모델과 도구를 사용하므로 전체 토큰은 늘어날 수 있습니다. 목표는 총 토큰 최소화가 아니라 Sol의 메인 컨텍스트를 보호하고, 독립 작업의 완료 시간과 검증 품질을 개선하는 것입니다.
권장 지표는 다음 순서입니다.
- Sol 메인 스레드 input tokens와 context 압축 횟수
- 작업 완료 시간
- 첫 검증 성공률과 재작업 횟수
- 리뷰에서 발견한 결함과 회귀 수
- Sol과 모든 Luna worker를 합친 전체 토큰
짧거나 강하게 결합된 작업에서 작업당 토큰이 증가한다면 위임하지 않는 것이 정상입니다. 측정 때문에 내부 세션이나 rollout을 읽지 않으며 공개 metadata가 없는 값은 추정하지 않습니다.
| 경로 | 역할 |
|---|---|
SKILL.md |
Sol이 따르는 오케스트레이션 규칙 |
agents/openai.yaml |
Codex UI metadata와 기본 prompt |
assets/luna-worker.toml |
고정된 Luna Max leaf worker template |
scripts/manage_luna_worker.py |
worker 점검, diff, 설치와 검증 도구 |
tests/ |
설정·설치 안전성과 skill 계약 회귀 테스트 |
개발 검증:
python3 -m unittest discover -s tests -v
Sol은 방향을 잃지 않고, Luna는 경계를 넘지 않습니다.
좋은 오케스트레이션은 역할보다 책임을 먼저 나눕니다.