Cursor AI 프롬프트 실전 가이드: 코드 수정 요청을 정확하게 쓰는 법

AI 코딩 도구를 쓸 때 결과가 들쭉날쭉한 이유는 모델 성능만의 문제가 아닙니다. 요청이 너무 넓거나, 관련 파일이 빠졌거나, 원하는 변경 범위가 불명확하면 Cursor도 추측으로 코드를 만들 수밖에 없습니다. 좋은 프롬프트는 멋진 문장이 아니라 작업 범위를 정확히 잠그는 지시문입니다.

이 글은 Cursor에서 코드 수정, 리팩토링, 디버깅, 테스트 작성을 요청할 때 바로 써먹을 수 있는 방식으로 정리했습니다. 핵심은 “무엇을 고칠지”, “어디까지 건드릴지”, “어떻게 검증할지”를 한 번에 알려주는 것입니다.

좋은 요청은 파일, 목표, 제한, 검증을 같이 준다

“이 코드 고쳐줘”는 너무 넓습니다. Cursor가 프로젝트 전체를 추측하게 만들기 때문입니다. 대신 관련 파일, 원하는 동작, 건드리면 안 되는 범위, 실행할 테스트를 같이 적으면 결과가 훨씬 안정적입니다.

코드 수정 요청 템플릿

기능을 수정할 때는 모델에게 “전체를 새로 만들라”고 하기보다, 현재 구조를 유지하면서 필요한 부분만 바꾸게 해야 합니다.

@src/components/OrderTable.tsx
@src/lib/orders.ts

목표:
- 주문 목록에서 결제 실패 상태를 별도 배지로 보여줘.
- 기존 필터와 정렬 동작은 유지해.

제한:
- Order 타입의 public field 이름은 바꾸지 마.
- 새 패키지는 추가하지 마.
- UI 스타일은 기존 Badge 컴포넌트를 사용해.

검증:
- npm test -- OrderTable
- npm run lint

디버깅 요청은 증상보다 재현 조건이 중요하다

에러 메시지만 붙이면 Cursor는 원인을 넓게 추측합니다. 언제 발생하는지, 어떤 입력에서 깨지는지, 기대 결과와 실제 결과가 무엇인지 함께 줘야 합니다.

@src/api/auth.ts
@src/middleware/session.ts

증상:
- 로그인 후 30분이 지나면 /dashboard 진입 시 401이 발생해.

재현:
1. 테스트 계정으로 로그인
2. accessToken 만료 시간을 1분으로 낮춤
3. /dashboard 새로고침

기대:
- refreshToken이 유효하면 accessToken을 재발급하고 화면을 유지해야 함.

요청:
- 원인을 먼저 설명하고, 최소 변경 패치를 제안해.
- 보안상 토큰을 console.log로 출력하지 마.

리팩토링 요청은 “예쁘게”가 아니라 기준을 줘야 한다

리팩토링은 위험합니다. 동작은 그대로여야 하는데 코드 구조는 바뀌기 때문입니다. 따라서 어떤 기준으로 나눌지, 어떤 동작을 보존할지, 테스트를 어디까지 요구할지 적어야 합니다.

@src/pages/report.tsx

목표:
- 400줄짜리 report.tsx를 데이터 로딩, 필터 상태, 테이블 렌더링으로 분리해.

제한:
- URL query parameter 동작은 바꾸지 마.
- API 응답 타입은 그대로 유지해.
- 한 번에 큰 추상화를 만들지 말고 파일 2~3개로만 나눠.

검증:
- 기존 스냅샷 테스트가 깨지면 원인을 설명해.
- 변경 요약을 파일별로 정리해.

테스트 작성 요청은 실패 케이스를 먼저 적는다

AI에게 테스트를 맡길 때 “테스트 짜줘”라고만 하면 정상 케이스만 만들기 쉽습니다. 실제로 필요한 것은 실패 케이스, 경계값, 권한 오류, 빈 데이터입니다.

• 빈 배열이 들어왔을 때 빈 상태 화면이 보이는가
• 필수 값이 없을 때 사용자에게 확인 가능한 메시지가 나오는가
• 권한이 없는 사용자가 접근했을 때 API 호출이 막히는가
• 날짜 경계값, 페이지네이션 마지막 페이지가 깨지지 않는가

AI가 만든 패치를 검토하는 순서

Cursor가 패치를 제안했다고 바로 적용하면 안 됩니다. 먼저 변경 파일 수와 삭제량을 봐야 합니다. 작은 버그를 고치는데 파일 12개가 바뀌었다면 범위가 과합니다.

1. 요청한 파일 외에 예상하지 못한 파일이 바뀌었는지 확인합니다.
2. 타입, 테스트, 린트 결과를 봅니다.
3. 삭제된 코드가 실제로 불필요한지 확인합니다.
4. 에러를 숨기기 위해 any, 빈 catch, 무조건 return을 넣지 않았는지 봅니다.
5. 사용자가 보는 동작 기준으로 수동 확인합니다.

Cursor를 쓰지 않는 편이 나은 순간

AI 코딩 도구는 빠르지만, 모든 작업에 맞지는 않습니다. 결제, 인증, 개인정보, 권한, 데이터 삭제처럼 실수 비용이 큰 영역에서는 작은 패치와 명확한 리뷰가 우선입니다. 이때는 Cursor에게 전체 구현을 맡기기보다 원인 분석, 테스트 케이스 제안, 코드 리뷰 보조 정도로 쓰는 편이 안전합니다.

자주 묻는 질문

Cursor에 전체 코드베이스를 맡겨도 되나요?

작은 프로젝트라면 도움이 되지만, 실무에서는 관련 파일을 좁혀 주는 편이 안정적입니다. 범위가 넓을수록 모델은 추측을 많이 하게 됩니다.

프롬프트에 테스트 명령까지 꼭 넣어야 하나요?

가능하면 넣는 것이 좋습니다. AI가 만든 코드는 그럴듯해 보여도 실행되지 않을 수 있으므로, 통과해야 할 명령을 명시하면 결과 품질이 좋아집니다.

AI가 자꾸 큰 구조 변경을 제안하면 어떻게 해야 하나요?

“공개 API 유지”, “파일 2개 이하 변경”, “새 추상화 금지”, “동작 변경 금지”처럼 제한 조건을 프롬프트에 넣어야 합니다. 그래도 과하면 작은 단계로 쪼개서 요청하는 편이 낫습니다.

---

본 포스팅은 Epix AI 코딩 아카이브의 일환으로 작성되었습니다.