[OpenAI] Codex 바이브코딩 가이드: 초보자를 위한 AGENTS.md, Skills 실전 세팅법

1. 바이브코딩의 핵심

바이브코딩은 “아이디어를 자연어로 말하면 AI가 알아서 다 만들어주는 것”처럼 보이지만, 실제로는 작게 시키기 → 결과 확인 → 테스트 → 수정 지시 → 다시 확인을 반복하는 방식이 안전합니다.

Codex 공식 베스트 프랙티스도 변경만 시키고 끝내지 말고, 필요한 테스트를 만들고, 관련 체크를 실행하고, 결과를 확인하고, diff를 리뷰하라고 권합니다. 처음부터 “앱 전체 만들어줘”보다 이렇게 가야 합니다.

1. 프로젝트 설명해줘
2. 기능을 3~5개 작은 작업으로 쪼개줘
3. 첫 번째 작업만 구현해줘
4. 테스트/빌드/린트 돌려줘
5. diff를 초보자 눈높이로 설명해줘
6. 내가 확인한 뒤 다음 작업으로 넘어가

 

2. 먼저 구분해야 할 것: Prompt, AGENTS.md, Skill

구분	언제 쓰는가	설명
Prompt	한 번만 시킬 때	“이 버튼 색 바꿔줘”, “이 에러 설명해줘”
AGENTS.md	항상 지켜야 할 프로젝트 규칙	Codex가 작업 전에 읽는 프로젝트 설명서. 실행 방법, 테스트 명령, 금지 규칙을 넣음
Skill	반복되는 작업 흐름	“버그 수정 절차”, “기능 구현 절차”, “배포 전 검증”처럼 자주 쓰는 작업을 패키지화
MCP / Automations / Subagents	나중에	외부 도구 연결, 반복 자동화, 여러 에이전트 병렬 작업. 초보자는 뒤로 미뤄도 됨

 

Codex는 AGENTS.md를 작업 전에 읽어 프로젝트별 지침으로 사용합니다.

공식 문서는 AGENTS.md에 repo 구조, 실행 방법, build/test/lint 명령, PR 기준, 금지 규칙, 완료 기준을 넣는 패턴을 권장합니다.

 

3. 가장 유용한 Codex Skills 12개

처음부터 20개씩 만들지 말고, 아래 중 1~6번만 먼저 만들면 충분합니다. 공식 문서도 Skill은 한 작업에 집중하고, 입력·출력·트리거를 명확히 하라고 권합니다.

 

P0. 무조건 먼저 만들면 좋은 Skills

Skill 이름	언제 쓰나	Skill에 넣을 핵심 규칙
$project-reader	새 프로젝트를 열었을 때	폴더 구조, 실행 방법, 주요 파일, 기술스택을 초보자 말로 설명
$feature-slicer	“이런 앱 만들고 싶어”처럼 아이디어가 클 때	기능을 작은 작업 단위로 쪼개고, 한 번에 하나씩만 구현
$git-safety	Codex가 파일을 수정하기 전	git status 확인, 변경 전 checkpoint 권장, diff 요약
$bug-minimal-fix	에러·버그가 났을 때	재현 → 원인 후보 → 최소 수정 → 테스트 순서로 진행
$test-and-verify	기능 구현 후	lint/test/build 실행, 수동 확인 체크리스트 작성
$beginner-code-review	Codex가 만든 코드를 받았을 때	변경 파일, 위험한 부분, 되돌리는 방법, 다음 확인사항 설명

 

Codex는 프로젝트 디렉터리에서 파일을 읽고, 명령을 실행하고, 변경을 쓸 수 있으므로 초보자는 Git checkpoint를 특히 중요하게 봐야 합니다.

공식 Quickstart도 Codex가 코드베이스를 수정할 수 있으니 작업 전후 Git checkpoint를 고려하라고 안내합니다. Git은 소스 변경을 관리하는 분산 버전 관리 시스템이므로, 바이브코딩을 할수록 필수 안전장치가 됩니다.

 

P1. 조금 익숙해지면 추가할 Skills

Skill 이름	언제 쓰나	Skill에 넣을 핵심 규칙
$ui-builder	화면, 버튼, 레이아웃 만들 때	모바일/데스크톱 반응형, 접근성, 빈 상태, 로딩 상태 포함
$api-integration	외부 API 붙일 때	환경변수 사용, 에러 처리, 로딩 처리, mock 먼저 고려
$db-change-guard	DB 스키마나 마이그레이션 바꿀 때	파괴적 변경 금지, 백업/롤백 설명, migration 리뷰
$dependency-judge	새 패키지 설치 전	왜 필요한지, 대안, 유지보수 위험, 설치 전 사용자 승인
$docs-writer	README, 사용법, 배포 문서 만들 때	설치/실행/테스트/환경변수/트러블슈팅 문서화
$deploy-preflight	배포 직전	build 통과, env 확인, secret 노출 확인, rollback 계획

 

4. 내가 추천하는 첫 세팅 순서

