최종 프로젝트: 아이디어에서 출시까지 한 번에 완성하기

이제는 내 앱을 하나 출시할 시간

지금까지 우리는 Codex를 설치하고, 프롬프트를 쓰고, 샌드박스와 승인 모드를 다루고, Git과 worktree로 안전하게 실험하고, 테스트와 배포까지 경험했다. 마지막 장의 목표는 단순히 "Codex를 잘 쓰는 법"을 복습하는 것이 아니다. 이제는 정말로 작은 앱 하나를 완성해 보는 것이다.

여기서 중요한 단어는 "작은"이다. 처음부터 거대한 서비스를 만들려고 하면 Codex도, 사람도 길을 잃기 쉽다. 반대로 주말 안에 만들 수 있는 MVP, 즉 최소 기능 제품을 목표로 잡으면 Codex의 장점이 선명하게 드러난다. OpenAI의 Codex 소개에서도 "예전에는 한 분기 걸리던 일을 주말 안에 출시할 수 있게 됐다"는 식의 사용 사례가 강조된다.¹ 이 말은 마법처럼 모든 일이 자동으로 끝난다는 뜻이 아니다. 범위를 잘 자르고, Codex가 작업할 수 있는 단위로 나누고, 사람이 리뷰할 지점을 정확히 잡으면 출시 속도가 달라진다는 뜻이다.

이번 장에서는 예시 프로젝트로 독서 기록 앱을 만든다고 가정하겠다. 앱 이름은 ReadSeed로 하자. 사용자는 읽은 책을 등록하고, 독서 상태를 바꾸고, 짧은 메모를 남기고, 월별 독서 현황을 볼 수 있다. 하지만 독자는 꼭 독서 앱을 따라 할 필요는 없다. 개인 가계부, 예약 관리 앱, 팀 회고 보드, 미니 CRM으로 바꿔도 흐름은 같다.

핵심은 하나다. 아이디어를 Codex에게 통째로 던지는 것이 아니라, 기획 → 설계 → 구현 → 검증 → 배포 → 회고의 흐름으로 잘게 나누어 맡기는 것이다.

주말 안에 출시할 수 있는 아이디어 고르기

앱 아이디어를 고를 때 가장 흔한 실수는 "쓸모 있어 보이는 것"을 고르는 것이다. 더 좋은 기준은 "주말 안에 배포 가능한가"다. 초보자에게 출시 가능한 앱은 기능이 적어서 허술한 앱이 아니라, 핵심 사용자가 분명하고 데이터 구조가 단순하며 외부 연동이 적은 앱이다.

Codex에게 먼저 아이디어 비교를 맡겨 보자. 이 단계에서는 코드를 만들지 않는다. 생각을 정리하는 것이 먼저다.

나는 주말 안에 출시할 수 있는 작은 웹앱을 만들고 싶어.
후보는 개인 가계부, 독서 기록 앱, 예약 관리 앱, 팀 회고 보드, 미니 CRM이야.

다음 기준으로 비교해 줘.
- 핵심 사용자
- 필수 기능 3~5개
- 데이터 모델 복잡도
- 외부 연동 필요 여부
- 배포 난이도
- 초보자가 주말 MVP로 만들기 적합한 순위

아직 코드는 만들지 말고, 표와 추천 이유만 정리해 줘.

Codex의 답변을 받은 뒤에는 사람이 현실적인 판단을 해야 한다. 예를 들어 개인 가계부는 간단해 보이지만 거래 내역, 카테고리, 월별 통계, 예산, 반복 지출까지 욕심내면 금방 복잡해진다. 예약 관리 앱은 시간 충돌, 알림, 캘린더 연동이 들어가면 난도가 올라간다. 미니 CRM은 고객, 연락 이력, 태그, 영업 단계처럼 데이터가 늘어나기 쉽다.

초보자에게 가장 다루기 쉬운 후보는 보통 독서 기록 앱이나 팀 회고 보드다. 외부 결제나 OAuth 없이도 시작할 수 있고, 데이터 모델도 비교적 단순하다. 이번 장에서는 독서 기록 앱을 선택하되, 다른 앱을 고른 독자도 같은 방식으로 바꿔 적용할 수 있게 구성하겠다.

아이디어를 확정할 때는 다음 다섯 문장을 직접 써 보면 좋다.

앱 이름: ReadSeed
핵심 사용자: 읽은 책과 읽고 싶은 책을 한곳에서 관리하고 싶은 개인 사용자
첫 출시 목표: 로그인 없이 브라우저에서 독서 목록을 만들고 상태와 메모를 관리한다
필수 기능: 책 등록, 목록 보기, 상태 변경, 메모 작성, 간단한 통계
이번 주말에 하지 않을 것: 소셜 공유, ISBN 검색, 결제, 추천 알고리즘, 모바일 앱 출시

마지막 줄이 특히 중요하다. "하지 않을 것"을 정해야 완성할 수 있다.

프로젝트 폴더를 만들고 Codex에게 먼저 문서를 쓰게 하기

이제 프로젝트 폴더를 만든다. Codex App을 쓴다면 프로젝트 폴더를 선택한 뒤 Local 환경을 선택해 내 컴퓨터에서 작업하게 한다. 공식 문서에서도 Codex App은 작업할 프로젝트 폴더를 선택하고, Local을 선택한 뒤 첫 메시지를 보내는 흐름으로 시작한다고 안내한다.² 이 방식은 초보자에게 특히 좋다. Codex가 어느 폴더 안에서 작업하는지 눈으로 확인할 수 있기 때문이다.

