AI에게 코드를 맡기기 전에 작업장을 만든다
이제부터는 실제 제품을 만들기 시작한다. 하지만 바로 Cursor를 열고 "리뷰 분석 SaaS 만들어줘"라고 입력하면 안 된다. AI는 빠르게 코드를 만들 수 있지만, 프로젝트의 목적과 경계를 모르면 그럴듯한 방향으로 길을 잃는다.
1인 창업가에게 AI 코딩 도구는 주니어 개발자이자 검색 도우미이자 코드 리뷰어다. 대신 한 가지 조건이 있다. 일을 작게 나누고, 규칙을 문서로 남기고, 변경 내역을 추적할 수 있어야 한다. 이 장의 목표는 기능을 많이 만드는 것이 아니다. 앞으로 리뷰 업로드, AI 분석, 리포트 공유 기능을 안전하게 쌓을 수 있는 개발 환경을 만드는 것이다.
이번 장을 끝내면 손에 남아야 할 결과물은 네 가지다.
GitHub 저장소
로컬에서 실행되는 Next.js 앱
AI가 참고할 프로젝트 규칙 문서
로컬·배포 환경에서 분리된 환경 변수 구조
AI 생성 이미지
AI 코딩 도구는 역할을 나눠 쓴다
AI 도구를 많이 쓰는 것보다 중요한 것은 역할을 분리하는 것이다. 같은 AI에게 기획, 구현, 검토를 모두 맡기면 실수를 스스로 덮고 넘어갈 가능성이 커진다. 혼자 일하더라도 역할은 나눠야 한다.
| 역할 | 추천 도구 | 맡길 일 |
|---|---|---|
| 기획 파트너 | ChatGPT, Claude | 기능 범위 정리, 사용자 흐름, PRD 보완 |
| 코드 작성자 | Cursor, GitHub Copilot | 파일 수정, 컴포넌트 작성, Supabase 연동 코드 초안 |
| 디버깅 파트너 | ChatGPT, Claude, Cursor Chat | 에러 로그 해석, 원인 후보 정리, 수정 방향 제안 |
| 리팩터링·리뷰어 | 다른 대화창의 Claude 또는 ChatGPT | 변경된 코드 검토, 위험한 부분 찾기, 테스트 관점 제안 |
예를 들어 "리뷰 CSV 업로드 화면을 만든다"는 작업이 있다면 순서는 이렇다.
Claude나 ChatGPT에게 사용자 흐름과 완료 기준을 정리하게 한다.
Cursor에게 해당 기준에 맞는 코드 변경을 맡긴다.
로컬에서 직접 실행해 본다.
에러가 나면 로그와 변경 파일을 AI에게 보여준다.
다른 AI 대화창에
git diff를 붙여 넣고 위험한 변경이 없는지 검토시킨다.
이 방식은 조금 느려 보이지만, 혼자 만든 서비스가 커질수록 큰 차이를 만든다. 한 명의 AI가 "끝났다"고 말하는 것과 실제로 제품이 안전하게 동작하는 것은 다르다. 솔로 창업가의 역할은 코드를 한 줄씩 다 외우는 사람이 아니라, 행동을 정확히 지시하고 의심 많은 기술 리더처럼 검토하는 사람에 가깝다.1
프로젝트를 생성한다
이 책의 기본 스택은 Next.js, TypeScript, Supabase, Vercel, GitHub다. 먼저 Next.js 앱을 만든다. 패키지 매니저는 npm, pnpm, yarn 중 익숙한 것을 쓰면 된다. 여기서는 기본 npm 명령을 기준으로 설명한다.
npx create-next-app@latest review-action-ai \
--ts \
--eslint \
--tailwind \
--app \
--import-alias "@/*"
cd review-action-ai
npm run dev중간에 선택지를 묻는 프롬프트가 나오면 TypeScript, ESLint, Tailwind, App Router를 사용하는 방향으로 고르면 된다. 브라우저에서 http://localhost:3000이 열리면 첫 단계는 성공이다. 아직 리뷰 분석 기능은 없다. 지금 확인해야 할 것은 "내 컴퓨터에서 앱을 실행할 수 있다"는 사실이다.
바로 Git 저장소도 만든다.
git init
git add .
git commit -m "chore: initialize nextjs app"그리고 GitHub에서 새 저장소를 만든 뒤 연결한다.
git remote add origin https://github.com/사용자명/review-action-ai.git
git branch -M main
git push -u origin main처음부터 복잡한 브랜치 전략은 필요 없다. 다만 main에 직접 큰 변경을 쌓는 습관은 피하자. 앞으로 기능을 만들 때는 작업 단위마다 브랜치를 만든다.
git checkout -b chore/setup-ai-rules브랜치 이름은 결과보다 목적이 보이게 짓는다. fix, feat, chore, docs 정도만 써도 충분하다.
AI가 읽을 프로젝트 규칙 파일을 만든다
AI 코딩 도구의 출력 품질은 프롬프트보다 프로젝트 안에 있는 문서의 영향을 크게 받는다. 매번 "우리는 Next.js와 Supabase를 쓰고, 한국어 UI를 만들고, 보안에 조심해야 해"라고 설명할 수는 없다. 저장소 안에 규칙을 남겨야 한다.
AI 코딩 에이전트용 스타터 프로젝트들도 CLAUDE.md 같은 규칙 파일과 docs/ 폴더를 두어 제품 맥락, 사용자 스토리, 설계 원칙을 제공하는 방식을 사용한다.2 우리도 비슷한 구조를 만든다.
mkdir docs
touch docs/AI_RULES.md
touch docs/PROJECT_CONTEXT.md
touch docs/COMMANDS.mddocs/PROJECT_CONTEXT.md에는 제품의 맥락을 적는다.
# 프로젝트 맥락
이 프로젝트는 동네 음식점·카페 사장님을 위한 리뷰 분석 AI SaaS다.
사용자는 리뷰 텍스트 또는 CSV 파일을 업로드한다.
서비스는 리뷰를 분석해 다음 결과를 제공한다.
- 반복 불만
- 자주 언급되는 장점
- 이번 주 개선 액션
- 리뷰 답글 초안
- 마케팅 문구 초안
첫 버전에서 만들지 않는 것:
- 리뷰 플랫폼 자동 연동
- 자동 답글 게시
- 팀 계정 기능
- 복잡한 관리자 페이지
- 자체 AI 모델 학습docs/AI_RULES.md에는 AI가 지켜야 할 작업 규칙을 적는다.
# AI 작업 규칙
- 먼저 변경 계획을 제안하고, 그다음 코드를 수정한다.
- 한 번에 하나의 이슈만 처리한다.
- 불필요한 패키지를 추가하지 않는다. 필요하면 이유를 먼저 설명한다.
- 실제 API 키나 비밀 값은 코드, 로그, 문서에 쓰지 않는다.
- 환경 변수는 `.env.example`에 이름만 추가한다.
- Supabase 서비스 롤 키는 브라우저 코드에서 절대 사용하지 않는다.
- 데이터베이스 에러를 조용히 무시하지 않는다.
- UI 문구는 기본적으로 한국어로 작성한다.
- 변경 후 실행해야 할 명령을 마지막에 알려준다.docs/COMMANDS.md에는 자주 쓰는 명령을 모은다. 아래처럼 파일 안에 명령어와 용도를 함께 적어 두면, 나중에 AI에게 "이 프로젝트에서 확인해야 할 명령을 알려줘"라고 물었을 때 더 일관된 답을 받을 수 있다.
# 개발 명령
```bash
npm run dev # 로컬 개발 서버 실행
npm run lint # 린트 검사
npm run build # 배포 전 빌드 확인
```이 문서들은 개발자만을 위한 문서가 아니다. 앞으로 AI에게 작업을 맡길 때 "먼저 docs/PROJECT_CONTEXT.md와 docs/AI_RULES.md를 읽고 답해줘"라고 말할 수 있는 기준점이다.
폴더 구조는 기능 중심으로 잡는다
초기 Next.js 프로젝트는 app, components, lib 정도만 있어도 시작할 수 있다. 하지만 우리가 만들 서비스는 리뷰 업로드, 매장 관리, 리포트 생성, 공유 링크로 나뉜다. 폴더도 이 흐름을 반영하면 AI가 파일을 찾기 쉽다.
추천 구조는 다음과 같다.
app/
page.tsx
layout.tsx
(marketing)/
(dashboard)/
api/
components/
ui/
features/
stores/
reviews/
reports/
lib/
supabase/
ai/
utils/
types/
docs/각 폴더의 역할은 단순해야 한다.
app/: 페이지와 라우팅components/ui/: 버튼, 카드, 입력창 같은 공통 UIfeatures/stores/: 매장 정보 관련 코드features/reviews/: 리뷰 업로드와 전처리 코드features/reports/: 분석 결과와 리포트 화면 코드lib/supabase/: Supabase 클라이언트와 서버 유틸lib/ai/: AI API 호출과 프롬프트 템플릿types/: 공통 타입 정의docs/: AI와 사람이 함께 읽는 프로젝트 문서
처음부터 모든 폴더에 파일을 채울 필요는 없다. 폴더 구조는 "앞으로 어디에 무엇을 넣을지"를 정하는 지도다. AI에게 작업을 맡길 때도 "리뷰 업로드 관련 코드는 features/reviews 아래에 작성해줘"라고 말할 수 있다.
작업 단위는 이슈 하나, 브랜치 하나, 커밋 여러 개
AI가 만든 변경을 추적하려면 작업 단위를 작게 쪼개야 한다. "대시보드 전체 만들어줘"는 너무 크다. 대신 이렇게 나눈다.
랜딩 첫 화면 문구 교체
매장 정보 입력 폼 추가
리뷰 CSV 업로드 UI 추가
업로드 파일 유효성 검사 추가
AI 분석 요청 API 라우트 추가
리포트 카드 컴포넌트 추가
각 작업은 짧은 이슈로 적는다.
## 이슈: 리뷰 CSV 업로드 UI 추가
목표:
사장님이 리뷰 CSV 파일을 선택할 수 있는 업로드 영역을 만든다.
범위:
- 파일 선택 버튼
- 선택된 파일명 표시
- CSV가 아닐 때 안내 문구 표시
제외:
- 실제 Supabase Storage 업로드
- AI 분석 호출
- 결제 기능
완료 기준:
- 로컬 화면에서 파일 선택이 가능하다.
- 잘못된 파일 형식이면 한국어 오류 메시지가 보인다.
- npm run lint가 통과한다.AI에게는 이 이슈 전체를 붙여 넣고 요청한다. 그리고 반드시 이렇게 덧붙인다.
docs/PROJECT_CONTEXT.md와 docs/AI_RULES.md를 먼저 읽고,
변경 계획을 5줄 이내로 제안한 뒤 코드를 수정해줘.
한 번에 이 이슈 범위 밖의 기능은 만들지 마.커밋 메시지는 짧고 추적 가능하게 남긴다.
git add .
git commit -m "docs: add AI project rules"
git commit -m "chore: add initial feature folders"
git commit -m "feat: add review upload form"AI가 만든 변경은 반드시 git diff로 확인한다.
git diff main...HEAD모든 코드를 완벽히 이해하지 못해도 괜찮다. 대신 바뀐 파일 수, 새로 추가된 패키지, 환경 변수 추가, 인증 관련 코드, 데이터 삭제 코드, 결제 관련 코드는 직접 확인해야 한다. 이 부분은 실수 비용이 크다. 그리고 git diff나 에러 로그를 외부 AI에 붙여 넣기 전에는 실제 API 키, 고객 데이터, 개인 정보가 포함되어 있지 않은지도 한 번 더 확인하자.
환경 변수는 처음부터 분리한다
초기 프로젝트에서 가장 흔한 보안 실수는 API 키를 코드에 직접 쓰거나 .env 파일을 GitHub에 올리는 것이다. 공개 저장소가 아니어도 피해야 한다. 환경 변수 파일에는 AI API 키, Supabase 키, 결제 시크릿처럼 외부 서비스 접근 권한이 들어간다. 실제 값이 노출되면 다른 사람이 내 계정으로 비용을 발생시키거나 데이터에 접근할 수 있다. 공개 템플릿들도 .env 파일을 커밋하지 말라고 명확히 경고한다.3
루트에 .env.example을 만든다.
touch .env.example내용은 이름만 적고 실제 값은 비워 둔다.
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
OPENAI_API_KEY=
ANTHROPIC_API_KEY=그리고 로컬 개발용 파일을 만든다.
cp .env.example .env.local.env.local에는 실제 값을 넣는다. 이 파일은 Git에 올라가면 안 된다. .gitignore에 다음 항목이 있는지 확인한다.
.env
.env.local
.env*.localNext.js에서는 NEXT_PUBLIC_으로 시작하는 환경 변수가 브라우저 코드에 노출될 수 있다. 그래서 공개되어도 되는 값에만 이 접두어를 붙인다. Supabase URL과 anon key는 일반적인 클라이언트 사용을 위해 노출될 수 있지만, SUPABASE_SERVICE_ROLE_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY는 서버에서만 사용해야 한다. 특히 Supabase의 anon key는 이름 때문에 비밀 키처럼 느껴질 수 있지만, 클라이언트에서 쓰도록 설계된 키다. 대신 실제 데이터 접근은 RLS(Row Level Security) 정책으로 제한해야 한다.
기억할 기준은 간단하다.
브라우저에서 써야 하는 값:
NEXT_PUBLIC_가능비용이 발생하는 키: 서버 전용
데이터 권한을 우회할 수 있는 키: 서버 전용
결제 시크릿과 웹훅 시크릿: 서버 전용
AI에게 코드를 맡길 때도 "서비스 롤 키를 클라이언트 컴포넌트에서 쓰지 마"라고 규칙 파일에 명시해 두어야 한다.
로컬, 프리뷰, 프로덕션을 구분한다
Vercel에 배포하면 환경은 최소 세 개로 나뉜다.
로컬: 내 컴퓨터의
.env.local프리뷰: Pull Request나 브랜치 배포 환경
프로덕션: 실제 고객이 접속하는 배포 환경
초기에는 Supabase 프로젝트 하나로 시작해도 된다. 하지만 결제와 실제 고객 데이터가 들어오기 시작하면 개발용 Supabase와 운영용 Supabase를 분리하는 것이 좋다. 테스트하다가 실제 고객 데이터를 지우는 실수를 막기 위해서다.
Vercel에서는 프로젝트 설정의 Environment Variables 메뉴에 값을 넣는다. 로컬에서 잘 되는데 배포 후 안 된다면 대부분 다음 중 하나다.
Vercel에 환경 변수를 넣지 않았다.
변수 이름을 로컬과 다르게 썼다.
Supabase Auth의 사이트 URL 또는 리다이렉트 URL이 배포 주소와 맞지 않는다.
서버 전용 키를 클라이언트 코드에서 읽으려 했다.
환경 변수를 추가한 뒤 재배포하지 않았다.
처음 배포할 때는 완성된 기능이 없어도 괜찮다. "리뷰를 읽는 시간을 줄이고, 오늘 바꿀 액션을 제안합니다"라는 첫 화면만 있어도 된다. 중요한 것은 GitHub에 push하면 Vercel이 배포하고, 배포된 주소에서 앱이 열린다는 흐름을 확인하는 것이다.
첫 화면은 간단히 바꿔 둔다
다음 장에서 본격적으로 사용자 여정을 만들겠지만, 지금은 기본 Next.js 화면만 지워도 충분하다. app/page.tsx를 열고 다음 정도의 문구로 바꾼다.
export default function Home() {
return (
<main className="mx-auto flex min-h-screen max-w-3xl flex-col items-center justify-center px-6 text-center">
<p className="mb-4 text-sm font-medium text-gray-500">
음식점·카페 사장님을 위한 리뷰 분석 AI
</p>
<h1 className="text-4xl font-bold tracking-tight">
리뷰를 읽는 시간을 줄이고,
<br />오늘 바꿀 액션을 찾습니다.
</h1>
<p className="mt-6 text-lg text-gray-600">
고객 리뷰를 업로드하면 반복 불만, 칭찬 포인트, 개선 액션,
답글 초안과 마케팅 문구를 정리해 드립니다.
</p>
</main>
);
}그다음 확인한다.
npm run lint
npm run build문제가 없으면 커밋한다.
git add .
git commit -m "feat: add initial product landing copy"
git push이 작은 화면은 단순한 장식이 아니다. 앞으로 모든 기능은 이 약속을 지켜야 한다. 리뷰를 업로드하게 만드는 이유도, AI 분석을 붙이는 이유도, 리포트를 공유하게 만드는 이유도 "오늘 바꿀 액션을 찾는다"는 약속에 연결된다.
이번 장의 완료 기준
개발 환경 세팅은 도구 설치가 아니라 반복 가능한 작업 흐름을 만드는 일이다. 다음 항목을 체크하자.
Next.js 앱이 로컬에서 실행된다.
GitHub 저장소에 초기 코드가 올라갔다.
docs/PROJECT_CONTEXT.md가 있다.docs/AI_RULES.md가 있다..env.example과.env.local을 분리했다.실제 API 키를 Git에 올리지 않았다.
기능 작업은 브랜치와 작은 커밋으로 나누기로 했다.
AI에게 작업을 맡길 때 사용할 기본 요청 형식을 정했다.
이제 AI에게 코드를 맡길 준비가 됐다. 다음 장부터는 이 환경 위에서 첫 화면과 사용자 여정을 만든다. 중요한 원칙은 계속 같다. AI에게 큰 덩어리를 던지지 않는다. 작은 이슈, 명확한 완료 기준, 추적 가능한 변경으로 제품을 쌓아 간다.
참고
1The Solo Founder AI Stack (2026): What I Actually Use to Ship
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.