초보자라면 Codex App 또는 IDE Extension으로 시작하는 게 좋습니다. Codex IDE Extension은 VS Code 같은 IDE 옆에서 Codex를 쓰거나 Codex Cloud에 작업을 맡길 수 있고, Codex는 코드를 읽고 수정하고 실행할 수 있다고 공식 문서에 설명되어 있습니다. CLI가 편하면 터미널에서 codex로 실행할 수 있고, CLI 역시 선택한 디렉터리에서 코드를 읽고 변경하고 명령을 실행할 수 있습니다.

 

추천 순서:

1. VS Code 또는 Codex App으로 시작
2. Git 설치 및 기본 명령 익히기
3. 새 프로젝트마다 git init 또는 GitHub repo 연결
4. AGENTS.md 만들기
5. P0 Skills 6개 만들기
6. 기능 하나 만들 때마다 test/lint/build/diff 확인

 

웹앱을 만들 거라면 HTML/CSS/JavaScript 기초는 반드시 같이 익히세요. MDN은 완전 초보자를 위한 웹 개발 시작 모듈과 핵심 모듈을 제공하며, 초보자가 “편안하게” 웹 개발을 시작하는 데 필요한 구조화된 학습 경로를 제시합니다.

 

5. AGENTS.md 템플릿

프로젝트 루트에 AGENTS.md를 만들고 아래처럼 시작하세요. 나중에 Codex가 같은 실수를 반복하면 여기에 규칙을 추가하면 됩니다.

# AGENTS.md

## My level
- I am a beginner developer.
- Explain important changes in simple Korean.
- Do not assume I understand framework internals.

## Workflow
- Before editing files, summarize the plan.
- Prefer small, safe changes.
- Do not rewrite the whole project unless I explicitly ask.
- After changes, explain:
  1. What changed
  2. Why it changed
  3. How to test it
  4. Any risk or limitation

## Safety
- Check `git status` before major changes.
- Ask before installing new production dependencies.
- Never expose API keys, tokens, or secrets.
- Do not modify database schema without explaining rollback.

## Verification
- Run available checks when relevant:
  - npm run lint
  - npm test
  - npm run build
- If a command does not exist, say so and suggest what should be added.
- Review the diff before saying the task is done.

## Coding style
- Prefer readable code over clever code.
- Add comments only where the logic is not obvious.
- Keep components/functions small.

 

6. Skill 만드는 기본 구조

Skill은 보통 폴더 안에 SKILL.md가 있고, 필요하면 scripts/, references/, assets/를 추가합니다.

SKILL.md에는 name과 description이 필요합니다.

Codex는 repo 위치의 .agents/skills나 사용자 위치의 $HOME/.agents/skills 등에서 Skill을 읽습니다.

 

예를 들어 개인용 Skill은 이렇게 만들 수 있습니다.

$HOME/.agents/skills/beginner-bug-minimal-fix/SKILL.md

 

예시:

---
name: beginner-bug-minimal-fix
description: Use this when the user reports a bug, error, failing test, broken UI, or says something is not working. Focus on reproducing the issue, making the smallest safe fix, and explaining it for a beginner.
---

# Beginner Bug Minimal Fix

You are helping a beginner developer fix a bug safely.

## Rules
1. Do not make broad rewrites.
2. First identify the symptom, expected behavior, and actual behavior.
3. Inspect the smallest relevant set of files.
4. If possible, reproduce the issue with an existing command or test.
5. Propose the minimal fix before editing.
6. After editing, run the most relevant check:
   - existing test
   - lint
   - build
   - manual verification steps
7. Explain the result in Korean:
   - 원인
   - 수정한 파일
   - 검증 방법
   - 남은 위험

## Do not
- Do not install new dependencies unless the user approves.
- Do not change unrelated formatting.
- Do not change public APIs unless necessary.
- Do not hide failing checks.

 

Codex에는 $skill-creator도 있어서, 직접 파일을 만들기 어렵다면 “이런 Skill을 만들어줘”라고 시킬 수 있습니다. 공식 문서는 $skill-creator가 Skill의 목적, 트리거, instruction-only 여부 등을 물어본다고 설명합니다.

 

7. 복붙해서 쓸 Skill 생성 프롬프트

처음에는 아래 3개만 만들어도 충분합니다.

7-1. 기능 쪼개기 Skill

$skill-creator

Create a local skill named beginner-feature-slicer.

Purpose:
When I describe an app idea or a big feature, break it into small beginner-friendly tasks.

Trigger phrases:
- "이런 앱 만들고 싶어"
- "기능 추가하자"
- "MVP로 쪼개줘"
- "작업 단위로 나눠줘"

Behavior:
- Ask at most 3 clarifying questions only if truly necessary.
- Prefer making reasonable assumptions.
- Output:
  1. MVP goal
  2. Small tasks in order
  3. Files likely to change
  4. Verification for each task
- Do not write code unless I explicitly approve the first task.

 

7-2. Git 안전장치 Skill

$skill-creator

Create a local skill named beginner-git-safety.

Purpose:
Use this before and after Codex makes code changes in a beginner project.

