하네스 엔지니어링 5 - CODEX : 서브 에이전트(Sub Agent)

https://developers.openai.com/codex/subagents

Subagents – Codex | OpenAI Developers

 

 

AGENTS.md는 보통 서브에이전트를 직접 실행하거나 정의하는 파일이 아니라, 저장소에서 작업할 때 따라야 할 규칙과 참고 경로를 안내하는 지침 문서입니다.

즉 연결 구조는 이렇게 됩니다.

• AGENTS.md: 작업 규칙, 참고 문서, 권장 작업 방식 안내
• custom agent 정의 파일: 각 에이전트의 역할, 제약, 지침 정의
• skill 정의 파일: 반복 작업 절차와 도메인 지식 정의
• 실행 로직: 실제로 custom agent를 spawn하는 Codex 기능

실무적으로는 AGENTS.md가 “배포 이슈를 다룰 때는 release_auditor 같은 custom agent를 사용하는 것이 적절하다”는 지침을 줄 수 있고, 실제 release_auditor의 정의는 .codex/agents/release-auditor.toml에 둡니다.

1. 연결 방식

예를 들어 사용자가 “장애 원인을 찾아줘”라고 요청하면:

1. 메인 에이전트는 저장소 지침 문서인 AGENTS.md를 참고할 수 있습니다.
2. 작업 규칙과 문서 맵은 참고할 수 있지만, skill은 명시적으로 호출되거나 skill 설명과 작업이 맞을 때 사용되며, custom agent는 사용자가 명시적으로 요청할 때만 spawn됩니다.
3. 메인 에이전트는 .codex/agents/log-investigator.toml 같은 파일에 정의된 custom agent를 사용할 수 있으며, 실제 식별 기준은 파일명이 아니라 해당 파일의 name 필드입니다.
4. 필요하면 .agents/skills/log-analyzer/ 아래의 skill을 사용하며, Codex는 먼저 skill 메타데이터를 보고 필요할 때만 SKILL.md 전체를 로드합니다.
5. custom agent는 조사 결과를 반환하고, 메인 에이전트가 그 결과를 모아 최종 응답으로 통합합니다.

즉, AGENTS.md는 저장소 작업 지침 문서이고, custom agent 파일은 역할과 제약을 정의하는 실행 프로필이며, skill은 재사용 가능한 작업 절차와 자료를 묶은 워크플로 정의입니다.

2. 샘플 폴더 구조

아래는 간단하지만 역할이 분명한 예시입니다.

repo/
├── AGENTS.md
├── .codex/
│   └── agents/
│       ├── log-investigator.toml
│       ├── release-auditor.toml
│       └── docs-researcher.toml
├── .agents/
│   └── skills/
│       ├── log-analyzer/
│       │   └── SKILL.md
│       ├── release-checker/
│       │   └── SKILL.md
│       └── openai-docs/
│           └── SKILL.md
├── docs/
│   ├── operations/
│   │   ├── logging.md
│   │   └── incident-process.md
│   └── release/
│       └── release-process.md

3. 예시 AGENTS.md

여기서는 skill과 custom agent를 둘 다 연결합니다.

# AGENTS.md

## Purpose
This repository supports IT operations, release validation, and API integration work.

## Global Rules
- Prefer repository docs over assumptions.
- Do not guess when logs or specs are available.
- Do not run destructive commands unless explicitly approved.
- Keep outputs concise and evidence-based.

## Docs Map
- Incident process: docs/operations/incident-process.md
- Logging guide: docs/operations/logging.md
- Release process: docs/release/release-process.md

## Skill Guidance
- For log analysis, use `.agents/skills/log-analyzer/SKILL.md`.
- For release validation, use `.agents/skills/release-checker/SKILL.md`.
- For official API documentation lookup, use `.agents/skills/openai-docs/SKILL.md`.

## Custom Agent Guidance
Use a custom agent when the task is large, research-heavy, or would pollute the main context.

### Use `log_investigator`
When the task involves:
- incident investigation
- repeated application errors
- root cause analysis from logs

First read:
- docs/operations/incident-process.md
- docs/operations/logging.md

