참고자료 · Profiles / Subagents

Profiles 와 Subagents 설계

Codex 하네스를 제대로 설명하려면 config와 hooks만으로는 부족합니다. 실제 실무에서는 “어떤 mode로 실행할 것인가”와 “어떤 역할을 서브에이전트로 분리할 것인가”가 생산성과 비용, 안정성을 크게 좌우합니다. 이 페이지는 그 두 층을 같이 설명합니다.

1. Profiles는 작업 모드를 나누는 층입니다

profile은 “개인 취향 저장소”가 아니라, 팀이 반복적으로 합의한 작업 모드를 나누는 층으로 보는 것이 좋습니다. 예를 들어 review, verify, codex, quick 같은 이름은 역할이 분명하지만, 개인 실험값을 계속 추가한 profile은 팀 공통 설정을 오염시키기 쉽습니다.

[profiles.review]
model = "gpt-5.4-mini"
sandbox_mode = "read-only"
approval_policy = "on-request"

[profiles.verify]
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[profiles.codex]
model = "gpt-5-codex"
model_reasoning_effort = "high"

2. 어떤 profile이 유용한가

3. Subagents는 역할을 좁게 나눠야 합니다

좋은 subagent는 메인 에이전트의 축소판이 아닙니다. reviewer, verifier, docs researcher, ops auditor처럼 좁고 검증 가능한 역할을 가져야 병렬화 가치가 생깁니다.

name = "reviewer"
description = "Read-only reviewer for regressions, missing tests, and risky edits."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"

developer_instructions = """
변경사항을 읽기 전용으로 검토합니다.
행동 회귀, 누락 테스트, 위험한 수정, 계약 드리프트를 우선 확인합니다.
"""

4. 실무에서 유용한 역할 분리

• reviewer: 회귀, 누락 테스트, 위험 수정 확인
• gradle_verifier: build / lint / test 검증
• docs_researcher: 공식 문서와 링크 검증
• ops_safety_auditor: 배포 / 인프라 / destructive operation 검토
• python_mlops_reviewer: 파이프라인 / drift / registry 변경 검토

5. 모델 배치 원칙

메인 세션은 이해력과 설명 품질이 중요한 모델을 두고, subagent는 더 좁은 역할에 맞는 빠른 모델을 두는 편이 좋습니다. 현재 공식 모델 카드 기준으로 GPT-5.4 mini는 subagent나 고속 coding 보조 역할에 상당히 적합합니다.

6. 같이 읽으면 좋은 페이지