1. AI가 프로젝트를 이해하는 방식

AI 코딩 도구는 프로젝트 폴더를 열었다고 해서 모든 파일을 사람처럼 계속 기억하는 방식으로 일하지 않습니다. 도구마다 차이는 있지만, 보통은 현재 대화 내용, 열려 있는 파일, 검색으로 찾은 파일, 사용자가 제공한 설명, 프로젝트 규칙 파일을 바탕으로 판단합니다.

그래서 기존 프로젝트를 맡길 때 가장 먼저 해야 할 일은 “이 프로젝트가 무엇인지”를 AI가 추측하게 두지 않는 것입니다. 추측이 많아질수록 엉뚱한 파일을 수정하거나, 이미 있는 규칙을 무시하거나, 비슷한 기능을 새로 만들어버릴 가능성이 커집니다.

예를 들어 AI에게 곧바로 이렇게 요청하면 위험합니다.

로그인 오류 고쳐줘.

프로젝트 규모가 작아도 AI 입장에서는 확인해야 할 것이 많습니다. 어떤 인증 방식을 쓰는지, 프론트엔드와 백엔드가 분리되어 있는지, 로그인 관련 파일이 어디 있는지, 기존 에러 처리 방식은 무엇인지 알 수 없기 때문입니다.

조금 더 안전한 요청은 이런 형태입니다.

이 프로젝트는 Next.js 기반 웹앱입니다.
로그인 화면은 app/login/page.tsx에 있고,
인증 요청은 lib/auth.ts의 login 함수에서 처리합니다.

현재 문제는 로그인 실패 시 에러 메시지가 화면에 표시되지 않는 것입니다.
우선 app/login/page.tsx와 lib/auth.ts만 확인하고,
필요한 경우에만 다른 파일을 읽어도 되는지 물어봐 주세요.

핵심은 AI에게 “무엇을 봐야 하는지”, “무엇을 건드리면 안 되는지”, “언제 확인을 요청해야 하는지”를 함께 주는 것입니다.

2. 폴더 구조와 핵심 파일 설명하기

기존 프로젝트를 AI에게 이해시킬 때 가장 효과적인 자료는 폴더 구조입니다. 다만 전체 파일 목록을 무작정 붙여넣는 방식은 좋지 않습니다. 의존성 폴더, 빌드 결과물, 캐시 파일까지 포함되면 오히려 맥락이 흐려집니다.

Git으로 관리되는 프로젝트라면 현재 추적 중인 파일 목록을 확인할 수 있습니다.

git ls-files

폴더 구조를 간단히 보고 싶다면 macOS나 Linux 환경에서 다음 명령을 사용할 수 있습니다.

find . -maxdepth 2 -type f

다만 `node_modules`, `.next`, `dist`, `build`, `.git` 같은 폴더는 보통 AI에게 설명할 필요가 없습니다. 이런 폴더는 생성물이나 외부 의존성에 가까워서, 문제 해결에 직접 필요한 경우가 아니면 제외하는 편이 안전합니다.

AI에게 전달할 때는 단순 목록보다 역할 설명이 더 중요합니다.

프로젝트 구조 요약:

app/
- Next.js App Router 페이지와 라우트가 있습니다.
- app/login/page.tsx: 로그인 화면
- app/dashboard/page.tsx: 로그인 후 진입하는 대시보드

components/
- 공통 UI 컴포넌트가 있습니다.
- components/ui/: 버튼, 입력창 같은 기본 컴포넌트

lib/
- 외부 API 호출과 공통 유틸 함수가 있습니다.
- lib/auth.ts: 로그인, 로그아웃, 세션 확인 로직
- lib/api.ts: fetch 래퍼 함수

prisma/
- 데이터베이스 스키마와 마이그레이션 관련 파일이 있습니다.

이 정도만 있어도 AI는 “어디를 먼저 읽어야 하는지” 판단하기 쉬워집니다. 특히 `lib`, `app`, `components`, `server`, `api`, `routes`, `models`, `prisma`, `db`처럼 기능의 중심이 되는 폴더는 반드시 설명해 두는 것이 좋습니다.

