Codex 앱 메인·서브에이전트 협업 가이드

문서 기준일: 2026-07-30

목표: 메인 에이전트가 API·백엔드를 담당하고, 프론트엔드 전담 서브에이전트와 협업하도록 구성한다.

1. 권장 협업 구조

Codex 앱에서 두 개의 독립 작업을 나중에 연결하는 방식이 아니라, 메인 작업에서 프론트엔드 전담 서브에이전트를 직접 생성하는 방식을 사용한다.

메인 에이전트: API Lead
├─ 요구사항 분석 및 API 계약 결정
├─ backend/** 구현
├─ 프론트 담당자에게 API 계약 전달
├─ 서브에이전트 진행 관리
├─ 변경사항 통합 및 충돌 해결
└─ 백엔드·프론트 최종 검증

서브에이전트: frontend_worker
├─ frontend/** 전담
├─ API DTO에 맞춘 TypeScript 타입 구현
├─ Vue/Nuxt 화면 및 상태 처리
├─ 프론트 테스트·typecheck·build
└─ 변경 파일과 검증 결과를 메인 에이전트에 보고

현재 저장소가 backend/와 frontend/로 분리되어 있으므로, 각 에이전트의 파일 소유 범위만 명확히 하면 같은 기능을 병렬로 구현하기 좋은 구조다.

2. Codex 서브에이전트의 특징

• 현재 Codex 릴리스에서는 서브에이전트 기능이 기본적으로 활성화된다.
• 메인 에이전트가 직접 요청을 받아 서브에이전트를 생성하고 업무를 위임한다.
• 서브에이전트는 별도의 agent thread에서 작업한다.
• 메인 에이전트는 서브에이전트의 결과를 회수해 하나의 최종 결과로 통합한다.
• Codex 앱에서 활성·완료된 서브에이전트와 개별 작업 내용을 확인할 수 있다.
• 서브에이전트는 부모 작업의 도구와 권한 정책을 기본적으로 상속한다.
• 에이전트마다 모델과 도구를 별도로 사용하므로 단일 에이전트보다 계정 사용량이 증가한다.

이미 별도로 만든 두 개의 일반 Codex 작업을 부모·자식 서브에이전트 관계로 연결하는 공식 흐름은 없다. 협업이 필요하면 메인 작업에서 새 서브에이전트를 생성해야 한다.

3. 프로젝트 설정

프로젝트에 다음 파일을 추가하면 frontend_worker 역할을 반복해서 사용할 수 있다.

google-maps-poc/
└─ .codex/
   ├─ config.toml
   └─ agents/
      └─ frontend-worker.toml

3.1 .codex/config.toml

[agents]
enabled = true
max_concurrent_threads_per_session = 1

max_concurrent_threads_per_session은 메인 에이전트를 제외하고 동시에 실행할 수 있는 서브에이전트 수다. API 담당 메인 에이전트와 프론트 담당 서브에이전트 한 명만 사용하는 경우 1로 설정한다.

3.2 .codex/agents/frontend-worker.toml

name = "frontend_worker"
description = "Nuxt, Vue, TypeScript 프론트엔드 구현과 검증을 담당하는 프로젝트 전용 에이전트."

sandbox_mode = "workspace-write"

developer_instructions = """
당신은 이 프로젝트의 프론트엔드 담당자다.

소유 범위:
- frontend/**

금지 범위:
- backend/** 수정 금지
- 루트 README.md, PLAN.md, 공통 Git 설정 수정 금지
- 부모가 전달한 API 응답 규격을 임의로 변경하지 말 것

업무 원칙:
1. 부모 에이전트가 전달한 API 계약을 기준으로 구현한다.
2. 계약이 불명확하면 추측해서 백엔드를 수정하지 말고 부모에게 질문한다.
3. Vue 3, Nuxt 4, TypeScript의 기존 구조와 스타일을 유지한다.
4. 기존 사용자 변경과 관련 없는 파일을 수정하지 않는다.
5. 완료 전에 typecheck와 build를 실행한다.
6. 변경 파일, 실행한 검증, 실패 항목, 남은 가정을 부모에게 간결하게 보고한다.
"""

커스텀 에이전트에는 다음 필드가 필수다.

• name
• description
• developer_instructions

model과 model_reasoning_effort를 생략하면 부모 작업 또는 전역 서브에이전트 설정을 상속한다. 프로젝트 전용 에이전트는 .codex/agents/, 모든 프로젝트에서 사용할 개인 에이전트는 %USERPROFILE%\.codex\agents\에 둔다.

설정 파일을 새로 추가하거나 변경한 뒤에는 새 Codex 작업을 열어 설정을 다시 읽게 하는 것이 안전하다.

4. Codex 앱에서 실행하는 프롬프트

프로젝트를 연 뒤 새 Codex 작업에 다음 프롬프트를 입력한다.

이 기능을 메인/서브에이전트 협업으로 구현하세요.

역할:
- 메인 에이전트인 당신은 API 설계, backend/** 구현, 통합과 최종 검증을 담당합니다.
- frontend_worker 서브에이전트 한 명을 생성해 frontend/** 구현을 맡기세요.

진행 순서:
1. 먼저 기존 프론트와 백엔드를 조사하고 API 요청·응답 계약을 확정하세요.
2. 확정한 엔드포인트, 요청 파라미터, 응답 JSON, 오류 규격을
   frontend_worker에게 전달하세요.
3. frontend_worker가 프론트를 구현하는 동안 메인 에이전트는
   backend/**를 구현하세요.
4. 서로의 소유 경로 밖 파일은 수정하지 마세요.
5. frontend_worker가 끝날 때까지 기다린 뒤 결과를 검토하세요.
6. 백엔드 테스트, 프론트 typecheck와 build를 모두 실행하세요.
7. 실패하면 담당 영역의 에이전트가 수정하게 하고 다시 검증하세요.
8. 마지막에는 전체 변경사항과 테스트 결과를 하나로 정리하세요.

서브에이전트가 반드시 필요할 때는 다음 표현을 명시적으로 사용한다.

• frontend_worker 서브에이전트를 생성하세요.
• 프론트 작업을 frontend_worker에게 위임하세요.
• 메인과 서브에이전트가 병렬로 작업하세요.
• 서브에이전트가 끝날 때까지 기다린 후 결과를 통합하세요.

5. API 계약 전달

병렬 구현을 시작하기 전에 메인 에이전트가 최소한 다음 계약을 결정해야 한다.

5.1 계약 예시

GET /api/v1/places/{placeId}?locale=ko

{
  "placeId": "ChIJ...",
  "name": "업체명",
  "rating": 4.5,
  "ratingCount": 320,
  "reviews": [],
  "photos": []
}

5.2 프론트 에이전트에 전달할 내용

• 엔드포인트와 HTTP 메서드
• Path·query 파라미터
• 요청 본문
• 정상 응답 DTO
• nullable 또는 선택 필드
• 오류 상태 코드와 자체 오류 코드
• 로딩·빈 결과·부분 실패 처리
• Mock 응답 제공 여부
• 프론트에서 호출해야 하는 시점

API 계약 없이 병렬로 시작하면 프론트와 백엔드가 서로 다른 DTO를 구현할 수 있으므로 통합 비용이 커진다.

6. 파일 소유권

공유 파일을 두 에이전트가 동시에 수정하지 않도록 한다. 공통 문서나 루트 설정을 수정해야 한다면 서브에이전트는 필요한 변경사항만 보고하고 실제 수정은 메인 에이전트가 수행한다.

7. 실행 중 서브에이전트 관리

Codex 앱의 Subagents 또는 백그라운드 에이전트 영역에서 다음 내용을 확인할 수 있다.

• Active: 현재 실행 중인 서브에이전트
• Done: 완료된 서브에이전트
• 개별 agent thread
• 작업 과정과 최종 결과
• 중단 또는 종료 상태

진행 중 추가 지시가 필요하면 메인 채팅에 입력한다.

frontend_worker에게 reviews 필드가 배열로 변경됐다고 전달하고
프론트 타입과 화면을 수정하게 해줘.

frontend_worker의 현재 진행 상태와 블로커를 요약해줘.

frontend_worker를 중단하고 현재 변경사항만 검토해줘.

중요한 API 계약 변경은 서브에이전트 작업 화면에 직접 입력하기보다 메인 에이전트를 통해 전달하는 것이 좋다. 메인 에이전트가 계약 변경과 전체 영향 범위를 관리해야 하기 때문이다.

8. 완료 및 검증 순서

8.1 메인 에이전트 검증

cd backend
.\gradlew.bat test
.\gradlew.bat build

8.2 프론트엔드 검증

cd frontend
pnpm typecheck
pnpm build

8.3 통합 검증

1. 백엔드 API를 실행한다.
2. 프론트엔드를 실행한다.
3. 실제 또는 Mock API 요청을 확인한다.
4. 정상·빈 결과·오류 응답을 확인한다.
5. 브라우저 콘솔 오류와 네트워크 요청을 확인한다.
6. API 응답과 TypeScript 타입이 일치하는지 확인한다.
7. 메인 에이전트가 전체 변경 파일과 테스트 결과를 최종 정리한다.

서브에이전트의 완료 보고만으로 전체 작업을 완료 처리하지 않는다. 메인 에이전트가 서브에이전트 변경을 검토하고 전체 테스트를 통과시켜야 한다.

9. 같은 checkout과 Worktree 선택

같은 작업의 서브에이전트가 적합한 경우

• 하나의 기능을 프론트와 백엔드로 분담
• backend/와 frontend/처럼 파일 경계가 분명함
• 메인 에이전트가 계약과 최종 통합을 책임짐
• 결과를 한 번에 검증하고 전달해야 함

별도 Worktree가 적합한 경우

• 프론트와 백엔드가 공통 설정 파일을 많이 수정
• 대규모 리팩터링
• 각각 별도 커밋이나 PR이 필요
• 여러 날 동안 독립적으로 진행
• 같은 파일을 동시에 수정할 가능성이 큼

Worktree는 독립 checkout을 만들어 충돌을 줄이지만, 두 일반 작업이 자동으로 부모·자식 관계가 되는 것은 아니다. 작업 결과를 브랜치, PR 또는 Codex의 Handoff 흐름으로 합쳐야 한다.

10. /side와 서브에이전트 차이

프론트 구현처럼 실제 파일을 수정하고 테스트해야 하는 업무에는 /side 대신 서브에이전트 또는 별도 Worktree를 사용한다.

11. 문제 해결

서브에이전트가 생성되지 않음

• 프롬프트에 서브에이전트를 생성하세요를 명시한다.
• .codex/config.toml에서 agents.enabled = true인지 확인한다.
• 설정 변경 후 새 Codex 작업을 연다.
• 프로젝트 또는 관리자 정책에서 다중 에이전트가 제한됐는지 확인한다.

frontend_worker를 찾지 못함

• 파일이 .codex/agents/frontend-worker.toml에 있는지 확인한다.
• TOML의 name = "frontend_worker"가 프롬프트 이름과 일치하는지 확인한다.
• name, description, developer_instructions가 모두 있는지 확인한다.
• TOML 문법 오류가 없는지 확인하고 새 작업을 연다.

프론트 에이전트가 백엔드 파일을 수정함

• developer_instructions에 경로 소유권을 더 명확히 적는다.
• 실행 프롬프트에도 backend/** 수정 금지를 반복한다.
• 변경이 계속 겹치면 프론트 작업을 Worktree로 분리한다.

API와 프론트 타입이 맞지 않음

• 메인 에이전트가 실제 백엔드 응답을 다시 추출한다.
• JSON 예시와 nullable 필드를 프론트 에이전트에 재전달한다.
• 프론트 에이전트가 타입과 변환 로직을 수정하게 한다.
• 메인 에이전트가 통합 테스트를 다시 실행한다.

권한 승인 때문에 서브에이전트가 멈춤

• 서브에이전트는 부모 작업의 권한 모드를 상속한다.
• 작업 시작 전에 입력창 아래 권한 모드를 확인한다.
• 필요한 승인은 요청 출처를 확인한 뒤 허용한다.
• 프론트 에이전트에 불필요한 외부 네트워크나 광범위 파일 권한을 주지 않는다.

12. 공식 참고 문서

• Codex Subagents
• Codex Worktrees
• Codex Config basics
• Codex Permissions
• Codex Developer commands

13. 적용 체크리스트

• .codex/config.toml 생성
• .codex/agents/frontend-worker.toml 생성
• 새 Codex 작업 시작
• 메인 에이전트의 API·통합 책임 명시
• frontend_worker 생성 명시
• API 계약 확정 후 프론트 업무 위임
• backend/**와 frontend/** 소유권 분리
• 서브에이전트 완료 결과 검토
• 백엔드 테스트·빌드 통과
• 프론트 typecheck·빌드 통과
• 통합 동작 검증
• 메인 에이전트가 최종 결과 정리

안녕하세요. 공존에서 진행하는 월간 경제 브리핑 안내드려요.
건물주가 되는 성곡적인 로드맵을 알려주시는 맥밀란, 열정잇기님의 <5월 월간 경제 브리핑> 신청해 보세요. 

신청안내 글은 : 아래 링크를 클릭해 주시면 방문해서 보실 수 있어요 ^^
                        맥밀란열정잇기의 디벨롭 공존 신축부동산경제모임꼬마빌딩 : 네이버 카페

Vue.js나 Nuxt.js로 만든 정적(Static) 웹사이트를 AWS S3에 배포하고 커스텀 도메인까지 연결하려면,
 **CloudFront(CDN)와 Route 53(DNS), ACM(무료 SSL 인증서)**을 함께 사용하는 것이 현대적인 표준 아키텍처입니다.

S3 단독으로는 커스텀 도메인에 HTTPS(보안 연결)를 적용할 수 없기 때문입니다.

가장 안전하고 속도가 빠른 'S3 비공개 + CloudFront 배포' 방식을 기준으로 단계별 설정 방법을 안내해 드립니다.

1단계: 프로젝트 빌드 (정적 파일 생성)

먼저 로컬 환경에서 프로젝트를 정적 파일로 빌드해야 합니다.

• Vue.js: npm run build (완료되면 dist 폴더가 생성됩니다.)
• Nuxt.js (Nuxt 3 기준): SSR이 아닌 정적 사이트 생성(SSG)을 위해 npm run generate를 실행합니다. (완료되면 .output/public 또는 dist 폴더가 생성됩니다.)

2단계: AWS S3 버킷 생성 및 파일 업로드

S3는 웹사이트의 파일들이 저장되는 저장소 역할을 합니다.

1. AWS 콘솔에서 S3로 이동하여 [버킷 만들기]를 클릭합니다.
2. 버킷 이름을 입력합니다. (예: my-vue-website-bucket)
3. 객체 소유권 및 퍼블릭 액세스 차단 설정은 기본값(모든 퍼블릭 액세스 차단)을 그대로 둡니다. (CloudFront를 통해서만 접근하게 하여 보안을 높입니다.)
4. 버킷이 생성되면, 앞서 빌드한 폴더(dist 또는 .output/public) 안의 내용물 전체를 S3 버킷에 업로드합니다.

3단계: ACM에서 무료 SSL 인증서 발급

HTTPS 통신을 위해 인증서를 미리 발급받아야 합니다.

1. AWS 콘솔 우측 상단에서 리전을 반드시 **미국 동부(버지니아 북부, us-east-1)**로 변경합니다. (CloudFront용 인증서는 무조건 이 리전에서 발급받아야 합니다.)
2. **Certificate Manager(ACM)**로 이동하여 [인증서 요청]을 클릭합니다.
3. 사용할 도메인 이름(예: example.com 및 *.example.com)을 입력하고 DNS 검증을 통해 인증서를 발급받습니다.

4단계: CloudFront 배포 (CDN 및 HTTPS 연결)

전 세계 어디서든 사이트가 빠르게 로딩되도록 캐싱하고, S3와 도메인을 연결해 줍니다.

1. AWS 콘솔에서 CloudFront로 이동하여 [배포 생성]을 클릭합니다.
2. 원본 도메인(Origin domain): 앞서 만든 S3 버킷을 선택합니다.
3. 원본 액세스(Origin access): 원본 액세스 제어 설정(OAC)을 선택하고 [제어 설정 생성]을 눌러 추가합니다. (이 설정을 통해 CloudFront만 S3에 접근할 수 있게 됩니다.)
4. 뷰어 프로토콜 정책: Redirect HTTP to HTTPS를 선택합니다.
5. 웹 애플리케이션 방화벽(WAF): 보안 보호 활성화/비활성화 중 선택합니다. (비용 절감을 위해 일단 비활성화해도 무방합니다.)
6. 대체 도메인 이름(CNAME): 서비스할 실제 도메인(예: www.example.com)을 입력합니다.
7. 사용자 정의 SSL 인증서: 3단계에서 발급받은 인증서를 선택합니다.
8. 기본값 루트 객체: index.html을 입력하고 [배포 생성]을 완료합니다.

💡 중요 - S3 버킷 정책 업데이트: 배포가 생성되면 화면 상단에 알림창이 뜹니다. '정책 복사'를 누른 뒤, S3 버킷의 [권한] 탭 - [버킷 정책]에 붙여넣기 하여 CloudFront가 S3 파일을 읽을 수 있도록 허용해 주어야 합니다.

5단계: SPA(Single Page Application) 라우팅 에러 해결

Vue나 Nuxt 같은 SPA는 새로고침 시 403/404 에러가 발생할 수 있습니다. 이를 해결하기 위해 CloudFront 설정을 추가해야 합니다.

1. 생성한 CloudFront 배포의 [오류 페이지] 탭으로 이동합니다.
2. [사용자 정의 오류 응답 생성]을 클릭합니다.
3. HTTP 오류 코드: 403: Forbidden을 선택합니다.
4. 오류 응답 사용자 정의: 예
5. 응답 페이지 경로: /index.html
6. HTTP 응답 코드: 200: OK
7. 위와 동일한 방법으로 404: Not Found에 대해서도 똑같이 하나 더 생성해 줍니다.

6단계: Route 53 (또는 외부 DNS) 도메인 연결

마지막으로 도메인과 CloudFront를 연결합니다.

1. Route 53 호스팅 영역으로 이동합니다. (가비아 등 외부 업체를 쓴다면 해당 업체의 DNS 설정으로 이동합니다.)
2. [레코드 생성]을 클릭합니다.
3. 레코드 유형: A - IPv4 주소...
4. 별칭(Alias): 활성화
5. 트래픽 라우팅 대상: CloudFront 배포에 대한 별칭을 선택하고, 4단계에서 만든 CloudFront의 도메인 주소(예: d123456.cloudfront.net)를 선택한 후 저장합니다.

이제 약 10~15분 정도 DNS 전파 및 CloudFront 배포가 완료되기를 기다린 후, 도메인으로 접속하시면 정상적으로 서비스가 열리는 것을 확인할 수 있습니다.

혹시 AWS CLI나 GitHub Actions를 이용해서 코드를 푸시할 때마다 이 S3에 자동으로 빌드 및 배포(CI/CD)되도록 자동화하는 스크립트도 함께 작성해 드릴까요?