처음부터 "전체 앱 만들어줘"라고 하지 말자. 그 요청은 너무 넓다. 대신 Codex에게 먼저 프로젝트 문서를 만들게 한다. 이 문서는 앞으로 Codex가 길을 잃지 않게 해 주는 지도다.

현재 폴더에서 ReadSeed라는 독서 기록 웹앱을 만들 거야.
아직 코드는 작성하지 말고 docs/product-spec.md 파일만 만들어 줘.

목표:
- 주말 안에 배포 가능한 MVP 요구사항을 정리한다.

포함할 내용:
- 앱 한 줄 소개
- 핵심 사용자
- 필수 기능 5개 이하
- 화면 목록
- 데이터 모델 초안
- 하지 않을 기능
- 완료 기준

제약:
- 초보자가 이해할 수 있는 쉬운 표현으로 써 줘.
- 구현 세부 코드나 라이브러리 설치는 아직 하지 마.

완료 조건:
- docs/product-spec.md 파일이 생성되어야 한다.
- 마지막에 MVP 범위가 너무 큰지 자체 점검 코멘트를 추가해 줘.

이 프롬프트에는 대상 파일, 목표, 제약, 완료 조건이 모두 들어 있다. Codex가 성공하기 좋은 요청이다. 작업이 끝나면 바로 diff를 확인한다. 문서라고 해서 무조건 받아들이지 말고, 범위가 커졌는지 살핀다. 예를 들어 Codex가 "사용자 팔로우", "책 추천 AI", "소셜 공유" 같은 기능을 넣었다면 과감히 지운다.

다음으로 화면 목록을 조금 더 구체화한다.

방금 만든 docs/product-spec.md를 기준으로 docs/screens.md를 작성해 줘.

목표:
- MVP에 필요한 화면과 각 화면의 역할을 정리한다.

필수 화면:
- 홈/대시보드
- 책 목록
- 책 추가/수정 폼
- 책 상세 또는 메모 영역
- 설정 또는 안내 화면은 필요할 때만 포함

제약:
- 화면은 5개를 넘기지 마.
- 각 화면마다 사용자가 할 수 있는 행동을 3개 이하로 정리해 줘.
- 구현은 하지 마.

완료 조건:
- docs/screens.md가 생성된다.
- 각 화면에 필요한 데이터가 함께 적혀 있다.

이 과정을 거치면 앱이 조금씩 손에 잡힌다. 초보자는 코드를 먼저 보면 겁이 나지만, 화면과 데이터를 먼저 보면 "아, 결국 책 목록을 추가하고 보여 주는 일이구나"라고 이해할 수 있다.

기술 스택은 평범하게, 데이터 모델은 단순하게

최종 프로젝트에서 기술 스택은 멋보다 익숙함이 중요하다. 이미 앞 장들에서 Next.js나 React 기반 예제를 따라왔다면 그대로 가도 좋다. 아직 백엔드와 데이터베이스가 부담스럽다면 첫 버전은 브라우저 localStorage에 저장하는 방식으로 시작할 수 있다. localStorage는 사용자의 브라우저 안에 작은 데이터를 저장하는 기능이다. 서버가 없어도 동작하므로 MVP를 빠르게 만들 때 유용하다.

다만 나중에 로그인과 여러 기기 동기화를 넣고 싶다면 Supabase, Neon, PostgreSQL 같은 데이터베이스로 확장할 수 있다. 여기서는 초보자 기준으로 다음 선택을 추천한다.

Codex에게 기술 스택 결정을 문서화하게 하자.

ReadSeed MVP의 기술 스택을 docs/tech-stack.md로 정리해 줘.

전제:
- 초보자가 주말 안에 완성하는 프로젝트다.
- 첫 버전은 로그인 없이 localStorage에 저장한다.
- 배포는 Vercel을 우선 고려한다.

포함할 내용:
- 선택한 기술 스택
- 왜 이 선택이 MVP에 적합한지
- 나중에 확장할 때 바꿀 수 있는 부분
- 이번 버전에서 일부러 제외할 기술

제약:
- 아직 package.json이나 코드는 수정하지 마.

데이터 모델도 먼저 작게 잡는다. 독서 기록 앱의 핵심 데이터는 책이다. 처음부터 사용자, 태그, 리뷰, 독서 세션, 통계를 모두 테이블로 나누지 말자.

ReadSeed의 MVP 데이터 모델을 docs/data-model.md에 작성해 줘.

Book 모델만 먼저 설계해 줘.
필드는 다음 정도로 제한하고, 필요한 경우 이유를 적어 줘.
- id
- title
- author
- status: want-to-read | reading | finished
- rating
- memo
- createdAt
- updatedAt

제약:
- 첫 버전은 localStorage 저장을 전제로 해.
- 관계형 데이터베이스 설계로 과하게 확장하지 마.
- TypeScript 타입 예시는 포함해도 되지만 실제 코드 파일은 만들지 마.

여기까지 오면 아직 앱은 없지만, 성공 확률은 크게 올라간다. Codex가 앞으로 따라야 할 지도가 생겼기 때문이다.

