Cursor가 내 코드베이스를 망가뜨리지 않도록 설정하는 방법
요약
Cursor, Claude Code 등 AI 코딩 도구 사용 시 발생하는 컨텍스트 부재 문제를 해결하기 위한 가이드를 제공합니다. .cursorrules나 CLAUDE.md와 같은 설정 파일을 통해 프로젝트의 규칙과 안티 패턴을 정의함으로써 AI의 무분별한 코드 수정을 방지할 수 있습니다.
핵심 포인트
- AI 도구의 문제는 프롬프트가 아닌 컨텍스트 부재에 있음
- .cursorrules 및 CLAUDE.md를 통한 지속적 컨텍스트 유지 필요
- 프로젝트 구조, 스택, 명령어, 코딩 관례를 명시적으로 정의
- 'DO NOT' 섹션을 통해 AI의 무분별한 리팩터링 방지
만약 당신이 Cursor, Claude Code, 또는 Windsurf를 매일 사용한다면, 아마 이런 경험을 해봤을 것입니다:
새로운 채팅창을 열고 작은 수정을 요청했는데, 20분 뒤에 AI가 API 레이어를 다시 작성하고, 세 개의 새로운 의존성(dependencies)을 추가하며, "일관성을 위해서" 데이터 페칭(data-fetching) 패턴을 바꿔버린 상황 말입니다.
모델이 고장 난 것이 아닙니다. 컨텍스트(context)가 없는 것입니다.
모든 새로운 세션은 제로(zero) 상태에서 시작됩니다. 모델은 당신의 스택(stack), 관례(conventions), 또는 절대 건드려서는 안 되는 것들을 알지 못합니다. 그래서 당신은 처음 10분 동안 다시 설명하는 데 시간을 쓰고, 마지막 1시간은 되돌리는 데 사용하게 됩니다.
이것이 제가 문제를 해결한 방법입니다.
진짜 문제는 프롬프트(prompts)가 아닙니다
대부분의 개발자들은 프롬프트를 수집합니다. 메모 앱, Slack 스니펫, 오래된 채팅 스레드 등 말이죠. 이는 일회성 작업에는 도움이 되지만, 세션 문제를 해결해주지는 못합니다.
당신에게 필요한 것은 지속적인 컨텍스트(persistent context)입니다. 즉, 당신이 무엇인가를 입력하기 전에 자동으로 로드되는 규칙들입니다.
두 개의 파일이 이 역할을 수행합니다:
CLAUDE.md — Claude Code가 읽는 파일 (다른 곳에서도 프로젝트 컨텍스트로 사용 가능)
.cursorrules — Cursor가 매 세션마다 로드하는 파일 (Windsurf의 경우 .windsurfrules로 이름 변경)
이 파일들을 프로젝트 루트(project root)에 넣으세요. 끝입니다.
좋은 설정 파일에 들어갈 내용
유용한 설정 파일은 "TypeScript를 사용하고 깨끗한 코드를 작성하라"와 같은 열 줄짜리 문구가 아닙니다. 그런 것은 동작을 바꾸기에는 너무 모호합니다.
저의 설정에는 다음 내용이 포함됩니다:
프로젝트 구조(Project structure) — 페이지, 컴포넌트(components), API 라우트가 위치하는 곳
스택 + 버전(Stack + versions) — Pages Router가 아닌 Next.js 14 App Router; Zod; shadcn/ui
명령어(Commands) — npm run dev, npm run typecheck, npm run test
코딩 관례(Coding conventions) — 명명 규칙(naming), 임포트 별칭(import aliases), 서버(Server) vs 클라이언트(Client) 컴포넌트
DO NOT 섹션 — 가장 중요한 부분 (이에 대한 자세한 내용은 아래 참조)
워크플로우 노트(Workflow notes) — @folder 사용, 기존 파일 편집 선호, 최소한의 차이(minimal diffs)
다음은 저의 시간을 가장 많이 아껴준 DO NOT 섹션의 발췌본입니다:
DO NOT — 핵심 안티 패턴(Critical Anti-Patterns)
pages/디렉토리를 생성하거나 Pages Router를 사용하지 마세요- API 레이어 전체를 다시 작성하지 마세요 — 기존의 라우트 핸들러 (route handlers)를 확장하세요
- 이유를 명시하지 않고 새로운 npm 의존성 (dependencies)을 추가하지 마세요
- 관련 없는 파일에서 무분별한 리팩터링 (drive-by refactors)을 수행하지 마세요
- 서버 컴포넌트 (Server Components)가 직접 데이터를 가져올 수 있음에도
useEffect에서 데이터를 가져오지 마세요
마지막 패턴인 명시적인 안티 패턴 (anti-patterns)은 제대로 작동하는 설정과 무시되는 설정을 가르는 차이점입니다.
DO NOT 섹션은 비밀 병기입니다
AI 어시스턴트는 최적화 도구입니다. 그들은 무언가를 "개선"하고 싶어 합니다. 가드레일 (guardrails)이 없다면, 개선이란 곧 당신의 잘 작동하는 코드를 리팩터링하는 것을 의미합니다.
DO NOT 섹션은 모델에게 무엇을 건드리지 말아야 할지 알려줍니다. 구체적으로 작성하세요:
❌ 모호함
✅ 구체적임
"망가뜨리지 마세요"
"app/api/ 내의 라우트 핸들러 (route handlers)를 다시 작성하지 마세요"
"베스트 프랙티스 (best practices)를 따르세요"
"브라우저 API (browser API)가 필요하지 않은 경우 "use client"를 추가하지 마세요"
"주의하세요"
"마이그레이션 (migration) 없이 DB 컬럼을 삭제하지 마세요"
당신이 겪었던 최악의 AI 재앙들로부터 5~10개의 규칙을 추가하세요. 모델이 "도움을 주기" 위해 새로운 방식을 찾아낼 때마다 매달 업데이트하세요.
작업에는 프롬프트(Prompts), 세션에는 설정(Configs)
설정 (Configs)은 항상 켜져 있는 규칙을 처리합니다. 프롬프트 (Prompts)는 특정 작업을 처리합니다:
- 오류 디버깅 (Debug an error) → 최소한의 차이 (minimal diff)만 생성, 먼저 스택 트레이스 (stack trace)를 읽을 것
- 기능 스캐폴딩 (Scaffold a feature) → 기존 패턴과 일치시킬 것, 코딩 전 파일 목록을 나열할 것
- 배포 체크리스트 (Ship checklist) → 린트 (lint), 타입 (types), 보안 비밀 (secrets), 모바일, 테넌트 스코핑 (tenant scoping)
프롬프트를 폴더에 보관하세요. 필요할 때 채팅창에 복사해서 붙여넣으세요. 매번 같은 지침을 다시 타이핑하지 마세요.
오늘 바로 사용할 수 있는 무료 샘플
무료 샘플을 공유합니다 — Next.js 스택 설정 + 3개의 프롬프트:
GitHub: https://github.com/js91tech/ship-faster-ai-free-sample
빠른 시작 방법:
CLAUDE.md와.cursorrules를 Next.js 프로젝트 루트에 복사합니다.[CUSTOMIZE]를 검색하여 3줄(프로젝트 이름, 설명, 배포 대상)을 업데이트합니다.- 다음에 무언가 고장 나면,
01-debug-error.md를 채팅창에 붙여넣습니다.
약 2분 정도 소요됩니다.
전체 툴킷 (모든 스택을 원하는 경우)
Gumroad를 위해 전체 시스템을 패키징했습니다:
5가지 스택 설정 (stack configs) — Next.js, React + Vite, FastAPI, Express, SaaS 범용 (SaaS generic)
15개의 검증된 프롬프트 (battle-tested prompts)
DO NOT 안티 패턴 (anti-patterns) 가이드
단 한 번의 $29 결제로 즉시 ZIP 다운로드: 툴킷 받기
FAQ가 포함된 랜딩 페이지: https://shipfasterdevkit.netlify.app/
(Cursor 또는 Anthropic과 관련이 없습니다 — 그저 매번 다시 프롬프트를 입력하는 것에 지친 개발자일 뿐입니다.)
제가 확인한 결과
설정(configs)을 일관되게 사용한 후:
"왜 내 API 전체를 다시 작성했지?"라고 고민하는 세션이 줄어들었습니다.
매 채팅마다 스택의 기초를 설명하는 시간이 단축되었습니다.
기본 컨텍스트 (base context)가 이미 로드되어 있기 때문에 프롬프트가 실제로 작동합니다.
배포 체크리스트 (Ship checklist)가 늦은 밤에 놓치기 쉬운 부분들을 잡아냅니다.
개인마다 차이는 있겠지만, 무료 샘플을 시도하는 데는 비용이 들지 않습니다.
핵심 요약 (Takeaways)
세션 수준의 컨텍스트 (session-level context)를 위해서는 프롬프트보다 설정 (configs)이 더 중요합니다.
DO NOT 섹션이 가장 높은 ROI (투자 대비 효율)를 제공하는 부분입니다.
스택에 특화되어야 합니다 — 범용적인 규칙은 무시되기 마련입니다.
3줄만 커스텀하고 바로 배포하세요 — 첫날부터 과도한 엔지니어링 (over-engineer)을 하지 마세요.
샘플을 사용해 보신다면, DO NOT 목록에 무엇을 추가하고 싶은지 알려주세요. 가장 좋은 내용들을 수집하고 있습니다.
여러분의 AI 코파일럿 (AI copilot)이 제발 그만했으면 하는 행동 1위는 무엇인가요? 댓글로 남겨주세요.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기