Then use custom agent:
- `.codex/agents/log-investigator.toml`

### Use `release_auditor`
When the task involves:
- release readiness
- deploy risk review
- post-deploy validation

First read:
- docs/release/release-process.md

Then use custom agent:
- `.codex/agents/release-auditor.toml`

### Use `docs_researcher`
When the task involves:
- finding exact references in internal docs
- summarizing architecture or runbook content
- targeted documentation lookup

Then use custom agent:
- `.codex/agents/docs-researcher.toml`

## Output Expectations
- Separate verified facts from assumptions.
- Cite files, logs, or docs used as evidence.
- Keep custom agent outputs short and structured.

## Validation
- Run the most relevant checks before concluding.
- State clearly if validation was not run.

한글 예시:

# AGENTS.md

## 목적
이 저장소는 IT 운영, 릴리스 검증, API 연동 작업을 지원합니다.

## 전역 규칙
- 추정보다 저장소 문서를 우선합니다.
- 로그나 명세가 있으면 추측하지 않습니다.
- 명시적으로 승인되지 않은 파괴적 명령은 실행하지 않습니다.
- 출력은 간결하고 근거 중심으로 작성합니다.

## 문서 맵
- 장애 대응 프로세스: docs/operations/incident-process.md
- 로그 가이드: docs/operations/logging.md
- 릴리스 프로세스: docs/release/release-process.md

## 스킬 안내
- 로그 분석에는 `.agents/skills/log-analyzer/SKILL.md`를 사용합니다.
- 릴리스 검증에는 `.agents/skills/release-checker/SKILL.md`를 사용합니다.
- 공식 API 문서 조회에는 `.agents/skills/openai-docs/SKILL.md`를 사용합니다.

## 커스텀 에이전트 안내
작업이 크거나, 조사 비중이 높거나, 메인 컨텍스트를 많이 오염시킬 수 있을 때 custom agent를 사용합니다.

### `log_investigator` 사용
다음과 같은 작업일 때:
- 장애 조사
- 반복되는 애플리케이션 오류
- 로그 기반 근본 원인 분석

먼저 읽을 문서:
- docs/operations/incident-process.md
- docs/operations/logging.md

그다음 사용할 custom agent:
- `.codex/agents/log-investigator.toml`

### `release_auditor` 사용
다음과 같은 작업일 때:
- 릴리스 준비 상태 점검
- 배포 리스크 검토
- 배포 후 검증

먼저 읽을 문서:
- docs/release/release-process.md

그다음 사용할 custom agent:
- `.codex/agents/release-auditor.toml`

### `docs_researcher` 사용
다음과 같은 작업일 때:
- 내부 문서에서 정확한 참조 찾기
- 아키텍처나 런북 내용 요약
- 특정 문서 내용 조회

그다음 사용할 custom agent:
- `.codex/agents/docs-researcher.toml`

## 출력 기대치
- 검증된 사실과 가정을 구분합니다.
- 근거로 사용한 파일, 로그, 문서를 명시합니다.
- custom agent의 출력은 짧고 구조적으로 유지합니다.

## 검증
- 마무리 전에 가장 관련성 높은 검증을 실행합니다.
- 검증을 하지 못했다면 그 사실을 명확히 밝힙니다.

이 파일의 역할은 명확합니다.

• 어떤 작업이면 sub-agent를 쓰는지
• 무엇을 먼저 읽고
• 어떤 sub-agent 파일을 참고할지

다만 AGENTS.md는 지침 문서이며, custom agent가 실제로 spawn되는 조건은 별도입니다. custom agent는 사용자가 명시적으로 요청할 때만 spawn됩니다.

4. 실제 sub-agent 정의 파일

이제 실제 custom agent를 정의합니다. .codex/agents/log-investigator.toml 예시는 아래와 같습니다.