AGENTS.md로 프로젝트 기억 만들기

이제 AGENTS.md를 만든다. 앞에서 배운 것처럼 AGENTS.md는 Codex에게 "이 프로젝트에서는 이렇게 일하라"고 알려 주는 프로젝트 기억이다. 새 스레드를 열어도 반복해서 설명하지 않아도 된다.

지금까지 만든 docs/product-spec.md, docs/screens.md, docs/tech-stack.md, docs/data-model.md를 읽고
프로젝트 루트에 AGENTS.md 초안을 만들어 줘.

포함할 내용:
- 프로젝트 목표
- 기술 스택
- 주요 명령어 자리표시자
- 코딩 스타일
- 테스트와 빌드 기대 기준
- 금지 사항
- Codex가 작업 후 보고해야 할 내용

금지 사항:
- MVP 범위를 넘는 기능을 임의로 추가하지 마.
- 외부 API, 로그인, 결제, 소셜 기능을 추가하지 마.
- 대량 파일 삭제나 폴더 구조 변경은 사전 확인 없이 하지 마.

완료 조건:
- AGENTS.md가 생성된다.
- 초보자가 읽어도 이해할 수 있는 문장으로 작성된다.

AGENTS.md에는 이런 내용이 들어가면 좋다.

## Project Goal
ReadSeed is a weekend MVP for tracking books.
The first release must work without login and store data in localStorage.

## Scope Rules
Do not add authentication, payments, social sharing, ISBN search, or recommendation features unless explicitly requested.

## Commands
- Install: npm install
- Dev: npm run dev
- Test: npm test
- Build: npm run build

## Done Definition
A task is done only when:
- The requested files are changed.
- Relevant tests or build commands pass.
- The final response includes changed files, commands run, and remaining risks.

이 파일은 한 번 만들고 끝나는 문서가 아니다. 프로젝트가 진행되며 계속 다듬는다. 예를 들어 테스트 명령이 npm run test로 바뀌면 AGENTS.md도 고친다. 배포 체크리스트가 생기면 추가한다. 자주 쓰는 프롬프트 규칙도 넣는다.

첫 구현은 뼈대부터 만든다

이제 드디어 코드를 만들 차례다. 하지만 여전히 한 번에 전부 만들지 않는다. 첫 작업은 프로젝트 뼈대 생성이다.

ReadSeed 앱의 첫 구현을 시작하자.

목표:
- 현재 폴더에 Next.js + TypeScript 기반 앱 뼈대를 만든다.
- 아직 복잡한 기능 구현은 하지 않는다.

작업 범위:
- package.json
- app 또는 src 디렉터리의 기본 페이지
- 기본 스타일 파일
- README.md 초안

제약:
- localStorage CRUD 구현은 다음 작업에서 한다.
- 외부 UI 라이브러리는 추가하지 마. 필요한 경우 기본 CSS나 Tailwind만 사용해.
- AGENTS.md의 범위 규칙을 따라.

완료 조건:
- npm install이 가능해야 한다.
- npm run dev로 첫 화면이 떠야 한다.
- npm run build가 통과해야 한다.
- 변경 파일과 실행한 명령을 요약해 줘.

작업이 끝나면 Codex App의 diff 패널이나 Git diff로 변경 사항을 확인한다. Codex App은 agentic coding을 위한 작업 공간으로, worktree와 cloud 환경을 통해 여러 에이전트가 병렬로 작업할 수 있도록 설계되어 있다.³ 하지만 아무리 편리해도 diff를 보지 않고 병합하면 안 된다. 초보자는 코드 전체를 완벽히 이해하지 못해도 다음은 확인할 수 있다.

• 내가 요청하지 않은 라이브러리가 추가되었는가

• 이상한 환경 변수나 비밀 키가 들어갔는가

• 파일이 과하게 많이 바뀌었는가

• 실행 명령이 실제로 통과했는가

• README에 틀린 실행 방법이 적혀 있지 않은가

첫 구현이 괜찮다면 커밋한다.

git add .
git commit -m "chore: initialize ReadSeed MVP"

이 커밋은 안전 지점이다. 이후 Codex가 이상한 방향으로 가도 여기로 돌아올 수 있다.

기능 구현은 작은 조각으로 나눈다

ReadSeed의 필수 기능은 책 등록, 목록 보기, 상태 변경, 메모 작성, 통계 보기다. 이것을 한 번에 시키면 diff가 커지고 검토가 어려워진다. 대신 기능별로 나눈다.

첫 번째 기능은 책 타입과 저장 로직이다.

ReadSeed의 Book 타입과 localStorage 저장 로직을 구현해 줘.

목표:
- 책 데이터를 브라우저 localStorage에 저장하고 불러오는 유틸 함수를 만든다.

작업 범위:
- src/types/book.ts
- src/lib/bookStorage.ts
- 필요한 테스트 파일 1개

요구사항:
- Book 타입은 docs/data-model.md를 따른다.
- addBook, updateBook, deleteBook, getBooks 함수를 제공한다.
- localStorage가 없는 환경에서도 테스트가 가능하도록 방어 코드를 둔다.

제약:
- UI 컴포넌트는 만들지 마.
- 서버 API는 만들지 마.

완료 조건:
- 관련 단위 테스트가 통과한다.
- 실행한 테스트 명령을 알려 준다.

