Tips

짧은 팁

강의 중 자주 막히는 지점만 골라 답을 적어뒀습니다. 제목을 누르면 펼쳐집니다.

환경

설치했는데 command not found가 떠요

터미널을 닫았다가 다시 여세요. 설치 직후에는 기존 터미널이 새 프로그램의 위치를 모릅니다. VS Code 안의 터미널이라면 휴지통 아이콘으로 닫고 Ctrl+`로 다시 엽니다.

그래도 안 되면 설치 자체가 실패한 겁니다. 설치 명령을 다시 실행하고 빨간 글씨가 있는지 보세요.

Port 3000 is already in use

이전에 실행한 npm run dev가 아직 살아 있습니다. 그 터미널에서 Ctrl+C로 끄거나, 못 찾겠으면:

# macOS / Linux
lsof -ti:3000 | xargs kill

Windows PowerShell은 AI에게 "3000번 포트 쓰는 프로세스 종료하는 명령"을 물어보세요. 또는 그냥 npm run dev -- -p 3001로 다른 포트를 씁니다.

.env.local을 고쳤는데 반영이 안 돼요

환경변수는 서버가 시작될 때 한 번만 읽습니다. npm run dev를 Ctrl+C로 끄고 다시 켜세요.

그래도 undefined면 두 가지를 확인:

브라우저 코드에서 쓰는 변수인데 이름이 NEXT_PUBLIC_으로 시작하지 않음
파일 이름이 .env.local이 아니라 env.local이나 .env.local.txt

화면

useState를 썼더니 에러가 나요 (use client)

Next.js App Router에서는 파일이 기본적으로 서버 컴포넌트입니다. 클릭, 입력, useState, useEffect처럼 브라우저에서 움직이는 것이 있으면 파일 첫 줄에 이걸 넣어야 합니다.

"use client";

AI에게 에러를 그대로 보여주면 바로 고쳐줍니다. 반대로 fs로 파일을 읽거나 비밀 키를 쓰는 코드에는 이 줄이 있으면 안 됩니다.

Hydration failed 에러가 떠요

서버에서 그린 화면과 브라우저에서 그린 화면이 다르다는 뜻입니다. 흔한 원인:

new Date()나 Math.random()처럼 매번 값이 바뀌는 것을 화면에 바로 출력
localStorage를 렌더링 중에 읽음 (서버에는 localStorage가 없음)
<p> 안에 <div>처럼 HTML 구조가 잘못됨

AI에게 "hydration 에러야. localStorage나 Date를 useEffect 안으로 옮겨줘"라고 하면 대부분 해결됩니다.

Tailwind 클래스를 넣었는데 스타일이 안 먹어요

오타: text-gray-500을 text-grey-500으로 쓰는 식. 에디터에서 자동완성이 뜨는지 보세요.
동적 클래스: `bg-${color}-500` 처럼 조합해서 만든 클래스는 Tailwind가 인식 못 합니다. 전체 이름을 그대로 적어야 합니다.
globals.css의 @import "tailwindcss"가 지워짐: AI가 CSS를 정리하다 지우는 경우가 있습니다.

AI에게: "이 요소에 Tailwind 스타일이 안 적용돼. 클래스 이름과 globals.css를 확인해줘."

Git

방금 커밋을 취소하고 싶어요

상황	명령
커밋은 취소, 변경은 남기기	`git reset --soft HEAD~1`
커밋도 변경도 전부 버리기	`git reset --hard HEAD~1`
이미 push한 커밋	`git revert HEAD` 후 다시 push

--hard는 되돌릴 수 없으니 실행 전에 git status로 무엇이 날아가는지 확인하세요.

.env 파일을 실수로 커밋했어요

1순위: 키를 재발급하세요. 커밋 기록에서 지워도 이미 push했다면 누군가 봤을 수 있습니다.

그다음 Git에서 제거:

git rm --cached .env.local
echo ".env.local" >> .gitignore
git commit -m "env 파일 제거"

--cached는 "Git 추적에서만 빼고 파일은 남긴다"는 뜻입니다.

conflict가 났다는데 뭘 해야 하죠?

같은 파일의 같은 부분을 두 곳에서 다르게 고쳤다는 뜻입니다. 파일을 열면 이런 표시가 있습니다.

<<<<<<< HEAD
내 쪽 내용
=======
상대 쪽 내용
>>>>>>> branch-name

둘 중 남길 것을 고르고 표시 줄을 지운 뒤 커밋하면 됩니다. AI에게 "이 파일의 conflict를 해결해줘. 로그인 관련은 내 쪽, 스타일은 상대 쪽으로"처럼 기준을 주면 대신 정리합니다.

데이터

Supabase에서 데이터를 읽는데 빈 배열만 와요

에러 없이 []만 온다면 90%는 RLS입니다. 테이블에 RLS가 켜져 있는데 정책(Policy)이 없으면 아무것도 안 보입니다.

학습 중이면: Table Editor에서 RLS를 잠시 끄고 확인
로그인을 붙였다면: "자기 user_id 행만 select" 정책이 있는지, 그리고 지금 로그인된 상태인지 확인

나머지 10%는 .from("테이블이름")의 오타입니다.

외부 API가 401 Unauthorized를 줘요

키 문제입니다. 순서대로:

.env.local의 키 앞뒤에 공백이나 따옴표가 없는지
.env.local 수정 후 npm run dev를 재시작했는지
서버 라우트에서 process.env.키이름의 이름이 파일과 정확히 같은지 (대소문자)
배포에서만 401이면 Vercel 환경변수에 추가했는지

키 값을 AI에게 보여주지 말고, "키 이름이 맞는지만 확인해줘"라고 하세요.

배포

로컬은 되는데 Vercel 배포가 실패해요

Vercel은 npm run build를 실행합니다. 로컬에서도 같은 명령을 돌려보세요.

npm run build

로컬에서도 실패하면 → 에러를 AI에게. 보통 TypeScript 타입 에러이고, npm run dev는 이걸 눈감아줍니다.

로컬은 통과하는데 Vercel만 실패하면 → Vercel 로그의 빨간 줄을 복사해 AI에게. 대개 환경변수 누락이거나 Node 버전 차이입니다.

AI 도구

AI가 같은 실수를 계속 반복해요

대화가 너무 길어져 맥락이 오염된 상태입니다.

"지금까지 한 것과 남은 것을 TODO.md에 정리해줘"
새 대화 시작
"TODO.md 읽고 [남은 조각]부터 이어서. 이전에 [실수]를 반복했으니 이번엔 [대안]으로."

그리고 그 실수가 두 번째라면 CLAUDE.md에 한 줄 추가하세요.

AI가 요청 안 한 파일까지 고쳐요

git checkout .로 전부 되돌리고, 요청에 범위를 넣으세요.

"@src/components/MenuCard.tsx 만 수정해. 다른 파일을 고쳐야 한다면 먼저 이유를 설명하고 물어봐."

그래도 반복되면 CLAUDE.md 작업 규칙에 "요청한 파일만 수정한다. 다른 파일이 필요하면 먼저 물어본다"를 넣습니다. 승인 모드를 "매번 승인"으로 두면 승인 창에서 파일 목록이 보이므로 그 자리에서 거절할 수도 있습니다.

AI는 다 됐다는데 화면에선 안 돼요

AI는 코드를 썼을 뿐 실행해보지 않은 경우가 많습니다. "다 됐다"는 말을 믿지 말고 항상 직접 확인하세요.

요청할 때 미리 막는 법:

"완료했다고 하기 전에 npm run build를 실행해서 에러가 없는지 확인해줘. 그리고 내가 브라우저에서 확인할 방법을 3단계로 알려줘."

브라우저 연결(MCP)이 있으면 "직접 열어서 눌러보고 확인해줘"까지 시킬 수 있습니다.