name = "log_investigator"
description = "Focused incident investigation agent for log-based root cause analysis."
sandbox_mode = "read-only"
developer_instructions = """
You are a focused incident investigation agent.
Your only job is to analyze logs and identify the most likely causes of failure.

Scope:
- Investigate logs and error messages
- Identify repeated patterns
- Correlate failures with recent changes when possible
- Do not modify application code
- Do not propose fixes unless explicitly asked

Procedure:
1. Identify the affected service and time range.
2. Find the highest-signal error messages first.
3. Group repeated failures into patterns.
4. Note timestamps, services, and error counts when available.
5. Produce up to 3 likely causes with evidence.
6. Mark weak conclusions as hypotheses.

Output format:
- Incident summary
- Evidence
- Likely causes
- Open questions

Guardrails:
- Do not guess without evidence.
- Do not edit files.
- Return only the final summary, not intermediate notes.
"""

 

모든 독립형 사용자 지정 에이전트 파일은 다음 정보를 정의해야 합니다.

name, description, developer_instructions
nickname_candidates, model, model_reasoning_effort, sandbox_mode, mcp_servers, 와 같은 선택적 필드는 skills.config 생략할 경우 부모 세션의 설정을 상속합니다.

 

 

에이전트 범위

• ~/.codex/agents/
루트 경로의 .codex/agents/에 설정할 경우  내 계정 전체에서 쓰는 개인용 에이전트 어느 프로젝트에 들어가도 공통으로 보입니다.

 

• .codex/agents/
현재 프로젝트 폴더 안에 두는 프로젝트 전용 에이전트는 그 프로젝트에서만 의미가 있습니다.

 

 

한글 예시:

name = "log_investigator"
description = "로그 기반 근본 원인 분석에 집중하는 장애 조사 에이전트."
sandbox_mode = "read-only"
developer_instructions = """
너는 장애 조사에 집중하는 에이전트다.
너의 유일한 임무는 로그를 분석하고 가장 가능성 높은 장애 원인을 식별하는 것이다.

범위:
- 로그와 오류 메시지를 조사한다
- 반복되는 패턴을 식별한다
- 가능하면 최근 변경과 장애의 상관관계를 찾는다
- 애플리케이션 코드는 수정하지 않는다
- 명시적으로 요청받지 않으면 해결책을 제안하지 않는다

절차:
1. 영향을 받은 서비스와 시간 범위를 식별한다.
2. 가장 신호가 강한 오류 메시지부터 찾는다.
3. 반복되는 실패를 패턴으로 그룹화한다.
4. 가능하면 타임스탬프, 서비스, 오류 횟수를 기록한다.
5. 근거와 함께 최대 3개의 가능한 원인을 제시한다.
6. 근거가 약한 결론은 가설로 표시한다.

출력 형식:
- 장애 요약
- 근거
- 가능한 원인
- 미해결 질문

가드레일:
- 근거 없이 추측하지 않는다.
- 파일을 수정하지 않는다.
- 중간 메모가 아니라 최종 요약만 반환한다.
"""

다른 custom agent도 같은 방식입니다.

.codex/agents/release-auditor.toml:

name = "release_auditor"
description = "Release risk review agent for deployment readiness and change risk."
sandbox_mode = "read-only"
developer_instructions = """
Review release-related changes and identify deployment risk.

Scope:
- Review release-related changes
- Identify deployment risk
- Check readiness signals
- Do not deploy or modify environments

Procedure:
1. Review changed files and affected components.
2. Identify config, migration, or infra risks.
3. Check whether required validation was completed.
4. Return a short release-risk summary.

Output format:
- Scope
- Risks
- Missing checks
- Recommendation
"""

한글 예시:

name = "release_auditor"
description = "배포 준비 상태와 변경 리스크를 검토하는 릴리스 리스크 점검 에이전트."
sandbox_mode = "read-only"
developer_instructions = """
릴리스 관련 변경을 검토하고 배포 리스크를 식별한다.

범위:
- 릴리스 관련 변경 사항 검토
- 배포 리스크 식별
- 준비 상태 신호 점검
- 배포나 환경 수정은 하지 않음

절차:
1. 변경된 파일과 영향을 받는 컴포넌트를 검토한다.
2. 설정, 마이그레이션, 인프라 리스크를 식별한다.
3. 필요한 검증이 완료되었는지 확인한다.
4. 짧은 릴리스 리스크 요약을 반환한다.

출력 형식:
- 범위
- 리스크
- 누락된 점검
- 권고 사항
"""