파일 이름만으로 의미가 불명확한 경우도 있습니다. 예를 들어 `service.ts`, `helper.ts`, `index.ts` 같은 파일은 이름만 보고 역할을 판단하기 어렵습니다. 이런 파일은 한 줄 설명을 붙여야 합니다.

lib/service.ts는 외부 결제 API와 통신하는 파일입니다.
이름은 일반적이지만 현재 결제 승인, 결제 취소, 결제 상태 조회가 모두 들어 있습니다.

3. README와 CLAUDE.md로 맥락 제공

README는 사람과 AI가 동시에 읽는 프로젝트 소개서입니다. 기존 프로젝트에 README가 비어 있거나 설치 방법만 적혀 있다면, AI가 프로젝트를 이해하는 데 필요한 정보가 부족합니다.

최소한 아래 항목은 들어가는 것이 좋습니다.

# 프로젝트 개요

이 프로젝트는 사용자가 예약을 생성하고 관리할 수 있는 웹 서비스입니다.

## 기술 스택

- Next.js
- TypeScript
- Prisma
- PostgreSQL

## 주요 기능

- 회원가입과 로그인
- 예약 생성
- 예약 목록 조회
- 관리자 예약 승인

## 주요 폴더

- app/: 페이지와 라우트
- components/: 공통 UI 컴포넌트
- lib/: API 호출, 인증, 유틸 함수
- prisma/: 데이터베이스 스키마

## 실행 방법

npm install
npm run dev

## 주의사항

- 인증 로직은 lib/auth.ts를 기준으로 수정합니다.
- 데이터베이스 스키마 변경 전에는 반드시 영향 범위를 확인합니다.

Claude Code를 쓴다면 `CLAUDE.md` 파일이 특히 유용합니다. Claude Code는 프로젝트 맥락과 작업 규칙을 담는 파일로 `CLAUDE.md`를 활용하는 것으로 알려져 있습니다. 저장소 루트에 두면 프로젝트별 지침을 유지하기 좋습니다.

Claude Code에는 프로젝트를 분석해 `CLAUDE.md` 생성을 돕는 `/init` 명령이 있는 것으로 알려져 있습니다.

/init

직접 작성한다면 README보다 조금 더 “AI 작업 지침”에 가깝게 쓰는 편이 좋습니다.

# CLAUDE.md

## 프로젝트 설명

이 프로젝트는 예약 관리 웹앱입니다.
Next.js App Router와 TypeScript를 사용합니다.

## 작업 원칙

- 기존 구조를 우선 유지합니다.
- 새 라이브러리는 사용자 승인 없이 추가하지 않습니다.
- 타입 오류를 임시로 무시하기 위해 any를 사용하지 않습니다.
- UI 컴포넌트는 components/ui의 기존 패턴을 따릅니다.
- 데이터베이스 스키마 변경이 필요하면 먼저 변경 이유와 영향 범위를 설명합니다.

## 자주 수정하는 파일

- app/login/page.tsx: 로그인 화면
- lib/auth.ts: 인증 관련 함수
- lib/api.ts: API 요청 공통 함수
- prisma/schema.prisma: 데이터베이스 스키마

## 금지 사항

- node_modules, .next, dist 폴더는 수정하지 않습니다.
- 기존 API 응답 형식을 임의로 바꾸지 않습니다.
- 환경 변수 이름을 임의로 변경하지 않습니다.

ChatGPT에 프로젝트를 설명할 때도 같은 내용을 붙여 넣으면 됩니다. ChatGPT는 로컬 저장소를 자동으로 읽지 못하는 상황이 많기 때문에, README식 요약과 핵심 파일 내용을 함께 제공하는 방식이 안정적입니다.

4. Rules로 스타일·규칙 고정

프로젝트가 커질수록 “매번 말로 설명하는 규칙”은 빠뜨리기 쉽습니다. 그래서 도구별 규칙 파일을 활용하면 좋습니다.

Cursor는 프로젝트 규칙을 `.cursor/rules` 폴더에 두는 방식을 지원하는 것으로 알려져 있습니다. 규칙 파일은 `.mdc` 형식을 사용합니다.

예시는 다음과 같습니다.

---
description: TypeScript and React coding rules
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: true
---

- Use TypeScript strictly.
- Do not use `any` unless explicitly approved.
- Follow existing component patterns before creating new components.
- Keep UI text in Korean.
- Do not add new dependencies without confirmation.

