sol-advisor 딥다이브
— 설계·시공·검사를 강제로 분리한 Codex 오케스트레이션

1한 줄 정체

sol-advisor는 "OpenAI Codex에게 코딩을 시킬 때, 설계하는 세션 · 구현하는 세션 · 검사하는 세션을 강제로 분리하고, 각 세션이 쓸 모델과 추론 강도를 파일에 못 박아, 아무도 몰래 대충 하지 못하게 만드는 워크플로 플러그인"이다. 한마디로 에이전트판 "역할 분리 + 준공검사" 제도다. 코드를 짜는 도구가 아니라, 코드를 짜게 시키는 방식을 규율로 정한 것이다.

사용자가 "이 기능 만들어 줘"라고 하면 sol-advisor 규율 아래서 벌어지는 일을 압축하면 이렇다:

여기서 핵심은 ①의 사전점검과 ⑤의 신선한 검사다. ①은 "일을 시키기 전에 역할이 위조·변조되지 않았는지"를 해시로 확인하고, ⑤는 "짓는 동안 오간 대화에 물들지 않은 눈"으로 결과만 본다. 이 둘이 sol-advisor를 단순 "서브에이전트 띄우기"와 갈라놓는 지점이다.

2왜 주목받는가 — "역할을 못 박는다"는 각도

첫째, 지금 가장 뜨거운 주제인 "에이전트 오케스트레이션"의 실전 규율이다. TrendShift 데일리 1위 토픽이 AI agent일 만큼, "에이전트 여러 개를 어떻게 잘 부릴까"가 최대 관심사다. Codex가 최근 커스텀 에이전트·플러그인·네이티브 서브에이전트를 갖추면서, 그 새 기능을 규율 있게 쓰는 법을 보여 주는 참조 구현으로 딱 맞물렸다.

둘째, "몰래 성능을 낮추는" 실전 고통을 정면으로 때린다. AI 코딩 도구를 오래 쓴 사람은 안다 — 에이전트가 슬그머니 더 싼 모델로 갈아타거나 추론 강도를 낮춰, 겉으론 일하는 척하며 품질이 떨어지는 일이 잦다. sol-advisor는 모델·강도를 커스텀 에이전트 TOML에 못 박고(pin), "호출할 때 모델을 지정하지 말라"고 규정한다. 조용한 대체(silent fallback)를 금지한다는 이 원칙이 실무자의 공감을 얻는다.

셋째, 정직한 설계 서술이 신뢰를 준다. 이 레포는 자기 한계를 숨기지 않는다. 문서 곳곳에 "Sol이 Sol을 검토하는 것은 맥락이 신선할 뿐, 모델 계열이 독립적인 것은 아니다"라고 못 박는다. 즉 "완벽한 교차검증"이라 과장하지 않고, "같은 모델 계열이라 잡지 못하는 것도 있다"는 잔여 위험을 명시한다. 과대광고가 넘치는 에이전트 판에서 이런 절제가 오히려 눈에 띈다.

넷째, 저자의 배포력이다. 저자 Daniel McAteer(DannyMac180)는 Attention Heads라는 뉴스레터에서 "Agentic Engineering Field Notes"(에이전트 엔지니어링 현장 노트) 시리즈를 연재한다. 방법론을 글로 설파하는 저자가 그 방법론을 코드로 구현해 내놓은 것이라, 글 독자층이 곧 레포의 초기 별점으로 이어졌다.

3기술 스택 전체 지도

sol-advisor에는 웹서버도, 빌드 도구도, 무거운 런타임도 없다. 이 프로젝트의 "스택"은 Codex라는 숙주 플랫폼 위에 얹히는 설정 파일과 이식성 높은 셸 스크립트가 전부다. 바로 이 미니멀함이 요점이다 — 규율은 거대한 코드가 아니라 정확한 몇 개의 파일로 강제된다.

4아키텍처 심화 — 역할·핀·설치·관찰

축 1 — 세 역할과 단방향 위임 (누가 무엇을 하는가)

사용자에겐 하나의 Codex 세션으로 보이지만, sol-advisor는 일을 세 역할로 쪼갠다. 위임은 위에서 아래로만 흐르고, 각 역할은 자기 소관만 한다.