두 번째 기능은 책 목록 UI다.

책 목록 화면을 구현해 줘.

목표:
- 저장된 책 목록을 화면에 보여 준다.

작업 범위:
- 메인 페이지 컴포넌트
- 필요한 하위 컴포넌트 2~3개
- 스타일 파일

요구사항:
- 책 제목, 저자, 상태, 평점을 보여 준다.
- 책이 없을 때 빈 상태 메시지를 보여 준다.
- 모바일 화면에서도 카드가 깨지지 않아야 한다.

제약:
- 책 추가 폼은 아직 만들지 마.
- 디자인은 단순하지만 읽기 좋게 해.

완료 조건:
- npm run build가 통과한다.
- 빈 상태와 샘플 데이터 상태를 확인한 결과를 요약한다.

세 번째 기능은 책 추가와 수정이다.

책 추가/수정 폼을 구현해 줘.

목표:
- 사용자가 책 제목, 저자, 상태, 평점, 메모를 입력하고 저장할 수 있게 한다.

작업 범위:
- BookForm 컴포넌트
- 메인 페이지와 저장 로직 연결
- 필요한 간단한 유효성 검사

요구사항:
- 제목은 필수다.
- 평점은 1~5 사이 또는 비어 있을 수 있다.
- 저장 후 목록에 바로 반영되어야 한다.
- 새로고침해도 localStorage에서 유지되어야 한다.

제약:
- 폼 라이브러리는 추가하지 마.
- 복잡한 모달 대신 단순한 인라인 폼으로 구현해.

완료 조건:
- 수동 테스트 시나리오를 함께 보고한다.
- npm run build가 통과한다.

네 번째 기능은 상태 필터와 통계다.

독서 상태 필터와 간단한 통계를 추가해 줘.

목표:
- want-to-read, reading, finished 상태별로 책을 필터링하고 요약 숫자를 보여 준다.

작업 범위:
- 메인 페이지
- 필요한 작은 컴포넌트
- 테스트가 필요하면 유틸 함수 테스트

요구사항:
- 전체, 읽고 싶음, 읽는 중, 완료 필터를 제공한다.
- 총 책 수와 완료한 책 수를 보여 준다.
- 책이 없을 때도 화면이 어색하지 않아야 한다.

제약:
- 차트 라이브러리는 추가하지 마.
- 월별 통계는 이번 작업에 포함하지 마.

완료 조건:
- npm run build가 통과한다.
- 변경 파일과 확인한 화면 상태를 요약한다.

이렇게 나누면 Codex가 실수해도 피해가 작다. 사람이 리뷰하기도 쉽다. 작업 하나가 끝날 때마다 diff를 보고, 실행하고, 테스트하고, 마음에 들면 커밋한다.

병렬 작업은 worktree와 스레드로 분리한다

기본 기능이 어느 정도 완성되면 여러 작업을 동시에 진행하고 싶어진다. 예를 들어 한 스레드에서는 UI를 다듬고, 다른 스레드에서는 테스트를 보강하고, 또 다른 스레드에서는 README를 정리할 수 있다. 이때 같은 폴더에서 동시에 작업하게 하면 충돌이 생기기 쉽다. Codex App의 병렬 작업과 Git worktree를 활용하면 각 작업을 독립된 작업 공간에서 진행할 수 있다.

초보자에게 추천하는 분리 방식은 다음과 같다.

여기서 중요한 점은 "병렬"이 "방치"가 아니라는 것이다. 각 스레드가 끝나면 사람이 diff를 보고 병합할지 결정한다. 특히 같은 파일을 여러 스레드가 수정하면 충돌이 날 수 있다. 그래서 UI 스레드는 스타일 파일 중심, 테스트 스레드는 테스트 파일 중심, 문서 스레드는 README 중심처럼 파일 범위를 나누는 것이 좋다.

UI 개선 스레드에는 이렇게 요청할 수 있다.

새 worktree 또는 별도 스레드에서 UI 개선만 진행해 줘.

목표:
- ReadSeed 첫 화면을 더 보기 좋게 다듬는다.

작업 범위:
- 페이지 컴포넌트
- 스타일 파일
- 컴포넌트 마크업

제약:
- 데이터 저장 로직은 수정하지 마.
- 새 기능을 추가하지 마.
- 외부 UI 라이브러리를 추가하지 마.

완료 조건:
- 데스크톱과 모바일에서 깨지지 않는다.
- 빈 상태, 책 목록 상태, 필터 상태를 확인한다.
- 변경한 파일과 확인 결과를 요약한다.

테스트 보강 스레드에는 이렇게 요청한다.

별도 스레드에서 테스트 보강만 진행해 줘.

목표:
- ReadSeed의 핵심 저장 로직과 필터 로직을 테스트한다.

작업 범위:
- 테스트 설정 파일
- bookStorage 테스트
- 필터/통계 유틸 테스트

제약:
- UI 디자인은 수정하지 마.
- 기능 동작을 바꾸지 마. 버그를 발견하면 먼저 보고하고 수정 허락을 받아.

완료 조건:
- npm test가 통과한다.
- 실패했던 테스트가 있다면 원인과 수정 내용을 설명한다.

문서화 스레드는 비교적 안전하지만, 실행 명령을 틀리게 적으면 초보자에게 치명적이다. README는 반드시 직접 따라 해 본다.