Trigger phrases:
- "수정 시작하기 전에"
- "checkpoint"
- "git 확인"
- "되돌릴 수 있게 해줘"

Behavior:
- Run or ask to run git status.
- Explain whether the working tree is clean.
- Suggest creating a branch or commit before risky edits.
- After edits, summarize git diff in beginner-friendly Korean.
- Never discard changes unless I explicitly approve.

 

7-3. 구현 후 검증 Skill

$skill-creator

Create a local skill named beginner-test-and-verify.

Purpose:
Use this after implementing or changing code.

Trigger phrases:
- "검증해줘"
- "테스트 돌려줘"
- "빌드 확인"
- "제대로 됐는지 확인"

Behavior:
- Identify available scripts from package.json or project docs.
- Run relevant checks in this order when available:
  1. formatting/lint
  2. tests
  3. build
- If no tests exist, propose a small manual verification checklist.
- Explain failures honestly.
- Do not claim success unless checks passed or limitations are clearly stated.

 

 

8. 바이브코딩할 때 매번 쓰는 작업 루프

이 루프를 습관으로 만들면 실력이 빨리 늘고, Codex가 만든 코드를 맹신하는 위험도 줄어듭니다.

나:
$feature-slicer
간단한 개인 지출 기록 웹앱을 만들고 싶어. 초보자라서 작은 작업으로 나눠줘.

Codex:
작업 1, 2, 3으로 나눔

나:
작업 1만 구현해줘. 수정 전 계획 먼저 말하고, 새 dependency는 묻고 설치해.

Codex:
계획 제시

나:
진행해.

Codex:
코드 수정

나:
$test-and-verify
검증해줘. 실패하면 원인 설명하고 최소 수정해.

Codex:
테스트/빌드/수동 확인

나:
$beginner-code-review
diff를 초보자 눈높이로 설명해줘. 위험한 부분도 말해줘.

 

9. 초보자가 반드시 배워야 할 “사람 쪽” 개발 skills

Codex Skill과 별개로, 본인이 익혀야 하는 기본기도 있습니다.

배울 것	왜 필요한가
Git 기본기	Codex가 망쳐도 되돌릴 수 있어야 함
터미널 기본 명령	설치, 실행, 테스트, 에러 확인을 직접 해야 함
HTML/CSS/JS 기초	웹앱 바이브코딩의 최소 독해력
에러 메시지 읽기	Codex에게 정확히 상황을 전달하기 위해
테스트/빌드/린트 개념	“돌아가는 것처럼 보이는 코드”와 “검증된 코드”를 구분
환경변수와 secret 관리	API 키 노출 방지
작게 요구사항 쓰기	AI에게 큰 덩어리를 던지면 실패 확률이 커짐
diff 리뷰하기	Codex가 바꾼 파일을 이해해야 함

 

10. 추천 Skill 우선순위

가장 먼저 만들 순서는 이렇습니다.

1. beginner-feature-slicer
2. beginner-git-safety
3. beginner-bug-minimal-fix
4. beginner-test-and-verify
5. beginner-code-review
6. beginner-docs-writer

 

그다음 웹앱을 만들기 시작하면:

7. beginner-ui-builder
8. beginner-api-integration
9. beginner-deploy-preflight
10. beginner-dependency-judge

 

 

11. 절대 피해야 할 바이브코딩 습관

초보자일수록 아래는 피하세요.

- 전체 앱 한 번에 다 만들어줘
- 테스트는 나중에 하자
- 에러 뜨는데 일단 계속 진행해
- 아무 패키지나 설치해도 돼
- 기존 코드 다 갈아엎어줘
- diff 안 보고 바로 커밋

 

대신 이렇게 말하세요.

✅ 한 번에 한 기능만 구현해줘
✅ 수정 전 계획 먼저 말해줘
✅ 새 dependency는 설치 전에 이유와 대안을 설명해줘
✅ 테스트/빌드 실패하면 성공이라고 말하지 마
✅ 변경한 파일과 이유를 초보자 눈높이로 설명해줘
✅ 되돌리는 방법도 알려줘

 

12. 검증 결과 요약

확인한 공식 문서 기준으로, Codex는 로컬/IDE/클라우드에서 코드를 읽고 수정하고 실행하는 코딩 에이전트이며, 작업 전후 Git checkpoint가 권장됩니다. Skills는 SKILL.md 기반의 재사용 워크플로이고, $skill-creator로 만들 수 있으며, 직접 호출 또는 설명 기반 자동 호출이 가능합니다. OpenAI의 Codex 베스트 프랙티스는 반복되는 워크플로를 Skill로 만들고, 각 Skill을 한 가지 일에 집중시키며, 테스트·리뷰·lint·build 확인을 하라고 권합니다.

 

 

참고문헌: Codex 공식 문서

• https://developers.openai.com/codex/skills
• https://developers.openai.com/codex/learn/best-practices

 

• https://developers.openai.com/codex/quickstart
• https://developers.openai.com/codex/ide
• https://developers.openai.com/codex/cli