Codex 실전 활용 2편에서는 30분 뼈대 수립, 프롬프트 작업 계약, 창구(Desktop/IDE/CLI/Cloud) 선택 기준, 대형 저장소 길찾기, 그리고 팀의 헌법이 되는 AGENTS.md 실전 설계를 다룹니다.
1. 30분 안에 첫 제품 뼈대(Scaffold)를 세우는 법
새로운 아이디어를 코드로 옮길 때 처음부터 모든 기능을 완성하려 하면 에이전트와 인간 모두 지치게 됩니다.
30분 뼈대 구축 4단계 순서
- 최소 구동 환경 준비: 빈 폴더 생성 및 기본 설정 파일(
package.json또는wrangler.jsonc) 준비 - 완료 조건 한 줄 정의: "Express/Workers 서버가
/api/health에서 200 OK를 반환하고 기본 HTML을 렌더링한다." - Codex 1차 스캐폴딩 지시: 핵심 프레임워크 뼈대 코드만 요청하고 즉시 실행 검증
- 기능 레이어 단계적 추가: 뼈대가 통과한 후에만 데이터베이스 및 UI 컴포넌트 레이어를 순차적으로 얹기
2. 좋은 요청의 구조화: 프롬프트 작업 계약 (Task Contract)
나쁜 요청은 "예쁘고 빠른 로그인 페이지 만들어줘" 같은 모호한 자연어입니다. 좋은 요청은 아래 4개 요소를 포함한 작업 계약서입니다.
[Task Contract]
1. Goal: Express API에 JWT 기반 로그인/회원가입 라우터 추가
2. Scope & Files:
- Modify: src/routes/auth.js, src/middleware/jwt.js
- DO NOT Touch: src/routes/payment.js, public/index.html
3. Requirements:
- bcrypt를 사용한 비밀번호 암호화
- 토큰 만료 시간 24시간 설정
4. Verification:
- npm test tests/auth.test.js 통과 필수
3. 창구(Surface) 전환 마트릭스: 언제 바꿔 타야 할까?
Codex는 ChatGPT 웹, Codex Desktop App, IDE Extension (VS Code), CLI (codex exec), Cloud/GitHub 등 다양한 창구를 제공합니다.
| 작업 창구 | 주요 특징 및 추천 상황 | 권장 작업 종류 |
|---|---|---|
| ChatGPT / Web | 설치 없이 빠르게 아이디어 탐색 및 아키텍처 구상 | 초기 구상, 스키마 설계, 브레인스토밍 |
| Codex Desktop App | 독립된 멀티 윈도우 환경, 파일 트래킹 및 시각적 검증 | 단독 기능 구현, 스크린샷 렌더링 검증 |
| VS Code / IDE | 기존 개발 흐름과 통합, Inline Diff 검토 및 실시간 에디팅 | 코어 개발, 리팩터링, 대화형 디버깅 |
CLI (codex exec) |
터미널 명령 줄 실행, 스크립트 연동 및 CI/CD 자동화 | 매일 실행되는 주간 루틴, CI 빌드 검증 |
| Cloud / GitHub | PR 기반 자동 코드 리뷰, 비동기 이슈 처리 | 팀 단위 코드 리뷰, 비동기 파이프라인 |
4. 처음 보는 저장소에서 길을 찾는 순서 (Repository Navigation)
수만 줄에 달하는 거대한 처음 보는 저장소에 투입되었을 때 Codex를 활용해 길을 찾는 3단계 탐색법입니다.
- Top-Down 탐색:
AGENTS.md및README.md읽기 ➔ 의존성 파일(package.json,Cargo.toml) 분석으로 핵심 스택 파악 - Entry Point 추적: 메인 엔트리 파일(
src/index.js,src/worker.js)의 라우팅 매핑 테이블 추출 지시 - Execution Trace 핑거프린팅: 특정 유저 요청이 유입되었을 때 데이터가 거치는 함수 호출 트레이스 역추적
5. AGENTS.md는 왜 팀의 헌법이 되는가?
AGENTS.md는 개발자 개인의 머릿속에만 있던 노하우와 프로젝트 제약 조건을 AI 에이전트가 이해할 수 있는 공용 규칙으로 자산화한 팀의 헌법 문서입니다.
📋 공용 AGENTS.md 5대 표준 섹션
- 1. System & Architecture: 기술 스택 및 디렉토리 아키텍처 정의
- 2. Constrain Rules: 절대 하지 말아야 할 파괴적 조작 및 스타일 금지 수칙
- 3. Inform & Context: 핵심 라우터 및 데이터 모델의 위치 명세
- 4. Verification Commands: 코드 완료 전 반드시 구동해야 할 빌드/테스트 명령어
- 5. Error Recovery: 실패 시 로그 수집 및 롤백 절차 규정
6. 대형 작업(Long-running Task)의 계획 문서(Plan.md) 선행 패턴
작업 규모가 크고 1시간 이상 소요되는 대형 작업의 경우, 코드를 먼저 쓰지 않고 Plan.md 계획 문서부터 세우는 것이 실패를 예방하는 핵심입니다.
- 에이전트에게 요구사항 분석 후
Plan.md작성을 지시 - 인간 엔지니어가
Plan.md의 단계별 체크리스트 검토 및 승인 - 승인된
Plan.md의 체크리스트를 하나씩 체크하며 단계별 코드 생성 및 Verify 릴레이 수행