규칙이 엄격하다. 구현자는 자기가 소유한 파일만 건드리고, 리뷰어는 어떤 파일도 수정하지 못한다. 그리고 리뷰어가 스스로 버그를 고치는 것은 금지다 — 고치면 그 diff는 "검토받지 않은 변경"이 되므로, 반드시 구현 lane으로 되돌려 고친 뒤 새 신선한 리뷰를 다시 받는다. "검토"와 "수정"을 절대 한 손에 쥐지 않게 한 것이다.

축 2 — 역할 핀(role pinning): 몰래 못 낮추게 하는 법

핵심 안전장치는 모델과 추론 강도를 스폰(호출) 시점이 아니라 역할 파일에 박는다는 것이다. 주 세션은 agent_type 이름만 대고, 모델·강도는 절대 지정하지 않는다. 값은 TOML이 소유한다:

# agents/sol-advisor-terra-implementer.toml — 유일한 구현 lane
name = "sol_advisor_terra_implementer"
model = "gpt-5.6-terra"
model_reasoning_effort = "high"          # ← 여기 박힌 값이 진실

# agents/sol-advisor-sol-reviewer.toml — 신선한 read-only 리뷰
name = "sol_advisor_sol_reviewer"
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
sandbox_mode = "read-only"          # ← 검사관에겐 열람권만

그런데 "박아 뒀다"는 선언만으론 부족하다. sol-advisor는 실제로 그 값으로 돌고 있는지를 스폰 후에 확인한다(SKILL.md 사전점검 3단계). 확인 순서가 영리하다:

• 공개 메타데이터 우선: 네이티브 스폰/상세 정보가 선택된 역할·모델·강도를 노출하면 그걸 먼저 본다.
• 부족하면 로컬 인스펙터: 공개 정보에 모델/강도가 빠졌고 로컬 rollout 로그에 접근 가능하면, 뒤에 나올 inspect-agent-runtime.sh로 보충한다.
• 둘 다 있으면 반드시 일치해야: 공개값과 로컬값이 어긋나면 그 lane을 멈춘다. 허용값은 구현 Terra/High, 검토 Sol/High뿐.

축 3 — 바이트 정확 설치기(install-agents.sh): 사용자 파일을 절대 덮지 않는다

역할 파일은 사용자 소유다(각자 자기 Codex 설정 폴더에 둔다). 플러그인을 설치·업데이트해도 자동 등록되지 않으므로, 별도 설치 스크립트가 이걸 안전하게 깐다. 이 스크립트가 이 레포에서 가장 정교한 엔지니어링이다. 목적지 파일을 SHA-256으로 여섯 상태로 분류한다:

이 분류가 왜 중요한가? "설치"라는 단순 작업조차 사용자가 손수 고친 파일을 말없이 날려버릴 위험이 있기 때문이다. 스크립트는 current·legacy·missing만 진행하고, conflict·unsafe는 건드리지 않고 멈춘 뒤 사용자에게 경로를 알려 준다. 설치 자체도 원자적으로 한다:

# 임시 파일에 먼저 복사 → 하드링크로 목적지에 "원자적" 배치
staged=$(mktemp "$target_dir/.sol-advisor-agent.XXXXXX")
cp "$template" "$staged"
ln "$staged" "$destination"   # 목적지가 이미 있으면 실패 → 덮어쓰기 사고 원천 차단
rm -f "$staged"
# 설치 직전에 상태를 한 번 더 확인(same_state)해 경쟁 조건(TOCTOU) 방어

여기에 버전 마이그레이션까지 얹혀 있다. v0.2.0의 Terra·Luna 파일의 SHA-256 지문이 스크립트에 불변 상수로 하드코딩돼 있어, 구버전 파일을 정확히 알아보고 → 구 Terra는 새 템플릿으로 교체, 폐기된 Luna는 삭제한다. 단, 사용자가 조금이라도 손댄 구버전 파일이면(지문 불일치) 건드리지 않는다. "정확히 아는 것만 자동 처리, 조금이라도 다르면 사람에게"라는 태도가 일관된다.

축 4 — 안전한 런타임 관찰(inspect-agent-runtime.sh): 필요한 것만 내보낸다

축 2에서 "실제 모델·강도를 확인한다"고 했다. 그 확인을 로컬 로그에서 할 때 쓰는 도구가 이것인데, 최소 공개(least disclosure) 원칙으로 설계됐다. 로그 파일(rollout JSONL)에는 프롬프트·토큰 등 민감정보가 가득한데, 이 스크립트는 라우팅 관련 허용목록 필드만 뽑아 새 JSON으로 만든다:

# 1) 입력부터 엄격 검증: thread_id는 소문자 UUID여야만
grep -Eq '^[0-9a-f]{8}-[0-9a-f]{4}-...-[0-9a-f]{12}$'

# 2) 파일 내용은 "정확히 1개"가 매칭될 때까지 열지 않는다
find "$sessions_dir" -type f -name "rollout-*-$thread_id.jsonl"
#    0개 → 에러, 2개 이상 → 에러 (모호하면 정지)

# 3) jq로 "허용된 필드만" 새 객체를 구성 (원본을 그대로 뱉지 않음)
jq ... '{ thread_id, agent_role, model, effort,
       sandbox_policy_type, permission_profile_type, cwd }'
#    model/effort가 없거나 서로 충돌하면 추론하지 않고 에러

포인트는 "원본을 필터링"이 아니라 "허용된 것만 새로 구성"이라는 점이다. 필터링은 빠뜨린 민감정보가 새어나갈 수 있지만, 허용목록 구성은 명시적으로 나열한 필드 외에는 태생적으로 나올 수 없다. 검증 스크립트(verify.sh)는 실제로 로그에 DO_NOT_LEAK_PROMPT를 심어 두고, 인스펙터 출력에 그게 안 나오는지까지 테스트한다.

축 4-b — 5부 구현 명세: 위임의 계약서

Sol이 Terra에게 일을 넘길 때는 반드시 다섯 부분을 모두 채운 명세를 준다(role-contracts.md). 이 계약 양식 자체가 재사용 가치가 크다 — 어떤 에이전트에게든 일을 시킬 때 쓸 수 있다:

이 계약의 철학은 "완료했다는 말은 믿지 않는다, 증거를 본다"이다. 구현자는 "다 됐어요"가 아니라 실행한 명령과 그 실제 출력을 첨부해야 하고, 주 세션은 그 diff를 직접 열어 검증 명령을 스스로 재실행한다. 워커의 보고는 "주장(claim)"일 뿐, 검증 전엔 사실이 아니다.

축 4-c — 요청한 격리 vs 관찰된 격리

리뷰어 TOML은 sandbox_mode = "read-only"를 요청한다. 하지만 sol-advisor는 "요청했으니 됐다"고 넘어가지 않는다. 숙주(host) 환경이 그 요청을 넓혀버릴 수 있기 때문이다. 그래서 규약은 실제로 관찰된 샌드박스 정책으로만 판단하라고 못 박는다:

• 관찰값이 read-only면 → 격리가 강제됨, 진행 OK.
• 숙주가 넓혔으면 → 하드 격리가 불필요하고, 프롬프트가 편집을 금하며, 부모가 전후 상태를 정확히 캡처·검증할 때만 "행동상 read-only"로 진행하고 잔여 위험을 보고.
• 격리를 관찰할 수 없거나 변조가 발생하면 → 리뷰 lane 정지, "read-only였다"고 거짓 주장 금지.

"요청한 것"과 "실제로 벌어진 것"을 구분하고, 후자로만 안전을 주장하는 이 정직함이 sol-advisor 설계 전반을 관통한다.

5디렉토리 구조 해부

구조가 알려주는 힌트 셋. 첫째, 가장 큰 파일이 셋 다 scripts/의 셸이다(install 287 · verify 267 · inspect 156줄). 이 프로젝트의 무게중심이 "AI에게 줄 프롬프트"가 아니라 "사람·기계가 검증할 수 있는 장치"에 실려 있음을 그대로 보여 준다. 둘째, agents/(무엇을)·skills/(어떻게)·scripts/(강제)로 역할이 폴더로 갈려 있다 — 정의, 절차, 집행이 코드 트리에 1:1로 대응한다. 셋째, plugin.json의 버전 0.3.0과 설치기 안의 v0.2.0 지문이 공존한다 — 이 레포가 이미 한 번 세대교체(3-lane → 2-lane)를 거쳤다는 흔적이다.

6학습 포인트 — 기술별 배울 것

① 역할 핀 & 조용한 대체 금지 (가장 값진 배움)

모델·추론 강도를 호출 시점이 아니라 선언(TOML)에 못 박고, 실제 실행값을 관찰해 어긋나면 멈추는 패턴. "편의를 위한 자동 대체가 곧 조용한 품질 저하"라는 통찰과, 그걸 강제 가능한 장치로 바꾸는 법을 배운다. LLM 파이프라인뿐 아니라 어떤 다단계 시스템에서도 "묵시적 폴백은 위험하다"는 원칙은 그대로 통한다.