이런 규칙은 “코드 스타일”뿐 아니라 “작업 방식”까지 고정하는 데 도움이 됩니다. 예를 들어 다음과 같은 내용도 규칙으로 둘 수 있습니다.

---
description: Project safety rules
alwaysApply: true
---

- Before editing database schema, explain the impact first.
- Do not modify authentication flow without approval.
- Prefer small, focused changes.
- If requirements are ambiguous, ask before editing files.

Codex 계열 도구에서는 저장소 지침 파일로 `AGENTS.md`를 사용하는 방식이 알려져 있습니다. 사용하는 도구와 버전에 따라 동작 방식이 다를 수 있으므로, 현재 환경의 공식 문서를 확인하는 편이 안전합니다.

규칙을 너무 많이 넣는 것도 좋지 않습니다. AI가 반드시 지켜야 하는 핵심만 남기는 편이 효과적입니다.

좋은 규칙은 구체적입니다.

새 패키지를 설치하지 마세요.

더 좋은 규칙은 조건까지 포함합니다.

새 패키지가 필요하면 먼저 이유, 대안, 설치 명령어를 설명하고 승인 후 진행하세요.

반대로 아래처럼 추상적인 규칙은 효과가 약합니다.

코드를 예쁘게 작성하세요.

“예쁘게”의 기준은 사람마다 다르기 때문입니다. 기존 프로젝트에서는 추상적인 취향보다 명확한 금지 사항과 반복되는 패턴을 적는 것이 더 중요합니다.

5. 작업 범위를 좁혀 사고 방지

기존 프로젝트에서 AI를 쓸 때 가장 흔한 사고는 범위가 너무 넓을 때 발생합니다. “전체적으로 개선해줘”, “구조 정리해줘”, “버그 고쳐줘” 같은 요청은 AI가 과감하게 파일을 바꾸게 만들 수 있습니다.

작업 범위를 좁힐 때는 네 가지를 같이 지정하면 좋습니다.

목표:
로그인 실패 시 에러 메시지가 화면에 표시되게 수정합니다.

수정 허용 파일:
- app/login/page.tsx
- lib/auth.ts

수정 금지:
- 데이터베이스 스키마
- 환경 변수
- 패키지 설치
- 인증 API 응답 형식

진행 방식:
먼저 두 파일을 읽고 원인을 설명한 뒤,
수정 계획을 제시하고 승인 후 코드를 변경하세요.

이 요청은 AI에게 명확한 울타리를 만들어 줍니다. 수정 가능한 파일이 정해져 있고, 건드리면 안 되는 영역도 분명합니다. 특히 데이터베이스, 인증, 결제, 배포 설정은 작은 변경도 큰 문제로 이어질 수 있으므로 작업 전 확인 단계를 넣는 편이 안전합니다.

대규모 수정이 필요해 보일 때도 한 번에 맡기지 않는 것이 좋습니다.

전체 리팩터링은 하지 마세요.
이번 작업에서는 중복된 유효성 검사 함수만 분리합니다.
수정 대상은 lib/validation.ts와 app/signup/page.tsx로 제한합니다.

테스트나 실행 확인도 범위 안에 포함할 수 있습니다.

수정 후 다음 명령으로 타입 검사를 실행할 수 있는지 확인하세요.

npm run typecheck

단, 실제 프로젝트에 `typecheck` 스크립트가 없을 수도 있습니다. 이 경우 AI에게 먼저 `package.json`의 scripts를 확인하게 해야 합니다.

먼저 package.json의 scripts를 확인하고,
사용 가능한 검사 명령이 무엇인지 알려주세요.
없는 명령을 새로 가정하지 마세요.

기존 프로젝트를 AI에게 맡긴다는 것은 “코드를 대신 읽게 하는 일”에 가깝습니다. 잘 읽게 만들려면 프로젝트 소개, 폴더 구조, 핵심 파일, 규칙, 작업 범위가 필요합니다. 이 다섯 가지가 준비되어 있으면 ChatGPT, Claude Code, Cursor, Codex 모두에서 AI의 추측을 줄이고 더 안전하게 작업을 이어갈 수 있습니다.