README.md를 초보자용으로 정리해 줘.

포함할 내용:
- 앱 소개
- 주요 기능
- 설치 방법
- 실행 방법
- 테스트 방법
- 빌드 방법
- 배포 방법
- 수동 테스트 시나리오

제약:
- 실제 package.json에 있는 명령만 적어.
- 존재하지 않는 환경 변수나 서비스를 언급하지 마.

완료 조건:
- README의 명령을 실제로 확인하고 결과를 보고해 줘.

권한과 샌드박스는 끝까지 보수적으로 둔다

최종 프로젝트에서는 Codex가 많은 일을 하게 된다. 그래서 권한을 넓게 열고 싶어진다. 하지만 출시 직전일수록 더 보수적이어야 한다. 기본 원칙은 간단하다.

읽기와 분석은 넓게 맡겨도 된다. 현재 프로젝트 안의 파일 수정도 작은 범위라면 허용할 수 있다. 그러나 프로젝트 밖 파일 수정, 비밀 키 접근, 배포 설정 변경, 외부 서비스 연결, 결제나 계정 관련 작업은 반드시 사람이 확인해야 한다.

Codex에게 권한이 필요한 작업을 시킬 때는 프롬프트에 승인 기준도 같이 적는다.

배포 설정을 점검해 줘.

권한 규칙:
- 파일을 읽고 문제를 찾는 것은 허용한다.
- 파일 수정이 필요하면 먼저 수정 계획을 제안하고 대기해.
- 환경 변수 값은 출력하지 마.
- 배포 토큰, API 키, 계정 설정은 직접 변경하지 마.

완료 조건:
- 필요한 수정 목록을 위험도별로 정리한다.
- 사람이 직접 해야 할 작업과 Codex가 수정해도 되는 작업을 구분한다.

자동으로 실행되는 작업일수록 더 조심한다. Automations는 반복 작업을 줄여 주지만, 무인으로 돌아가기 때문에 리뷰 대기열과 제한된 권한이 중요하다. Codex 자동화는 반복 작업을 예약하거나 기존 스레드를 깨워 작업을 이어가게 할 수 있지만, 프로젝트에 영향을 주는 작업은 사람 리뷰를 통과하게 설계하는 편이 안전하다.⁴

Skills, MCP, Automations로 반복 작업 정리하기

앱을 만들다 보면 같은 지시를 여러 번 반복하게 된다. "빌드하고 결과 알려 줘", "README 명령이 맞는지 확인해 줘", "모바일 화면도 봐 줘", "배포 전 체크리스트를 돌려 줘" 같은 요청이다. 이런 반복은 프로젝트 규칙으로 빼면 좋다.

AGENTS.md는 저장소 전체의 기본 규칙이다. Skills는 반복 가능한 절차를 묶는 데 좋다. MCP는 외부 도구나 서비스와 연결할 때 사용한다. Automations는 정해진 시간이나 조건에 따라 반복 작업을 실행할 때 쓴다.

초보자용 ReadSeed 프로젝트에서는 다음 정도만 만들어도 충분하다.

예를 들어 pre-release-check라는 Skill을 만든다고 생각해 보자. 내용은 이렇게 구성할 수 있다.

# pre-release-check Skill

## Goal
Before release, verify that the app is safe, usable, documented, and deployable.

## Steps
1. Read AGENTS.md and README.md.
2. Run tests and build.
3. Check empty, loading, error, and mobile states.
4. Review environment variable usage.
5. Produce a release readiness report.

## Rules
- Do not modify production settings without approval.
- Do not print secret values.
- Separate must-fix issues from nice-to-have improvements.

이 Skill을 사용하면 출시 전마다 긴 프롬프트를 다시 쓰지 않아도 된다.

pre-release-check Skill을 사용해서 ReadSeed 출시 전 점검을 실행해 줘.
결과는 must-fix, should-fix, nice-to-have로 나누어 보고해 줘.
수정은 하지 말고 먼저 보고만 해.

MCP나 플러그인은 꼭 필요한 것만 연결한다. 예를 들어 Figma 디자인이 있다면 디자인을 코드로 옮기는 데 도움이 될 수 있고, GitHub 연결이 있으면 이슈나 PR 흐름을 더 쉽게 다룰 수 있다. 하지만 작은 MVP에서는 도구를 많이 연결하는 것이 오히려 부담이 될 수 있다. "지금 이 연결이 출시를 앞당기는가?"라는 질문에 답이 없으면 나중으로 미루자.

Automations도 처음에는 읽기 전용으로 시작한다.

매일 오전 9시에 ReadSeed 프로젝트 상태를 점검하는 Automation 초안을 제안해 줘.

요구사항:
- npm test와 npm run build 결과를 요약한다.
- 실패하면 원인 후보와 관련 파일을 보고한다.
- 자동 수정이나 자동 커밋은 하지 않는다.
- 결과는 리뷰 대기 상태로 남긴다.

아직 실제 자동화는 만들지 말고 설정 초안과 위험 요소를 설명해 줘.

자동화의 첫 목적은 "내 대신 코드를 고치기"가 아니라 "내가 놓칠 일을 알려 주기"다. 신뢰가 쌓인 뒤에 작은 수정까지 맡겨도 늦지 않다.

브라우저에서 실제 사용자처럼 검증하기