.codex/agents/docs-researcher.toml:

name = "docs_researcher"
description = "Documentation lookup agent for targeted internal or external reference checks."
sandbox_mode = "read-only"
developer_instructions = """
Search documentation, find exact references, and summarize only what is relevant to the parent task.

Procedure:
1. Search for the requested topic.
2. Read only the most relevant docs.
3. Return a concise answer with file references.

Output format:
- Answer
- Sources
"""

한글 예시:

name = "docs_researcher"
description = "내부 또는 외부 문서에서 필요한 참조를 찾아보는 문서 조회 에이전트."
sandbox_mode = "read-only"
developer_instructions = """
문서를 검색하고, 정확한 참조를 찾고, 부모 작업에 관련된 내용만 요약한다.

절차:
1. 요청된 주제를 검색한다.
2. 가장 관련성 높은 문서만 읽는다.
3. 파일 참조와 함께 간결한 답변을 반환한다.

출력 형식:
- 답변
- 출처
"""

5. 실제 spawn custom agent 예시

spawn이란 영어권 개발 문맥에서 부모 실행 주체가 새 작업 단위를 만들어 실행한다는 뜻으로, 여기서는 메인 에이전트가 하위 작업을 맡길 새 에이전트를 띄운다는 의미입니다.

개념적으로는 이렇게 연결됩니다.

{
  "agent_type": "log_investigator",
  "task_name": "log_investigator",
  "message": "Investigate payment-service errors from the last 1 hour. Return only: incident summary, evidence, likely causes, open questions."
}
{
  "agent_type": "release_auditor",
  "task_name": "release_auditor",
  "message": "Review the current release changes for deployment risk. Return only: scope, risks, missing checks, recommendation."
}

한글 예시:

{
  "agent_type": "log_investigator",
  "task_name": "log_investigator",
  "message": "지난 1시간 동안의 payment-service 오류를 조사해 주세요. 반환 형식은 다음만 포함합니다: 장애 요약, 근거, 가능한 원인, 미해결 질문."
}
{
  "agent_type": "release_auditor",
  "task_name": "release_auditor",
  "message": "현재 릴리스 변경 사항의 배포 리스크를 검토해 주세요. 반환 형식은 다음만 포함합니다: 범위, 리스크, 누락된 점검, 권고 사항."
}

여기서 관계를 다시 보면:

• AGENTS.md는 어떤 상황에서 어떤 custom agent와 skill이 적절한지 안내할 수 있지만, skill 사용과 custom agent spawn 여부는 Codex의 별도 동작 규칙을 따릅니다.
• 실제 custom agent 정의는 .codex/agents/*.toml에 있습니다.
• 실제 repo 범위 skill 정의는 .agents/skills/*/SKILL.md에 둘 수 있으며, Codex는 현재 작업 디렉터리부터 저장소 루트까지의 .agents/skills 경로를 스캔합니다.
• 메인 에이전트는 이 정의를 참고할 수 있지만, custom agent는 사용자가 명시적으로 요청한 경우에만 spawn합니다.

6. skill과 custom agent를 같이 쓰는 예

둘은 충돌하지 않고 같이 쓸 수 있습니다.

예:

1. 메인 에이전트는 AGENTS.md를 참고할 수 있습니다.
2. 로그 조사 작업이라도 log_investigator custom agent는 사용자가 명시적으로 요청한 경우에만 사용됩니다.
3. 그 custom agent는 작업 중 .agents/skills/log-analyzer/ skill의 메타데이터를 바탕으로 필요 시 SKILL.md를 로드해 로그 분석 절차를 따를 수 있습니다.

즉:

• custom agent = 어떤 역할이 필요할 때 누가 할지를 정의
• skill = 어떤 일을 할 때 어떻게 처리할지 표준화

7. 한 줄 요약

AGENTS.md는 저장소 작업 규칙과 참고 경로를 안내하는 문서이고, 실제 custom agent 정의는 .codex/agents/*.toml에 두며, repo 범위 skill 정의는 .agents/skills/*/SKILL.md에 둡니다. Codex는 사용자가 명시적으로 요청할 때만 custom agent를 spawn합니다.