책에 포함된 노트Cursor로 일하는 법: 에이전트 시대의 솔로 메이커 워크플로우

PRD부터 시작하라: 코드보다 먼저 쓰는 것

2026-05-06Views 75약 7분생성형 AI 활용

Summary

좋은 코드는 좋은 요청에서 나온다

Cursor를 쓰다 보면 가장 먼저 하고 싶은 말은 대개 이것이다.

"이 기능 만들어 줘."

문제는 이 한 문장 안에 너무 많은 빈칸이 있다는 점이다. 누구를 위한 기능인지, 어떤 상황에서 필요한지, 이번 버전에 어디까지 포함할지, 실패했을 때 어떻게 보여야 하는지, 성능이나 보안 기준은 무엇인지가 빠져 있다. 사람 개발자라면 회의에서 다시 물어볼 수 있지만, Agent는 종종 빈칸을 그럴듯하게 채운다. 그리고 그 그럴듯함이 나중에 가장 비싼 수정 비용이 된다.

PRD는 이 문제를 줄이기 위한 도구다. Product Requirements Document, 즉 제품 요구사항 문서다. 거창한 회사 문서가 아니다. 솔로 메이커에게 PRD는 "내가 정말 만들려는 것이 무엇인가"를 코드보다 먼저 고정하는 짧은 기준 문서다.

좋은 코드는 좋은 요청에서 나온다. 좋은 요청은 대개 먼저 쓴 문서에서 시작된다.

PRD부터 시작하라: 코드보다 먼저 쓰는 것 AI 생성 이미지

Agent를 작성자가 아니라 사고 파트너로 쓰기

PRD를 쓸 때 Cursor Agent를 바로 작성자로 쓰면 결과가 평범해지기 쉽다. Agent는 문서를 잘 꾸며 줄 수 있지만, 제품 판단을 대신해 주지는 못한다. 먼저 해야 할 일은 초안 작성을 맡기는 것이 아니라, 생각의 빈틈을 찾게 하는 것이다.

Cursor에서 Agent를 열고, 관련 자료를 @로 연결한다. 예를 들면 다음과 같다.

@docs/product-notes.md
@docs/user-interviews.md
@src/app/dashboard

이 자료를 바탕으로 새 대시보드 필터 기능의 PRD를 작성하려고 해.
아직 PRD를 쓰지 말고, 먼저 문제 배경, 대상 사용자, 기존 흐름, 위험한 가정, 빠진 정보가 무엇인지 정리해 줘.
추정하지 말고 먼저 확인 질문을 해줘.

핵심은 마지막 문장이다. "추정하지 말고 먼저 확인 질문을 해줘." PRD 작성 전에 Agent에게 확인 질문을 하게 만들면, 숨어 있던 가정이 드러난다. Cursor를 PRD 초안 생성기로 쓰기보다 사고 파트너로 쓰라는 조언은 여러 실무형 Cursor 워크플로우에서도 반복해서 강조된다.¹

Agent가 물어볼 질문은 이런 식이어야 한다.

이 기능은 어떤 사용자의 어떤 문제를 해결하나?
사용자는 이 기능을 쓰기 직전에 무엇을 하고 있나?
이번 버전에서 반드시 필요한 것은 무엇이고, 나중으로 미룰 수 있는 것은 무엇인가?
기존 화면이나 데이터 구조 중 재사용해야 할 것은 무엇인가?
실패, 빈 상태, 권한 없음 상태에서는 무엇을 보여줘야 하나?
성공 여부는 어떤 기준으로 판단할 수 있나?

이 질문에 답하는 과정에서 이미 절반의 설계가 끝난다. 코드를 쓰기 전에 제품의 모양이 선명해지기 때문이다.

미니 PRD에 반드시 들어갈 것

솔로 메이커에게 필요한 것은 20쪽짜리 문서가 아니다. 기능 하나를 안전하게 만들 수 있을 정도의 미니 PRD면 충분하다. 다만 짧아도 빠지면 안 되는 항목이 있다.

1. 한 문장 문제 정의

기능 이름이 아니라 문제를 쓴다.

나쁜 예:

알림 설정 기능을 만든다.

좋은 예:

사용자가 너무 많은 알림을 받아 중요한 결제 실패 알림까지 놓치고 있으므로, 알림 종류별로 수신 채널을 직접 조정할 수 있게 한다.

문제 정의가 선명하면 Agent가 불필요한 기능을 덧붙일 가능성이 줄어든다.

2. 목표 사용자와 핵심 사용 여정

"모든 사용자"는 좋은 대상 사용자가 아니다. 사용 직전의 상황을 적어야 한다.

대상 사용자:
- 유료 워크스페이스의 소유자 또는 관리자
- 팀 알림이 많아 결제, 초대, 리포트 관련 알림을 구분하고 싶은 사용자