빌드가 통과해도 앱이 좋은 것은 아니다. 실제로 눌러 봐야 한다. 특히 프론트엔드 앱은 버튼, 폼, 빈 상태, 모바일 화면에서 문제가 자주 나온다.

Codex에게 브라우저 검증을 맡길 때는 막연히 "테스트해 줘"라고 하지 말고 사용자 시나리오를 준다.

로컬 개발 서버에서 ReadSeed를 실제 사용자처럼 점검해 줘.

시나리오:
1. 처음 접속했을 때 빈 상태 메시지를 확인한다.
2. 책을 1권 추가한다.
3. 상태를 reading에서 finished로 바꾼다.
4. 메모를 수정한다.
5. 새로고침 후 데이터가 유지되는지 확인한다.
6. 모바일 크기에서도 주요 버튼이 보이는지 확인한다.

제약:
- 문제가 발견되면 바로 수정하지 말고 먼저 재현 단계와 원인을 보고해.
- localStorage에 테스트 데이터가 남는다면 정리 방법도 알려 줘.

완료 조건:
- 통과/실패를 시나리오별로 표로 정리한다.
- 수정이 필요한 항목은 우선순위를 붙인다.

브라우저 검증에서 자주 나오는 문제는 비슷하다. 저장 버튼을 눌러도 반응이 없거나, 새로고침하면 데이터가 사라지거나, 모바일에서 폼이 화면 밖으로 밀리거나, 빈 상태 메시지가 없어서 사용자가 무엇을 해야 할지 모르는 경우다. 이 문제들은 고급 버그가 아니다. 하지만 출시 앱의 인상을 크게 좌우한다.

수정 요청은 발견된 문제 하나씩 처리한다.

브라우저 검증에서 발견된 모바일 폼 overflow 문제만 수정해 줘.

작업 범위:
- 스타일 파일
- 필요한 경우 폼 컴포넌트의 className

제약:
- 저장 로직과 데이터 모델은 수정하지 마.
- 데스크톱 레이아웃이 크게 바뀌지 않게 해.

완료 조건:
- 375px 너비에서 폼이 화면 밖으로 넘치지 않는다.
- npm run build가 통과한다.

작은 버그를 작은 프롬프트로 고치는 습관이 마지막까지 중요하다.

배포 준비: Vercel에 올릴 수 있는 상태 만들기

이제 배포를 준비한다. Codex는 저장소, 스크린샷, 디자인, 거친 아이디어를 공유 가능한 미리보기 배포로 바꾸는 흐름에 활용될 수 있으며, OpenAI 문서에서도 Build Web Apps와 Vercel을 이용해 앱이나 웹사이트를 배포하는 사용 사례를 소개한다.⁵ 초보자는 배포를 어렵게 생각하지만, 프론트엔드 MVP라면 대부분의 작업은 "빌드가 통과하는 저장소를 GitHub에 올리고 Vercel에서 연결하는 것"이다.

먼저 Codex에게 배포 준비 상태를 점검하게 한다.

ReadSeed를 Vercel에 배포하기 전 상태를 점검해 줘.

확인할 것:
- package.json의 scripts가 올바른지
- npm run build가 통과하는지
- 환경 변수가 필요한지
- README의 배포 설명이 정확한지
- localStorage 기반 앱이라 서버 설정이 필요한지
- 배포 후 깨질 수 있는 경로 문제가 있는지

제약:
- 배포 계정 설정은 직접 변경하지 마.
- 문제가 있으면 수정 계획을 먼저 제안해.

완료 조건:
- 배포 가능/불가능을 명확히 말해 줘.
- 배포 전 반드시 고칠 항목을 따로 정리해 줘.

그다음 README에 배포 절차를 추가한다.

README.md에 Vercel 배포 방법을 초보자 기준으로 추가해 줘.

포함할 내용:
- GitHub에 push하기
- Vercel에서 New Project 선택하기
- 빌드 명령 확인하기
- 배포 후 확인할 URL
- 배포 후 수동 테스트 시나리오

제약:
- 실제 프로젝트에 없는 환경 변수는 언급하지 마.
- 너무 긴 설명보다 따라 하기 쉬운 단계로 써 줘.

배포 후에는 반드시 실제 URL에서 다시 테스트한다. 로컬에서는 잘 되던 기능이 배포 환경에서 깨질 수 있다. 특히 경로, 정적 파일, 환경 변수, 브라우저 저장소, 모바일 화면을 확인한다.

배포된 ReadSeed URL을 기준으로 출시 후 점검 체크리스트를 만들어 줘.

점검 항목:
- 첫 로딩
- 책 추가
- 새로고침 후 데이터 유지
- 상태 변경
- 메모 수정
- 모바일 화면
- 콘솔 에러
- README의 URL 업데이트

결과 형식:
- 항목
- 기대 결과
- 실제 결과를 적을 빈칸
- 통과 여부

직접 확인한 뒤 README에 실제 배포 URL을 넣는다.

## Live Demo
https://readseed-example.vercel.app

이 한 줄이 프로젝트를 "내 컴퓨터에서만 되는 코드"에서 "다른 사람에게 보여 줄 수 있는 앱"으로 바꾼다.

출시 전 최종 체크리스트

