Codex 마스터 클래스 1시간 편집본 | 하네스 설계부터 서비스 배포까지 > AI 엔지니어링

이전글루프 나온지도 얼마 안 됐는데 그래프 엔지니어링? 5분만에 쉽게 설명해드… 다음글 루프 엔지니어링 10분만에 가장 쉽게 설명해드려요ㅣ핵심 개념, 도입 효과…

최고관리자

26-08-29 20:42 0개 24회

Codex 마스터 클래스 1시간 편집본 | 하네스 설계부터 서비스 배포까지

# Codex 마스터 클래스 상세 요약 > **원본 영상:** [Codex 마스터 클래스 1시간 편집본｜하네스 설계부터 서비스 배포까지](https://www.youtube.com/watch?v=wScdyoQjj8E) > **채널:** 개발동생 > **게시일:** 2026년 5월 17일 > **영상 길이:** 51분 43초 > **실습 프로젝트:** Commit Hero > **핵심 주제:** Codex 하네스 구성요소를 이해하고, 아이디어 구체화부터 웹서비스 구현·검증·병렬 개발·배포까지 연결하는 실전 워크플로우 *** ## 1\. 영상 전체 요약 이 영상은 Codex를 단순한 코드 생성 도구가 아니라, **규칙·기억·업무 절차·외부 도구·강제 장치·병렬 에이전트를 결합해 실제 프로젝트를 수행하는 개발 에이전트**로 활용하는 방법을 설명합니다. 전반부에서는 Codex의 하네스를 구성하는 다음 여섯 요소를 다룹니다. 1. `AGENTS.md` 2. Memory 3. Skills 4. MCP 5. Hooks 6. Sub-agents 후반부에서는 이 요소들을 실제 개발 흐름에 적용해 **GitHub 사용자의 공개 활동을 분석하여 RPG 캐릭터 카드를 생성하는 ‘Commit Hero’ 서비스**를 만듭니다. 실습은 다음 순서로 진행됩니다. > 러프한 아이디어 → AI의 역질문 인터뷰 → 요구사항 확정 → 계획 문서 작성 → 목업 UI 구현 → 브라우저 검증 → GitHub API 연동 → GitHub 업로드 → 워크트리 병렬 개발 → AI 기능 추가 → Vercel 배포 영상의 가장 중요한 메시지는 다음과 같습니다. > **좋은 결과는 긴 프롬프트 하나에서 나오는 것이 아니라, AI가 일하는 기준과 절차를 프로젝트 안에 반복 가능한 구조로 고정할 때 나온다.** *** ## 2\. 하네스 엔지니어링이란? 영상에서는 하네스를 **AI가 일하는 방식을 일정하게 고정하는 구조**라고 설명합니다. 프롬프트만으로 애플리케이션 전체를 안정적으로 개발하기는 어렵습니다. 대화할 때마다 지시가 달라질 수 있고, 작업이 길어지면 처음의 목표를 잊거나 프로젝트 규칙을 어길 수도 있습니다. 하네스 엔지니어링은 AI 에이전트 주변에 다음과 같은 장치를 설치해 이 문제를 줄입니다. * 항상 따라야 하는 프로젝트 규칙 * 이전 작업과 사용자 선호를 이어주는 기억 * 반복 업무를 표준화한 절차 * 외부 시스템과 연결되는 도구 * 반드시 지켜야 하는 제한을 강제하는 프로그램 로직 * 독립된 컨텍스트에서 병렬로 일하는 전문 에이전트 ### 하네스 도입 효과 영상은 하네스의 주요 효과를 다음처럼 설명합니다. * **반복성:** 같은 작업을 일정한 방식으로 반복할 수 있습니다. * **강제와 자율성의 분리:** 반드시 지켜야 할 것은 시스템으로 강제하고, 나머지는 AI가 자율적으로 판단하게 합니다. * **팀 단위 축적:** 개인의 프롬프트와 노하우를 프로젝트 파일로 만들어 팀과 공유할 수 있습니다. * **세션 간 일관성:** 대화가 바뀌더라도 동일한 프로젝트 규칙과 절차를 재사용할 수 있습니다. * **장기 작업 안정성:** 작업이 길어져도 계획 문서와 규칙을 기준으로 방향을 유지할 수 있습니다. *** ## 3\. Codex 하네스의 6가지 구성요소 | 구성요소 | 핵심 역할 | 적합한 사용 상황 | | ---- | ----- | --------- | | **AGENTS.md** | AI가 항상 참고할 규칙과 프로젝트 지침 정의 | 코딩 규칙, 테스트 방법, 금지사항, 프로젝트 구조 고정 | | **Memory** | 이전 세션에서 얻은 사용자 선호와 반복 맥락 재사용 | 자주 쓰는 기술 스택, 작업 습관, 반복되는 결정 기억 | | **Skills** | 지시·자료·스크립트·템플릿을 묶은 재사용 워크플로우 | 인터뷰, 문서 작성, 배포, 디자인 검토 등의 반복 절차 | | **MCP** | AI가 외부 시스템의 정보와 기능을 사용하도록 연결 | Gmail, Slack, GitHub, Notion 등 외부 서비스 접근 | | **Hooks** | 특정 이벤트에서 프로그램 로직을 강제로 실행 | 비밀 파일 접근 차단, 명령 검사, 자동 검증과 가드레일 | | **Sub-agents** | 별도 컨텍스트를 가진 전문 에이전트에 작업 위임 | 병렬 조사·개발·검증, 생성자와 검토자 역할 분리 | *** ## 4\. AGENTS\.md: 에이전트가 따라야 할 규칙 `AGENTS.md`는 Codex가 프로젝트를 작업할 때 참고하는 **규칙 파일**입니다. 프롬프트마다 같은 내용을 반복하지 않고, 에이전트가 계속 따라야 할 지침을 파일로 고정할 수 있습니다. ### 적용 범위 영상에서는 규칙의 범위를 크게 두 가지로 설명합니다. #### 전역 규칙 모든 프로젝트에서 공통으로 적용할 지침입니다. 예시는 다음과 같습니다. * 답변과 주석에 사용할 언어 * 공통적인 코드 품질 기준 * 파일을 수정할 때 따라야 할 기본 원칙 * 테스트와 검증에 대한 공통 규칙 #### 프로젝트 규칙 특정 저장소에서만 적용할 지침입니다. * 기술 스택과 버전 * 프로젝트 디렉터리 구조 * 네이밍 규칙 * 빌드·테스트·린트 명령어 * 디자인 시스템과 컴포넌트 사용 규칙 * 수정하면 안 되는 파일 * 작업 완료 기준 ### 중첩 구조 `AGENTS.md`는 프로젝트 루트뿐 아니라 하위 디렉터리에도 둘 수 있습니다. Codex는 전역 지시와 프로젝트 루트에서 현재 작업 디렉터리까지의 지시를 순서대로 참고합니다. 이를 이용하면 다음처럼 규칙을 나눌 수 있습니다. * 프로젝트 루트: 전체 프로젝트 공통 규칙 * `frontend/`: 프론트엔드 전용 규칙 * `backend/`: 백엔드와 API 전용 규칙 * `tests/`: 테스트 작성과 실행 규칙 ### 실무에서 중요한 이유 `AGENTS.md`는 개인 컴퓨터 안에만 두는 임시 프롬프트가 아니라, 가능한 경우 저장소에 포함해 **팀이 함께 검토하고 버전 관리하는 개발 규칙**으로 운영하는 것이 좋다고 설명합니다. *** ## 5\. Memory: 세션을 넘어 반복 맥락 기억하기 Memory는 이전 대화와 작업에서 반복적으로 유용한 내용을 저장하고, 이후 세션에서 필요한 기억을 다시 불러오는 기능입니다. 영상에서는 다음과 같은 내용을 기억할 수 있다고 설명합니다. * 사용자가 선호하는 작업 방식 * 자주 사용하는 기술 스택 * 반복되는 업무 흐름 * 프로젝트 관리 방식 * 이전에 자주 발생했던 실수 * 다음 세션에서도 참고해야 할 결정 ### 활성화 방법 영상 촬영 시점에는 Memory가 기본적으로 비활성화된 기능으로 소개됩니다. Codex 앱의 설정에서 개인 맞춤 설정 영역을 통해 활성화하거나, 설정 파일을 직접 수정하거나, Codex에게 설정 변경을 요청하는 방식이 제시됩니다. ### AGENTS.md·플랜 문서와의 차이 | 장치 | 저장하는 내용 | | --- | ------- | | **AGENTS.md** | 반드시 따라야 할 명시적인 프로젝트 규칙 | | **Memory** | 대화와 작업에서 추출된 사용자 선호와 반복 맥락 | | **플랜 문서** | 현재 기능이나 프로젝트의 목표·범위·구현 순서 | Memory에 모든 것을 맡기기보다, 반드시 지켜야 할 규칙은 `AGENTS.md`에 명시하고 프로젝트별 계획은 저장소 안의 문서로 남기는 것이 안정적입니다. *** ## 6\. Skills: 반복 절차를 재사용 가능한 패키지로 만들기 Skill은 특정 업무에서 Codex가 따라야 하는 **지시, 참고 자료, 스크립트, 템플릿과 에셋을 하나로 묶은 재사용 가능한 워크플로우**입니다. 단순 프롬프트 템플릿은 텍스트 지시만 포함하지만, Skill은 다음과 같은 자료를 함께 포함할 수 있습니다. * 핵심 지침을 담은 `SKILL.md` * 세부 참고 문서 * 자동화 스크립트 * 출력 템플릿 * 이미지나 기타 에셋 ### 점진적 공개 방식 영상에서 강조하는 Skill의 장점은 필요한 모든 자료를 처음부터 컨텍스트에 넣지 않는다는 점입니다. 1. 먼저 Skill의 이름과 간단한 설명을 확인합니다. 2. 해당 Skill이 필요할 때 `SKILL.md`를 읽습니다. 3. 작업에 실제로 필요한 경우에만 참고 문서·스크립트·에셋을 추가로 읽습니다. 이 방식은 컨텍스트 사용량을 줄이면서도 전문화된 절차를 재사용할 수 있게 합니다. ### Skill로 만들기 좋은 작업 * 새로운 서비스 아이디어를 구체화하는 인터뷰 * `AGENTS.md` 생성 * 디자인 검토와 화면 QA * 정해진 형식의 보고서 작성 * 배포 전 검증 절차 * 반복적인 데이터 처리 * 코드 리뷰 체크리스트 실습에서는 **Deep Interview Skill**과 `AGENTS.md` 생성용 Skill을 활용합니다. *** ## 7\. MCP: 외부 서비스와 연결하기 MCP(Model Context Protocol)는 Codex가 기본 환경 밖의 외부 서비스와 상호작용하도록 연결하는 표준 방식입니다. 예를 들면 Codex가 다음 작업을 수행할 수 있게 합니다. * Gmail에서 메일 읽기와 답장 작성 * Slack 메시지 확인과 전송 * GitHub 저장소와 이슈·코드 확인 * Notion 문서 읽기와 작성 * 배포 서비스의 프로젝트 상태 확인 MCP를 연결하면 AI는 단순히 작업 방법을 설명하는 데서 끝나지 않고, 사용자의 승인과 권한 범위 안에서 외부 시스템을 사용해 실제 작업을 진행할 수 있습니다. *** ## 8\. Hooks: 반드시 지켜야 할 규칙 강제하기 `AGENTS.md`, Memory, Skills는 AI가 읽고 판단하여 따르는 지침입니다. 따라서 모든 상황에서 100% 지켜진다고 보장하기 어렵습니다. Hooks는 특정 실행 이벤트에 프로그램 로직을 연결하여, 중요한 규칙을 **결정론적으로 강제하는 런타임 자동화와 가드레일**입니다. ### Hook을 실행할 수 있는 시점 예시 * 세션이 시작될 때 * 사용자가 프롬프트를 제출했을 때 * AI가 도구를 사용하기 직전 * 한 작업 턴이 종료됐을 때 ### 활용 예시 * `.env`와 같은 비밀 파일 접근 차단 * 위험하거나 허용되지 않은 명령 실행 방지 * 코드 수정 후 자동 테스트 실행 * 작업 완료 전 린트·빌드 검사 * 외부 전송 전 승인 절차 적용 영상의 실무 사례에서는 환경변수와 비밀 키가 저장된 파일에 에이전트가 접근하지 못하도록 Hook으로 차단한다고 설명합니다. *** ## 9\. Sub\-agents: 병렬 작업과 전문 역할 분리 Sub-agent는 메인 에이전트가 별도의 에이전트를 생성해 작업 일부를 맡기는 기능입니다. 각 Sub-agent는 독립적인 컨텍스트에서 작업할 수 있습니다. ### 주요 활용 방식 * 서로 독립적인 여러 기능을 병렬 개발 * 조사와 구현을 분리 * 작성자와 검증자 역할 분리 * 프론트엔드·백엔드·테스트를 전문 역할로 나누기 * 메인 세션의 컨텍스트 부담 줄이기 영상에서는 서브에이전트를 단순한 속도 향상 도구가 아니라, **복잡한 작업을 전문 역할과 별도 컨텍스트로 분리하는 장치**로 설명합니다. *** ## 10\. 상황별로 선택하는 하네스 기능 | 해결하려는 문제 | 적합한 기능 | | -------- | ------ | | 같은 실수를 반복하지 않게 하고 싶다 | `AGENTS.md`, Hooks | | 이전 결정과 사용자 선호를 재사용하고 싶다 | Memory | | 반복 업무를 표준 워크플로우로 만들고 싶다 | Skills | | 외부 서비스와 데이터를 사용하고 싶다 | MCP·플러그인 | | 반드시 지켜야 할 제한이 있다 | Hooks | | 전문 작업을 분리하거나 동시에 진행하고 싶다 | Sub-agents·Worktree | | 긴 프로젝트의 방향을 유지하고 싶다 | 플랜 문서, `AGENTS.md` | 영상은 처음부터 모든 하네스를 완벽하게 설계하려 하지 말고 다음 순서로 필요한 요소를 쌓아가라고 권합니다. 1. `AGENTS.md`로 기본 규칙 정의 2. 반복되는 절차를 Skills로 분리 3. 필요한 외부 도구를 MCP로 연결 4. 중요한 제한을 Hooks로 강제 5. 병렬화와 검증이 필요하면 Sub-agents 추가 6. 반복 작업에서 얻은 선호와 맥락은 Memory로 재사용 *** ## 11\. 실습 프로젝트: Commit Hero Commit Hero는 GitHub 사용자 이름을 입력하면 공개 활동 데이터를 분석해 개발자를 RPG 캐릭터 카드로 표현하는 웹서비스입니다. ### 주요 사용자 흐름 1. 사용자가 GitHub 사용자 이름을 입력합니다. 2. 서버가 GitHub 공개 데이터를 가져옵니다. 3. 저장소·커밋·사용 언어 등의 활동을 분석합니다. 4. 개발자의 클래스, 레벨, 능력치, 스킬, 약점 등을 생성합니다. 5. 짧은 분석 보고서와 함께 RPG 카드를 보여줍니다. 6. 결과를 URL이나 파일로 공유합니다. 실습에서 최종적으로 확인된 결과에는 ‘리팩터링 성기사’ 같은 개발자 캐릭터명이 표시됐으며, URL 공유와 PDF 다운로드 기능도 구현됐습니다. *** ## 12\. 러프한 프롬프트에서 시작하기 강사는 처음부터 완벽한 요구사항을 작성하려 하지 않고 다음 정도의 러프한 아이디어로 시작합니다. > GitHub 사용자 이름을 입력하면 해당 사용자의 정보를 분석해 RPG 게임 형식의 재미있는 카드를 만들어주는 바이럴 웹서비스를 만들고 싶다. 여기서 곧바로 개발을 시작하지 않고, AI에게 **서비스를 만들기 전에 필요한 인터뷰를 진행해 달라**고 요청합니다. 이 접근의 핵심은 사용자가 처음부터 자신이 원하는 것을 모두 알고 있다는 가정을 버리는 것입니다. AI가 역으로 질문하도록 만들면 모호했던 아이디어가 선택 가능한 요구사항으로 바뀝니다. *** ## 13\. Deep Interview로 요구사항 구체화 Deep Interview Skill은 러프한 아이디어를 바탕으로 서비스의 목표, 사용자 경험, 기술 선택과 MVP 범위를 질문합니다. 실습에서 결정된 주요 요구사항은 다음과 같습니다. | 질문 항목 | 결정 내용 | | ----- | ----- | | **1차 성공 기준** | 정확한 개발자 평가보다 재미있고 공유하고 싶은 카드 생성에 우선순위 | | **서비스 분위기** | 개발자 밈과 유머 중심 | | **입력 방식** | OAuth 로그인 없이 GitHub 사용자 이름만 입력 | | **결과물** | RPG 캐릭터 카드와 짧은 분석 보고서 모두 제공 | | **공유 기능** | 결과 URL 공유와 카드 파일·PDF 저장 | | **초기 분석 방식** | 우선 규칙 기반으로 만들고 이후 AI를 붙일 수 있게 확장 | | **클래스 이름** | 웃긴 개발자 밈과 멋있는 RPG 명칭을 혼합 | | **디자인** | 다크 판타지와 SaaS 인터페이스의 혼합 | | **프론트엔드** | Next.js 기반 | | **패키지 관리** | pnpm 사용 | | **배포 대상** | Vercel | | **서비스 언어** | 한국어 | 이 과정에서 사용자는 대부분 선택지를 고르고 짧게 답변합니다. 질문에 답할수록 목표와 범위가 구체화되므로, 처음부터 긴 프롬프트를 혼자 작성하는 부담이 줄어듭니다. *** ## 14\. 인터뷰 후 바로 전체 개발을 시작하지 않는 이유 인터뷰가 끝난 뒤에도 곧바로 모든 기능을 구현하지 않습니다. 영상에서는 다음 두 단계를 먼저 수행합니다. 1. 인터뷰 결과와 구현 계획 정리 2. 백엔드 연결 없이 프론트엔드 목업 UI부터 구현 이렇게 하면 서비스의 방향과 화면 구성을 낮은 비용으로 먼저 검증할 수 있습니다. 잘못된 방향으로 백엔드와 AI 기능까지 개발한 뒤 되돌리는 일을 줄일 수 있습니다. *** ## 15\. In\-app Browser로 실제 화면 검증 Codex 앱에는 개발 중인 웹페이지를 열어볼 수 있는 내장 브라우저가 있으며, 에이전트가 브라우저를 제어해 결과를 확인할 수도 있습니다. 실습에서는 다음 작업을 수행합니다. * 로컬 개발 서버 실행 * `localhost:3000` 접속 * 메인 화면과 카드 결과 화면 확인 * 에이전트가 렌더링 결과를 직접 검증 * 영어로 생성된 인터페이스를 한국어로 변경 이 기능의 중요한 점은 코드를 작성하는 것에서 끝나지 않고, **실제로 화면이 렌더링되고 상호작용이 동작하는지 에이전트가 확인하게 할 수 있다는 것**입니다. 프론트엔드 작업에서는 다음과 같은 완료 조건을 함께 요청하는 것이 좋습니다. * 브라우저로 대상 페이지 열기 * 주요 버튼과 입력창 동작 확인 * 모바일·데스크톱 화면 점검 * 콘솔 오류 확인 * 발견한 문제를 수정한 뒤 다시 검증 *** ## 16\. 모델·추론 강도·속도 설정에 대한 설명 영상에서는 데모 당시 강사가 사용한 모델과 설정도 소개합니다. * 복잡한 개발 작업에는 높은 추론 강도 사용 * 라이브 방송에서는 빠른 진행을 위해 속도 옵션을 높임 * 속도를 높이면 결과가 빨리 나오지만 크레딧 소모도 빨라질 수 있음 * 실제 업무에서는 여러 세션을 병렬로 실행하므로 일반 속도로 충분할 수 있음 핵심은 한 작업이 가장 빨리 끝나는 것보다, 여러 작업을 병렬로 맡기고 각 에이전트가 충분히 검토하도록 운영하는 것이 더 효율적일 수 있다는 점입니다. *** ## 17\. GitHub 공개 API 연동 계획 목업 화면을 확인한 뒤 실제 GitHub 데이터를 연결합니다. 이 단계에서도 바로 구현하지 않고 필요한 결정을 다시 인터뷰합니다. ### 결정된 방향 * GitHub의 공개 데이터만 사용 * OAuth 로그인은 MVP 범위에서 제외 * 토큰 없이 호출 가능한 공개 REST API 사용 * 분석 점수는 설명 가능한 단순 규칙 기반으로 구성 * AI 기능은 후속 단계에서 추가 이후 인터뷰 결과를 바탕으로 GitHub API 연동 계획 문서를 작성합니다. *** ## 18\. 플랜 문서를 ‘외부 기억장치’로 활용하기 영상은 복잡한 작업일수록 인터뷰가 끝난 뒤 플랜 문서를 먼저 만들 것을 강조합니다. 작업이 길어지면 대화의 컨텍스트 윈도우가 점점 채워지고, 초반의 중요한 결정이 희미해질 수 있습니다. 반면 계획을 저장소 안의 파일로 남겨두면 에이전트가 대화 내용과 별개로 해당 문서를 다시 읽고 일관된 방향을 유지할 수 있습니다. 플랜 문서에는 다음 내용이 포함될 수 있습니다. * 기능의 목표 * MVP 범위와 제외 범위 * 사용자 흐름 * 데이터 계약 * API 구조 * 구현 단계 * 검증 방법 * 완료 조건 프로젝트별 계획이므로 일반적으로 전역 설정 폴더보다 **해당 프로젝트 저장소 안에 두는 방식**이 적합하다고 설명합니다. *** ## 19\. 계획을 HTML로 변환해 사람의 검토 속도 높이기 Markdown은 AI와 개발자가 구조적인 텍스트를 다루기에는 좋지만, 긴 계획을 사람이 짧은 시간 안에 검토하기에는 불편할 수 있습니다. 영상에서는 다음과 같은 요청을 사용합니다. > 지금 만든 플랜을 사람이 5분 안에 검토할 수 있는 단일 HTML 검토 화면으로 만들어줘. HTML 검토 화면에는 목표, 제외 범위, 사용자 흐름, API 계약 등이 시각적으로 정리됩니다. 이를 통해 사람이 중요한 항목을 빠르게 확인하고 승인할 수 있습니다. 이 방식은 계획뿐 아니라 다음 작업에도 응용할 수 있습니다. * 코드 리뷰 요약 * 아키텍처 변경 검토 * 데이터 흐름 확인 * 화면 요구사항 검토 * 릴리스 변경사항 검토 즉, AI에게 좋은 문서를 쓰게 하는 것뿐 아니라 **사람이 빠르게 승인할 수 있는 검토 인터페이스를 만들게 하는 것**도 하네스의 일부입니다. *** ## 20\. GitHub API 연동 결과 계획 검토 후 GitHub 공개 API를 실제 화면에 연결합니다. 사용자가 GitHub 사용자 이름을 입력하면 공개 계정 정보를 바탕으로 카드를 생성합니다. 실습 결과에서 확인된 기능은 다음과 같습니다. * GitHub 사용자 이름 입력 * 공개 계정 활동 분석 * RPG 클래스와 능력치 생성 * 짧은 분석 결과 표시 * 결과 URL 공유 * PDF 다운로드 이 시점까지는 설명 가능한 규칙 기반 분석이 중심이며, 이후 별도 작업으로 AI 생성 기능을 추가합니다. *** ## 21\. 기능 단위로 새 세션을 여는 이유 강사는 하나의 긴 대화에서 모든 기능을 계속 구현하기보다, 기능 단위로 새로운 세션을 여는 방식을 사용합니다. 예를 들어 다음처럼 분리합니다. * 세션 1: 기본 UI와 GitHub API 연동 * 세션 2: AI 기반 밈과 캐릭터 설명 생성 * 세션 3: 배포와 운영 설정 이렇게 하면 다음과 같은 장점이 있습니다. * 각 세션의 컨텍스트가 특정 기능에 집중 * 오래된 대화가 쌓여 성능이 떨어지는 문제 감소 * 독립적인 기능을 동시에 개발 가능 * 실패했을 때 영향을 받는 범위 축소 *** ## 22\. Worktree로 충돌 없이 병렬 개발하기 새로운 AI 기능은 기존 세션에서 계속 작업하지 않고, 새로운 세션과 Git Worktree를 생성해 별도의 작업 공간에서 구현합니다. Worktree를 사용하면 같은 저장소를 기반으로 하면서도 서로 다른 폴더에서 코드를 수정할 수 있습니다. ### 실습 구조 * **메인 작업 공간:** GitHub API 연동과 배포 진행 * **별도 Worktree:** OpenAI 모델을 이용한 AI 캐릭터·밈 생성 기능 구현 두 에이전트가 서로 다른 폴더에서 작업하므로 개발 중 파일 충돌이 줄어듭니다. 기능 구현이 끝나면 Worktree의 변경사항을 메인 브랜치에 병합합니다. ### Worktree가 유용한 상황 * 프론트엔드와 백엔드 동시 개발 * 기능 개발과 버그 수정 병렬 수행 * AI 기능과 배포 작업 동시 진행 * 서로 다른 해결책을 독립적으로 실험 * 여러 Codex 세션을 동시에 실행 *** ## 23\. GitHub 저장소 업로드 기본 기능이 동작하는 것을 확인한 뒤 프로젝트를 GitHub 저장소에 업로드합니다. 영상에서는 Codex가 저장소 생성과 코드 푸시 과정을 도와주며, 실제 저장소에 소스가 올라간 것을 확인합니다. 여기서 중요한 실무 원칙은 다음과 같습니다. * 로컬 검증이 끝난 상태를 먼저 저장소에 반영 * 병렬 작업은 별도 브랜치·Worktree에서 진행 * 공통 플랜과 규칙 문서는 메인 저장소에서 관리 * 기능이 완성된 뒤 검토하고 메인 브랜치에 병합 *** ## 24\. 플러그인으로 Vercel 배포하기 영상은 플러그인을 MCP와 Skills 같은 확장 기능을 설치하기 쉽게 묶어둔 번들 형태로 설명합니다. Codex에서 Vercel 플러그인을 선택한 뒤 다음과 같이 요청합니다. > Vercel을 사용해서 현재 GitHub 저장소에 올라간 프로젝트를 배포하고 싶은데 어떻게 하면 될까? 플러그인이 연결된 Vercel 계정과 프로젝트 정보를 확인하고, 저장소를 Vercel 프로젝트에 연결해 배포를 진행합니다. 이후 실제 배포 URL에서 Commit Hero가 실행되는 것을 확인합니다. 영상에서는 플러그인 목록에서 GitHub, Slack, Chrome, Notion, Gmail 등의 서비스 연결과 공식 Skills 설치도 가능하다고 소개합니다. *** ## 25\. AI 기능 추가와 Structured Output 별도 Worktree에서는 OpenAI 모델을 이용해 규칙 기반 결과보다 재미있는 캐릭터 설명과 밈을 생성하는 기능을 개발합니다. 영상에서 계획한 핵심 방향은 다음과 같습니다. * OpenAI API 연결 * 구조화된 출력(Structured Output) 사용 * 모델 결과를 정해진 데이터 구조로 받기 * 기존 카드 UI가 해당 데이터를 안정적으로 표시하도록 설계 * 기능 완성 후 메인 브랜치로 병합 Structured Output을 사용하면 모델이 자유로운 문장만 반환하는 대신, 클래스명·레벨·스킬·약점·설명처럼 애플리케이션이 요구하는 필드를 일정한 구조로 받을 수 있습니다. *** ## 26\. 환경변수와 비밀정보 보호 AI API를 사용하려면 API 키를 환경변수에 저장하고, 배포 환경인 Vercel에도 해당 환경변수를 설정해야 합니다. 영상은 실무에서 환경변수 파일이 유출되면 큰 문제가 되므로, 평소에는 에이전트가 비밀 파일에 접근하지 못하도록 Hook으로 차단한다고 설명합니다. ### 권장 원칙 * API 키를 소스 코드에 직접 작성하지 않기 * `.env` 파일을 Git 저장소에 커밋하지 않기 * 에이전트가 비밀 파일을 읽지 못하도록 차단하기 * 배포 서비스의 환경변수 관리 기능 사용 * 외부 전송과 배포 전 승인 절차 두기 * 로그에 비밀 값이 출력되지 않는지 확인하기 *** ## 27\. API 비용과 호출 제한 영상 실습에서는 두 가지 운영상 제약이 확인됩니다. ### OpenAI API 비용 AI 기능을 사용할 때마다 모델 API 요청이 발생하므로 사용량에 따라 비용이 부과됩니다. 따라서 실제 서비스에서는 다음과 같은 비용 통제 장치가 필요합니다. * 사용자별 호출 횟수 제한 * 전체 일일·월간 예산 설정 * 동일 요청 결과 캐시 * 입력 길이와 출력 토큰 제한 * 오류 발생 시 무제한 재시도 방지 * 비정상적인 요청 패턴 차단 ### GitHub 공개 API 제한 토큰 없이 GitHub 공개 API를 호출하는 방식은 구현이 간단하지만 호출 한도가 낮습니다. 라이브 시청자들이 동시에 테스트하면서 원본 IP 기준 시간당 호출 제한에 도달했고, 일부 조회가 정상적으로 처리되지 않는 상황이 발생합니다. 이 문제는 실제 서비스 설계에서 다음 사항을 검토해야 한다는 점을 보여줍니다. * 인증된 GitHub API 사용 여부 * 서버측 캐싱 * 요청 제한과 대기 안내 * 동일 사용자 정보의 중복 조회 방지 * 외부 API 장애 시 대체 화면 *** ## 28\. 영상에서 보여준 전체 개발 워크플로우 ``` flowchart TD A["러프한 서비스 아이디어"] --> B["Deep Interview"] B --> C["요구사항·MVP 확정"] C --> D["플랜 문서 작성"] D --> E["HTML로 사람 검토"] E --> F["목업 UI 구현"] F --> G["내장 브라우저 검증"] G --> H["GitHub API 연동"] H --> I["GitHub 푸시·Vercel 배포"] I --> J["Worktree에서 AI 기능 병렬 개발"] J --> K["메인 브랜치 병합·환경변수 설정"] K --> L["최종 배포와 운영 제한 확인"] ``` 이 흐름에서 하네스는 특정 기능 하나가 아니라 다음 요소들의 조합으로 나타납니다. * Deep Interview Skill로 요구사항 구체화 * 플랜 문서로 장기 작업의 방향 유지 * `AGENTS.md`로 프로젝트 규칙 고정 * 내장 브라우저로 실제 결과 검증 * Worktree로 병렬 작업 공간 분리 * 플러그인과 MCP로 GitHub·Vercel 연결 * Hooks로 비밀정보 접근 제한 * 새 세션과 Sub-agent로 전문 작업 분리 *** ## 29\. 실무에 적용할 수 있는 핵심 원칙 ### 1\. 처음부터 완벽한 프롬프트를 쓰려고 하지 않는다 러프한 아이디어를 전달한 뒤 AI에게 역으로 질문하도록 하면 요구사항을 더 쉽게 구체화할 수 있습니다. ### 2\. 인터뷰와 계획을 분리한다 인터뷰는 원하는 것을 발견하는 단계이고, 플랜은 결정된 내용을 실행 순서로 고정하는 단계입니다. ### 3\. 계획을 파일로 남긴다 대화에만 남겨두면 컨텍스트가 길어질수록 중요한 결정을 잃기 쉽습니다. 플랜 문서를 프로젝트 저장소에 저장해 외부 기억장치로 사용합니다. ### 4\. 사람의 검토 인터페이스를 따로 설계한다 Markdown 계획이 길다면 HTML 검토 화면이나 요약 대시보드로 변환해 빠르게 승인합니다. ### 5\. 구현 후 실제 화면을 검증한다 코드가 생성됐다는 사실을 완료로 보지 않고, 브라우저에서 실행·렌더링·상호작용을 확인합니다. ### 6\. 기능 단위로 세션과 작업 공간을 분리한다 한 세션에 모든 작업을 누적하지 않고, 기능별로 세션과 Worktree를 나눠 컨텍스트와 코드 충돌을 줄입니다. ### 7\. 지침과 강제를 구분한다 * AI가 판단하며 따라도 되는 내용: `AGENTS.md`, Skills * 반드시 막거나 실행해야 하는 내용: Hooks ### 8\. 외부 서비스 연동에는 운영 조건이 따라온다 MCP와 플러그인은 개발과 배포를 편리하게 하지만, 권한·비밀정보·호출 제한·API 비용을 함께 설계해야 합니다. *** ## 30\. Codex 프로젝트 시작 체크리스트 ### 기획 * 서비스를 한 문장으로 설명할 수 있는가? * AI에게 역질문 인터뷰를 요청했는가? * 핵심 사용자와 성공 기준이 정해졌는가? * MVP와 제외 범위가 구분되어 있는가? ### 하네스 * 프로젝트 루트에 `AGENTS.md`가 있는가? * 팀의 코딩·테스트·검증 규칙이 명시되어 있는가? * 반복 절차를 Skill로 분리할 필요가 있는가? * 필요한 외부 서비스를 MCP나 플러그인으로 연결했는가? * 비밀 파일과 위험 명령을 Hooks로 제한했는가? * 전문 작업을 Sub-agent에 위임할 필요가 있는가? ### 계획과 구현 * 인터뷰 결과를 플랜 문서로 저장했는가? * 목표, 제외 범위, 데이터 계약과 완료 조건이 있는가? * 긴 계획을 사람이 빠르게 검토할 화면이 있는가? * 목업 UI로 방향을 먼저 검증했는가? * 기능 단위로 세션을 분리했는가? * 병렬 작업에는 Worktree를 사용했는가? ### 검증과 배포 * 테스트·린트·빌드가 성공하는가? * 실제 브라우저에서 핵심 사용자 흐름을 검증했는가? * API 키가 코드와 로그에 노출되지 않는가? * 배포 환경변수가 올바르게 설정됐는가? * 외부 API 호출 제한과 장애 상황을 처리하는가? * AI API 비용과 호출 횟수에 상한이 있는가? *** ## 31\. 타임라인별 상세 목차 | 시간 | 내용 | | --- | --- | | **00:00** | 오늘 다룰 내용: Codex 하네스와 실전 서비스 빌드 | | **01:00** | 하네스 엔지니어링이 중요한 이유 | | **02:00** | Codex 하네스의 6가지 구성요소 | | **05:00** | 설정 경로와 `AGENTS.md`의 전역·프로젝트 규칙 | | **08:00** | Memory와 Skills의 역할 | | **11:00** | MCP, Hooks, Sub-agents | | **15:59** | Commit Hero 실습 시작 | | **20:00** | 러프한 프롬프트로 서비스 아이디어 제시 | | **21:00** | Deep Interview로 요구사항 구체화 | | **26:54** | Next.js 목업 UI 구현 요청 | | **27:59** | Codex 내장 브라우저로 화면 검증 | | **31:30** | GitHub 공개 API 연동 방향 결정 | | **33:00** | 플랜 문서 작성과 컨텍스트 관리 | | **34:43** | 플랜을 단일 HTML 검토 화면으로 변환 | | **38:00** | Codex Memory 활성화 방법 | | **38:55** | GitHub API 연동 결과 확인 | | **39:40** | 새 세션과 Worktree로 AI 기능 병렬 구현 | | **41:20** | GitHub 업로드와 Vercel 플러그인 배포 흐름 | | **45:27** | Vercel 배포 결과 확인 | | **46:00** | Hooks로 환경변수 파일 보호 | | **47:00** | Worktree 위치와 메인 브랜치 병합 | | **48:08** | AI API 비용과 호출 방식 설명 | | **48:50** | AI 기능과 배포 환경변수 확인 | | **49:16** | GitHub 공개 API 호출 제한 발생 | | **49:50** | 전체 서비스 빌드 워크플로우 정리 | *** ## 32\. 최종 정리 이 영상에서 소개하는 Codex 활용법의 핵심은 AI에게 코드를 한 번 생성해 달라고 요청하는 것이 아닙니다. 프로젝트를 안정적으로 진행하기 위한 **규칙, 인터뷰, 계획, 작업 공간, 검증, 외부 연동과 안전장치**를 하나의 반복 가능한 개발 환경으로 설계하는 것입니다. 핵심 내용을 다섯 문장으로 압축하면 다음과 같습니다. 1. **`AGENTS.md`는 AI가 계속 따라야 할 프로젝트 규칙을 고정합니다.** 2. **Skills는 반복 업무를 재사용 가능한 워크플로우로 바꿉니다.** 3. **플랜 문서는 긴 작업에서 목표를 잃지 않게 하는 외부 기억장치입니다.** 4. **새 세션과 Worktree는 여러 기능을 충돌 없이 병렬 개발하게 합니다.** 5. **MCP·플러그인·Hooks는 실제 서비스 연동과 배포를 가능하게 하지만, 권한·비밀정보·비용 제한을 함께 설계해야 합니다.** 결국 하네스 엔지니어링은 AI의 자율성을 무작정 높이는 방법이 아니라, **AI가 자율적으로 판단해도 되는 영역과 반드시 지켜야 할 영역을 구분하고, 그 경계를 문서와 시스템으로 구현하는 과정**입니다. *** ## 참고 자료 * 원본 영상: [https://www.youtube.com/watch?v=wScdyoQjj8E](https://www.youtube.com/watch?v=wScdyoQjj8E) * 라이브 전체 영상: [https://youtube.com/live/F5pr-hfyuEE](https://youtube.com/live/F5pr-hfyuEE) * 강의 자료: [https://devbrothers.ai/lectures/codex/harness-engineering/](https://devbrothers.ai/lectures/codex/harness-engineering/) * Commit Hero 소스코드: [https://github.com/devbrother2024/commit-hero](https://github.com/devbrother2024/commit-hero) * OpenAI Codex: [https://openai.com/ko-KR/codex/](https://openai.com/ko-KR/codex/) ## 작성 기준 * 영상 설명란의 공식 타임라인과 전체 한국어 자막을 기준으로 정리했습니다. * 자동 생성 자막의 명백한 오인식은 영상 문맥에 맞게 교정했습니다. * 체크리스트와 권장 원칙은 영상의 설명과 실습 흐름을 실제 프로젝트에 적용하기 쉽게 재구성한 내용입니다.

콘텐츠를 불러오는 중..