핵심 여정:
1. 사용자가 설정 > 알림으로 이동한다.
2. 알림 종류별로 이메일, 푸시, SMS 수신 여부를 확인한다.
3. 원하는 채널을 켜거나 끈다.
4. 저장 후 다음 알림부터 변경된 설정이 적용된다.

3. 우선순위가 있는 기능 목록

모든 기능을 같은 중요도로 쓰면 Agent는 무엇을 먼저 구현해야 할지 모른다. P0, P1, P2처럼 우선순위를 나눈다.

P0
- 알림 종류별 이메일/푸시 수신 여부 변경
- 저장 성공/실패 상태 표시
- 기존 사용자에게 기본값 적용

P1
- SMS 수신 여부 표시
- 마지막 저장 시각 표시

P2
- 알림 미리보기
- 추천 설정 자동 적용

우선순위는 구현 순서와 범위를 통제하는 장치다.

4. 포함 범위와 제외 범위

PRD에서 가장 중요한 부분 중 하나는 "이번에 하지 않을 것"이다. Agent는 종종 친절하게 범위를 넓힌다. 그 친절함이 제품을 무겁게 만든다.

포함 범위:
- 워크스페이스 단위 알림 설정
- 이메일과 푸시 채널
- 결제 실패, 댓글, 주간 요약 알림 타입

제외 범위:
- 마케팅 이메일 구독 관리
- 관리자별 세부 권한 설정
- 알림 템플릿 편집기
- SMS 실제 발송 연동

제외 범위가 있으면 나중에 Agent가 갑자기 새 테이블, 새 권한 체계, 새 UI를 만들 때 "PRD 밖"이라고 되돌릴 수 있다.

5. 주요 UX 흐름

화면의 세부 디자인을 모두 그릴 필요는 없다. 대신 사용자가 어떤 순서로 보고, 클릭하고, 피드백을 받는지 적는다.

UX 흐름:
1. 설정 화면 진입 시 현재 알림 설정을 불러온다.
2. 로딩 중에는 기존 설정 영역에 skeleton을 표시한다.
3. 사용자가 토글을 변경하면 저장 버튼이 활성화된다.
4. 저장 성공 시 toast로 "알림 설정을 저장했습니다"를 표시한다.
5. 저장 실패 시 변경값은 화면에 유지하고, 다시 시도 버튼을 제공한다.

여기까지 적으면 Agent는 "대충 설정 페이지"가 아니라 상태가 있는 제품 흐름을 구현하게 된다.

6. 기술 구조와 데이터 변경

PRD는 제품 문서지만, Cursor와 함께 쓸 때는 기술 힌트도 들어가야 한다. 특히 기존 구조를 재사용해야 할 때 중요하다.

기술 메모:
- 기존 settings API 패턴을 따른다.
- 새 패키지는 추가하지 않는다.
- notification_preferences 테이블을 사용한다.
- 워크스페이스 소유자와 관리자만 수정 가능하다.
- 변경 이벤트는 analytics.track('notification_preferences_updated')로 기록한다.

기술 메모는 상세 설계가 아니다. Agent가 구현 방향을 임의로 해석하지 않게 만드는 최소한의 울타리다.

모호한 요구를 검증 가능한 기준으로 바꾸기

PRD에서 가장 위험한 표현은 그럴듯하지만 검증할 수 없는 말이다.

사용하기 쉽게
빠르게
깔끔하게
좋은 경험으로
안정적으로

이 말들은 방향으로는 쓸 수 있지만, 구현 기준으로는 부족하다. Cursor에게는 검증 가능한 문장으로 바꿔 줘야 한다.

예를 들어 "사용하기 쉽게"는 이렇게 바꿀 수 있다.

사용자 스토리:
워크스페이스 관리자로서, 나는 알림 종류별 수신 채널을 한 화면에서 바꾸고 싶다. 그래야 결제 실패처럼 중요한 알림은 유지하면서 덜 중요한 요약 알림은 줄일 수 있다.

Acceptance Criteria:
- Given 관리자가 알림 설정 화면에 들어왔을 때, When 설정 데이터가 존재하면, Then 알림 종류별 이메일/푸시 토글이 현재 값으로 표시된다.
- Given 사용자가 토글을 변경했을 때, When 저장 버튼을 누르면, Then 변경값이 저장되고 성공 메시지가 표시된다.
- Given 저장 요청이 실패했을 때, Then 사용자가 변경한 값은 화면에 유지되고 재시도할 수 있다.
- Given 권한이 없는 사용자가 접근했을 때, Then 설정을 수정할 수 없으며 권한 안내 메시지를 본다.
- Given 알림 설정 데이터가 아직 없을 때, Then 기본값을 생성하거나 빈 상태 안내를 표시한다.

Acceptance criteria는 "완료"의 의미를 합의하는 문장이다. 좋은 PRD는 모호한 목표보다 구체적인 완료 조건, 오류 시나리오, 비기능 요구사항, 제외 범위를 포함해야 한다.²