출시 직전에는 새 기능을 넣고 싶은 마음이 강해진다. 하지만 마지막 날에는 기능 추가보다 검증이 우선이다. 아래 체크리스트를 복사해서 docs/release-checklist.md로 만들어도 좋다.

기능과 사용성

• 책을 추가할 수 있다.

• 책 목록이 정상적으로 보인다.

• 책 상태를 바꿀 수 있다.

• 메모를 작성하고 수정할 수 있다.

• 새로고침 후에도 데이터가 유지된다.

• 책이 없을 때 빈 상태 안내가 보인다.

• 잘못된 입력에 대해 사용자가 이해할 수 있는 메시지가 나온다.

화면과 접근성

• 모바일 너비에서도 주요 버튼이 화면 밖으로 나가지 않는다.

• 글자 크기와 대비가 읽기 좋다.

• 버튼과 입력창의 라벨이 명확하다.

• 키보드만으로 기본 입력 흐름을 사용할 수 있다.

• 로딩 상태나 저장 중 상태가 필요한 곳에 표시된다.

• 오류가 발생했을 때 화면이 완전히 멈추지 않는다.

성능과 안정성

• npm test가 통과한다.

• npm run build가 통과한다.

• 브라우저 콘솔에 치명적인 에러가 없다.

• 불필요하게 큰 라이브러리가 추가되지 않았다.

• localStorage 데이터 파싱 실패에 대한 방어 코드가 있다.

• 삭제나 초기화 같은 위험 동작은 사용자 확인을 거친다.

보안과 개인정보

• 비밀 키가 코드나 README에 들어 있지 않다.

• .env 파일이 커밋되지 않았다.

• 환경 변수 예시는 .env.example에만 들어 있다.

• 개인정보를 수집한다면 README나 화면에 설명이 있다.

• 외부 API를 호출하지 않는다면 그 사실이 명확하다.

• 배포 서비스의 프로젝트 공개 범위를 확인했다.

문서와 배포

• README에 설치, 실행, 테스트, 빌드 방법이 있다.

• 실제 배포 URL이 적혀 있다.

• 수동 테스트 시나리오가 있다.

• MVP에서 제외한 기능이 적혀 있다.

• 알려진 제한 사항이 숨겨져 있지 않다.

• GitHub 저장소의 마지막 커밋 상태가 깨끗하다.

Codex에게도 이 체크리스트를 기준으로 리뷰를 맡길 수 있다.

ReadSeed 출시 전 최종 점검을 해 줘.

기준:
- docs/release-checklist.md
- AGENTS.md
- README.md

작업 방식:
- 먼저 파일과 설정을 읽고 문제를 찾아.
- 수정하지 말고 보고서만 작성해.
- must-fix, should-fix, nice-to-have로 분류해.
- 각 항목마다 근거 파일이나 확인 명령을 적어.

완료 조건:
- 오늘 배포해도 되는지 판단을 내려 줘.

보고서에서 must-fix가 남아 있다면 배포를 미룬다. should-fix는 상황에 따라 결정한다. nice-to-have는 다음 버전으로 넘긴다. 출시란 모든 것을 완벽하게 만드는 일이 아니라, 약속한 범위 안에서 안전하게 공개하는 일이다.

출시 후 첫 개선: 사용자 한 명을 상상하라

배포가 끝나면 앱을 직접 써 본다. 가능하면 친구 한 명에게 URL을 보내고 아무 설명 없이 써 보게 한다. 사용자가 어디서 멈추는지 보는 것이 가장 빠른 개선 방법이다.

사용자 피드백을 Codex에게 정리하게 할 수도 있다.

아래는 ReadSeed 첫 사용자 피드백이야.
이 피드백을 바탕으로 다음 버전 개선 후보를 정리해 줘.

피드백:
- 책을 추가한 뒤 어디에 저장됐는지 처음에 헷갈렸다.
- 완료한 책만 따로 보고 싶다.
- 별점이 선택 사항인지 몰랐다.
- 모바일에서 메모 입력칸이 조금 작다.

요구사항:
- 즉시 고칠 것과 다음 버전으로 미룰 것을 나눠 줘.
- MVP 범위를 크게 벗어나는 제안은 제외해.
- 각 항목의 예상 수정 파일을 적어 줘.

아직 코드는 수정하지 마.

이때도 전부 반영하지 않는다. 출시 후 첫 개선은 작아야 한다. 예를 들어 "저장되었습니다" 메시지 추가, 완료 필터 강조, 별점 선택 안내 문구, 모바일 메모 입력칸 높이 조정 정도는 좋다. 반면 "사용자 계정 추가", "책 추천 AI", "독서 모임 기능"은 다음 프로젝트급 작업이다.

개선 작업도 작은 프롬프트로 나눈다.

ReadSeed에 저장 완료 피드백만 추가해 줘.

목표:
- 사용자가 책을 추가하거나 수정했을 때 짧은 성공 메시지를 보여 준다.

작업 범위:
- 메인 페이지 또는 BookForm 컴포넌트
- 필요한 최소 스타일

제약:
- 토스트 라이브러리는 추가하지 마.
- 저장 로직은 바꾸지 마.

완료 조건:
- 책 추가 후 성공 메시지가 보인다.
- 책 수정 후 성공 메시지가 보인다.
- npm run build가 통과한다.

이렇게 하면 출시 후에도 안정적으로 개선을 이어갈 수 있다.