② TOCTOU-안전한 파일 설치

사용자 파일을 절대 말없이 덮지 않는 설치기 설계. SHA-256으로 목적지를 6상태로 분류하고, mktemp+하드링크(ln)로 원자적으로 설치하며, 변경 직전에 상태를 재검사한다. 점표(dotfiles) 설치기, 마이그레이션 도구, 배포 스크립트를 짤 때 "조금이라도 다르면 사람에게 넘긴다"는 안전한 기본값을 배운다.

③ 최소 공개 introspection

민감정보가 든 로그에서 허용목록 필드만 새 객체로 구성해 내보내는 jq 패턴. "필터로 빼기"가 아니라 "허용된 것만 짓기"의 차이, 입력 검증(UUID 강제), "정확히 1개 매칭 전엔 내용을 안 연다"는 절제. 로그·API 응답을 안전하게 가공해야 할 때 두고두고 쓰는 기술이다.

④ 검증을 1급 시민으로 (verify.sh)

267줄짜리 verify.sh는 이 레포의 자가 테스트 하네스다 — 매니페스트 버전·TOML 핀을 검사하고, 깨끗한 설치·멱등성·마이그레이션·거부(수정된 파일/심볼릭 링크/오래된 파일)를 실제로 재현해 보고, 런타임 인스펙터의 라우팅 정확성과 유출 방지까지 시험한다. "문서가 코드와 어긋나지 않는지"(폐기된 스폰이 남아 있나)도 grep으로 잡는다. 규율을 말로만 두지 않고 CI로 집행하는 법의 표본.

⑤ 5부 위임 계약 (재사용성 최고)

OBJECTIVE / FILES·OWNERSHIP / INTERFACES / CONSTRAINTS / VERIFICATION로 짜인 명세 양식은 Codex가 아니어도 쓸 수 있다. Claude Code 서브에이전트, 동료에게 맡기는 작업 지시, 심지어 이슈 템플릿에도 그대로 적용된다. 특히 "증거 없는 완료 주장은 무효"라는 반환 규칙은 위임의 품질을 극적으로 끌어올린다.

⑥ 정직한 보안 서술 (관찰 vs 요청)

"read-only를 요청했다"와 "실제로 read-only로 관찰됐다"를 구분하고, 후자로만 안전을 주장하는 태도. 그리고 "Sol이 Sol을 보는 건 맥락만 신선할 뿐 모델 독립이 아니다"라며 잔여 위험을 스스로 명시하는 것. 과장 없이 한계를 적는 것이 오히려 신뢰를 만든다는, 문서화의 좋은 본보기다.

7시스템 / 실행 요구사항

• GPU·로컬 모델 불필요 — 추론은 Codex/OpenAI가 한다. 이 레포는 설정·스크립트뿐이라 빌드할 산출물도, 다운로드할 가중치도 없다.
• OS — 스크립트가 순수 POSIX sh라 macOS·Linux에서 동일 동작. Codex 자체 요구사항을 따른다.
• 설치기의 목적지 — --target-dir 없으면 $CODEX_HOME/agents(있으면), 없으면 $HOME/.codex/agents. 설치기는 config.toml을 건드리지 않고 역할 파일만 놓는다.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 로드맵 (주차별)

10핵심 키워드 사전

11참고 링크

• GitHub 저장소: github.com/DannyMac180/sol-advisor
• 1차 소스(권장 정독 순서): plugins/sol-advisor/skills/orchestration/SKILL.md(절차) → references/role-contracts.md(5부 계약) → agents/*.toml(역할 핀) → scripts/install-agents.sh(안전 설치) → scripts/inspect-agent-runtime.sh(최소공개) → scripts/verify.sh(검증 하네스)
• 저자 글: Daniel McAteer의 뉴스레터 Attention Heads — "Agentic Engineering Field Notes"(에이전트 엔지니어링 현장 노트) 시리즈
• 플랫폼: OpenAI Codex — 커스텀 에이전트·플러그인·네이티브 서브에이전트 문서
• 관련 개념(오케스트레이션): orchestrator–worker 패턴 · reflection/critic(자기검토) 패턴 · LLM-as-a-judge · multi-agent review
• 관련 개념(엔지니어링): TOCTOU 경쟁 조건 · 원자적 파일 교체(temp+rename/link) · allowlist 로그 위생 · POSIX 셸 이식성 · SHA-256 무결성 검증