정상 시나리오만 쓰면 Agent도 정상 시나리오만 구현한다. 그래서 PRD에는 다음 상태를 짧게라도 넣어야 한다.

로딩 상태
빈 상태
오류 상태
권한 없음 상태
네트워크 실패 후 복구 방식
모바일 화면에서의 동작
중복 클릭이나 연속 요청 처리

이 항목들은 나중에 QA 단계에서 발견하면 귀찮은 수정이 된다. PRD에 먼저 쓰면 구현의 일부가 된다.

비기능 요구사항은 짧아도 반드시 쓴다

비기능 요구사항은 "무엇을 만들 것인가"가 아니라 "어떤 품질로 동작해야 하는가"에 관한 기준이다. AI에게 기능 구현만 맡기면 이 부분이 쉽게 빠진다.

미니 PRD에서는 길게 쓰지 않아도 된다. 다음처럼 한 줄씩만 적어도 충분하다.

비기능 요구사항:
- 성능: 설정 화면의 초기 로딩은 기존 settings 페이지 성능을 악화시키지 않아야 한다.
- 보안: 워크스페이스 관리자 이상만 수정할 수 있다.
- 접근성: 모든 토글은 키보드로 이동 및 변경 가능해야 하며 label을 가져야 한다.
- 로깅: 저장 성공/실패 이벤트를 기록한다.
- 비용: 새 외부 API나 유료 서비스는 추가하지 않는다.
- 모바일: 360px 너비에서도 토글과 저장 버튼이 겹치지 않아야 한다.

이 정도만 있어도 Agent의 구현 방향이 달라진다. 단순히 화면을 만드는 것이 아니라 운영 가능한 기능을 만들게 된다.

PRD는 저장되어야 힘을 가진다

PRD를 채팅창에만 쓰면 금방 사라진다. Cursor 작업 흐름에서는 PRD를 파일로 저장해야 한다. 그래야 이후 Plan Mode, Agent 실행, 리뷰, 버그 수정에서 같은 기준을 반복해서 참조할 수 있다.

한 번에 "다 만들어 줘"라고 하지 않는다

PRD가 있어도 전체 기능을 한 번에 맡기면 위험하다. Agent는 긴 문서를 읽고도 구현 중간에 중요한 제약을 놓칠 수 있다. PRD는 전체 방향을 잡는 문서이고, 실행은 작게 나눠야 한다.

예를 들어 다음처럼 진행한다.

1단계: PRD의 데이터 모델과 권한 요구사항만 보고 구현 계획을 세워줘.
2단계: 설정 조회/저장 API만 구현해줘.
3단계: UI 컴포넌트만 구현해줘. 기존 settings 컴포넌트 패턴을 따라줘.
4단계: 로딩, 빈 상태, 오류 상태를 추가해줘.
5단계: acceptance criteria 기준으로 테스트와 수동 검증 목록을 만들어줘.

한 번에 큰 기능을 맡기는 대신 PRD의 섹션별로 작업하면 범위 이탈을 발견하기 쉽다. PRD를 단일 기준 문서로 두고, 구현은 섹션별로 나누는 방식은 AI 코딩 도구와 함께 일할 때 특히 효과적이다.⁴

반복해서 쓸 수 있는 미니 PRD 템플릿

아래 템플릿을 docs/prd/_template.md로 저장해 두자. 기능을 만들 때마다 복사해서 채우면 된다.

# Feature PRD: [기능 이름]

## 1. 문제 정의
[사용자가 어떤 상황에서 어떤 문제를 겪는가? 한 문장으로 작성]

## 2. 목표
- [이번 기능으로 달성하려는 결과]
- [사용자 또는 비즈니스 관점의 기대 효과]

## 3. 대상 사용자
- [주 사용자]
- [권한/플랜/상태 조건]

## 4. 핵심 사용 여정
1. [진입 경로]
2. [사용자 행동]
3. [시스템 반응]
4. [완료 상태]

## 5. 기능 범위
### P0
- [반드시 포함]

### P1
- [가능하면 포함]

### P2
- [나중에 고려]

## 6. 제외 범위
- [이번 작업에서 하지 않을 것]
- [Agent가 추가하면 안 되는 것]

## 7. UX 상태
- 기본 상태:
- 로딩 상태:
- 빈 상태:
- 오류 상태:
- 권한 없음 상태:
- 모바일 상태:

## 8. Acceptance Criteria
- Given [상황], When [행동], Then [결과]
- Given [상황], When [행동], Then [결과]

## 9. 비기능 요구사항
- 성능:
- 보안/권한:
- 접근성:
- 로깅/분석:
- 비용:
- 모바일 대응:

## 10. 기술 메모
- 관련 파일/폴더:
- 재사용할 기존 패턴:
- 데이터 변경:
- API 변경:
- 테스트 기준:

## 11. 열린 질문
- [아직 결정하지 못한 것]