프로젝트 회고: Codex가 잘한 일과 사람이 해야 할 일

마지막으로 회고를 한다. 회고는 감상문이 아니라 다음 앱을 더 빨리 만들기 위한 자산 정리다. Codex에게 회고 초안을 만들게 하되, 최종 판단은 사람이 한다.

ReadSeed 프로젝트 회고 문서 docs/retrospective.md를 작성해 줘.

포함할 내용:
- 프로젝트 목표와 실제 결과
- Codex가 잘 수행한 작업
- 사람이 반드시 리뷰해야 했던 작업
- 가장 효과적이었던 프롬프트 5개
- 다음 앱에서 재사용할 AGENTS.md 규칙
- Skill로 만들 만한 반복 절차
- Automation 후보
- 보강해야 할 테스트 케이스
- 다음 버전 아이디어

제약:
- 과장하지 말고 실제 변경과 검증 결과를 기준으로 써.
- 실패나 아쉬운 점도 포함해.

회고에서 특히 구분해야 할 것은 Codex에게 계속 맡겨도 되는 일과 사람이 반드시 책임져야 하는 일이다.

Codex가 잘하는 일은 대체로 반복적이고 검증 가능한 작업이다. 문서 초안 만들기, CRUD 코드 생성, 테스트 케이스 초안 작성, README 정리, diff 요약, 간단한 UI 개선, 오류 로그 분석이 여기에 속한다.

사람이 반드시 리뷰해야 하는 일은 제품 판단과 위험 판단이다. MVP 범위 결정, 데이터 삭제 정책, 개인정보 처리, 배포 계정 설정, 외부 서비스 권한, 보안 관련 변경, 사용자에게 보여 줄 최종 문구는 사람이 책임져야 한다.

다음 앱을 위해 남겨 둘 자산도 정리한다.

## Reusable Prompts
- MVP 후보 비교 프롬프트
- product-spec 작성 프롬프트
- localStorage CRUD 구현 프롬프트
- 배포 전 점검 프롬프트
- 회고 문서 작성 프롬프트

## Reusable AGENTS.md Rules
- MVP 범위를 넘는 기능은 추가하지 않는다.
- 작업 후 변경 파일, 실행 명령, 테스트 결과를 보고한다.
- 비밀 값은 출력하지 않는다.
- 대량 삭제와 구조 변경은 사전 승인 없이는 하지 않는다.

## Future Skills
- pre-release-check
- readme-verify
- mobile-ui-review
- local-storage-safety-review

## Future Automations
- daily test/build summary
- weekly dependency audit
- README command verification

이 목록이 쌓이면 다음 프로젝트는 훨씬 빨라진다. 처음에는 앱 하나를 만들었지만, 사실은 "앱을 만드는 나만의 시스템"도 함께 만든 것이다.

최종 프로젝트 전체 진행표

마지막으로 ReadSeed를 주말 안에 완성한다고 가정한 진행표를 정리해 보자.

이 표는 빠듯하지만 현실적이다. 중요한 것은 중간에 욕심을 줄이는 것이다. 시간이 부족하면 기능을 늘리지 말고 안정성을 올린다. 책 추천보다 저장 안정성이 중요하고, 멋진 애니메이션보다 모바일에서 버튼이 눌리는 것이 중요하다.

마지막으로: Codex는 개발자를 대신하는 것이 아니라 완성까지 밀어 주는 파트너다

이 책의 첫 장에서 우리는 Codex 시대의 앱 개발이 무엇을 바꾸는지 이야기했다. 마지막 장에 도착한 지금, 답은 더 분명해졌다. Codex는 코드를 대신 써 주는 채팅창이 아니다. 프로젝트 폴더를 읽고, 파일을 고치고, 테스트를 실행하고, diff를 보여 주고, 배포 전 점검까지 함께하는 작업 파트너다.

하지만 파트너에게도 역할이 있다. Codex는 빠르게 초안을 만들고 반복 작업을 줄여 준다. 사람은 방향을 정하고, 범위를 줄이고, 위험을 판단하고, 최종 결정을 내린다. 이 균형이 맞을 때 작은 아이디어는 실제 URL을 가진 앱이 된다.

오늘 만든 ReadSeed가 완벽할 필요는 없다. 중요한 것은 완성했다는 사실이다. README가 있고, 테스트가 있고, 배포 URL이 있고, 다음 개선 목록이 있다면 이미 훌륭한 첫 출시다. 이제 당신에게는 하나의 앱뿐 아니라, 다음 앱을 더 빠르고 안전하게 만들 수 있는 작업 방식이 생겼다.

다음에는 독서 기록 앱 대신 가계부를 만들 수도 있다. 팀 회고 보드를 만들 수도 있다. 예약 관리 앱이나 미니 CRM에 도전할 수도 있다. 그때도 흐름은 같다. 작게 정하고, 문서로 고정하고, Codex에게 작은 단위로 맡기고, 사람이 리뷰하고, 테스트하고, 배포한다.

이제 Codex를 배우는 단계는 끝났다. 이제는 Codex와 함께 만드는 단계다.

참고

¹Codex | OpenAI의 AI 코딩 파트너

²App - Codex | OpenAI Developers

³Codex | AI Coding Agent

⁴Codex Mac App 가이드: 설치부터 권한, MCP, 자동화까지

⁵Deploy an app or website | Codex use cases