Cursor, AI Coding #6 프롬프트 작성 요령

아트·2025년 10월 23일

AI cursor prompt

Cursor

목록 보기

6/6

여태 설명했던 내용의 레포지터리

프롬프트 작성 요령

프롬프트를 “명세서”처럼 쓰되, MCP · Rules · 문서화를 곁들이면 품질·속도·재현성이 동시에 올라갑니다.

1) 왜 프롬프트를 자세하게 써야 할까?

프롬프트는 결국 요구사항 정의서(Requirements) 입니다. 모델은 우리가 암묵적으로 공유하는 전제를 모릅니다. 그래서 다음 문제가 쉽게 터집니다.

모호성: 같은 문장을 두세 가지로 해석 → 재작업 증가
비일관성: 런타임/버전/입출력 규격이 매번 다름
숨은 제약 누락: 성능·보안·테스트 기준이 빠져 품질 미달
비재현성: 같은 요청인데 결과가 달라 팀이 헷갈림

즉, 정확하고 충분한 프롬프트 = 좋은 명세서입니다. 결과물의 정확도, 예측 가능성, 재현성까지 같이 올라갑니다.

2) 프롬프트 기본 구조 (RTFM-IOF 틀)

아래 7가지만 담아도 대부분의 삽질이 사라집니다.

Role(역할): “너는 시니어 백엔드 엔지니어(Go 1.22)다.”
Task(할 일): “X 기능을 Y 방식으로 구현하라.”
Format(출력 형식): “완성 코드를 하나의 파일로, 주석 포함, Markdown 코드블록으로.”
Metrics/Success(성공 기준): “처리량 5k rps, p95 < 50ms, 메모리 < 200MB.”
I/O Contract(입출력 규격): “입력 JSON 스키마 / 출력 HTTP 예시.”
Constraints(제약·금지): “외부 네트워크 금지, 표준 라이브러리만.”
Examples & Tests(예시·테스트): “3개 예제 + 반례 1개 + 단위테스트 골격.”

팁: “비목적(Non-Goals)”을 짧게 적어 범위를 고정하세요.

3) 실전 작성 요령 (Cheat‑Sheet)

체크리스트

언어/런타임/프레임워크 버전 (예: Node.js 22, TS ES2024)
대상 OS/플랫폼 (예: Linux x86_64, Alpine)
성능/자원 한도 (시간복잡도, p95, 메모리 상한, 파일 크기)
보안 기준 (입력 검증, 시크릿 취급, 로깅 정책/마스킹)
코딩 규칙 (lint/format, 에러 규약, 로깅 레벨)
테스트·검증 (단위/통합, 샘플 데이터, 벤치 조건)
출고 형식 (파일 구조/경로, 주석/README 여부)
비목적 (이번 범위에서 제외되는 것)

나쁜 예 → 좋은 예

나쁜 예: “CSV 파싱 코드 만들어줘.”
좋은 예: “Go 1.22로 헤더 포함 CSV를 스트리밍 파서로 읽어 JSON Lines로 변환.
- 입력 스키마: id:int,name:string,age:int
- 출력: {"id":1,"name":"A","age":20} (줄 단위)
- 성능: 1GB 기준 p95 < 2s, 메모리 < 64MB
- 제약: 외부 패키지 금지(표준만), Win/Linux 동작
- 테스트: 결측/잘못된 타입/빈 파일/대용량 포함
- 출고: cmd/csv2json/main.go 단일 파일, 주석·간단 벤치 포함
- 비목적: ETL 파이프 구성·진단 로그 수집 제외”

4) 무엇을 고려해야 하나? (실무 관점)

컨텍스트 길이(Context Window): 한 번에 넣을 수 있는 정보가 제한됩니다. 핵심만, 링크·요약 적극 활용.
결정성/재현성: 환경·버전·규칙을 고정해야 “어제와 같은 결과”가 나옵니다.
보안/프라이버시: 시크릿/PII는 직접 붙이지 말고, 안전한 도구를 통해 읽기 전용으로.
평가 가능성: 합격/불합격을 수치로 판단할 기준이 필요합니다.
증분 개발: “스텁 → 스펙 → 테스트 → 최적화” 순서로 쪼개서 진행.
오류·불확실성 관리: “모르면 질문해, 추정 금지, TODO 남기고 중단” 같은 가드를 넣으세요.

5) 바로 쓰는 프롬프트 템플릿

[Role]
당신은 {언어/런타임/분야}의 시니어 엔지니어다.

[Task]
{무엇을, 왜, 어디에 쓰기 위해} {어떻게} 구현하라.

[Environment]
- 언어/런타임/프레임워크: {예: Node.js 22 / TS ES2024}
- 대상 OS/플랫폼: {예: Linux x86_64, Alpine}
- 빌드/런 명령: {예: pnpm build && pnpm start}

[I/O Contract]
- 입력: {형식/스키마/예시}
- 출력: {형식/스키마/예시}

[Constraints]
- 성능: {예: p95 < 50ms, 메모리 < 200MB}
- 보안/금지: {예: 외부 네트워크 호출 금지}
- 코딩 규칙: {예: ESLint + Prettier, 에러 핸들러 패턴}

[Tests]
- 필수 테스트 케이스 나열 + 예제/반례

[Deliverable Format]
- 파일 구조/이름, 주석, README 포함 여부
- 오직 최종 코드만 Markdown 코드블록으로 출력

[Non-Goals]
- 이번 범위에 포함되지 않는 것들

6) Cursor에서 MCP(Model Context Protocol)를 쓰는 이유

요약: MCP는 모델이 외부 도구/데이터에 안전하고 표준화된 방식으로 접근하게 하는 프로토콜입니다.

보안 경계: 토큰/DB/클라우드 접근을 명시적 도구로 제한 → 시크릿 유출 예방
재현성/감사 가능성: “프롬프트+도구 호출 기록”으로 어떤 데이터를 어떻게 읽었는지 추적
최신성: 코드/이슈/스키마 등 “살아있는” 실데이터를 조회해 환각(Hallucination) 감소
최소 권한: 읽기 전용·스코프 제한 등 접근 제어 용이
속도/비용 최적화: 대용량 문서를 통째로 붙이는 대신, 질의 기반 조회로 컨텍스트 낭비↓
도구 재사용: GitHub/Jira/DB/FS/HTTP 등 커넥터를 여러 프로젝트에서 재활용

팁: 읽기 전용부터 붙이고, 쓰기 권한은 점진적으로. 각 도구에 쿼터/레이트리밋을 걸어 비용 폭주를 막으세요.

7) Cursor Rules를 쓰는 이유 (팀 규칙을 “맥락”으로 고정)

Rules는 “모델이 항상 따라야 할 프로젝트 규칙”을 자동 컨텍스트로 주입합니다.

일관성: 네이밍, 디렉터리, 에러/로그 규약을 통일
스캐폴딩 절감: 매번 설명하지 않아도 룰이 자동 첨부
중첩 규칙: 상위 공통 + 하위 도메인별 규칙을 경로(glob)로 분리
컨텍스트 절약: 필요한 규칙만 세분화해 첨부
위험 회피: Do/Don’t를 명시해 민감 행위를 차단

설계 원칙

짧고 명확하게(왜/무엇/예시)
경로 기반 분리(루트 공통 / 레이어별 / 예외)
충돌 시 더 구체적인 경로 우선
간단한 예시/반례 포함
PR·버전 태깅으로 변경 이력 관리(“규칙도 코드다”)

8) 왜 문서화(Documentation)가 필수인가?

지식 외부화: 팀원 머리 속 지식을 저장소로 이동 → 이직/휴가 리스크 감소
온보딩/핸드오버: 코드 없이도 큰 그림 파악 가능
일관성 강화: PR·테스트·배포 규칙이 문서로 고정
감사/컴플라이언스: 보안 기준·데이터 흐름·ADR이 추적 가능
AI 활용 극대화: 문서가 곧 모델의 교과서

문서 최소 세트

/README.md: 시스템 개요·빠른 시작·폴더 맵
/docs/architecture.md: 컨텍스트/데이터 흐름/경계
/docs/decisions/ADR-YYYYMMDD-*.md: 의사결정과 대안
/docs/rules/**/*.md: 코딩/리뷰/배포/보안 규칙(= Cursor Rules 원문)
/docs/runbooks/*.md: 장애 대응·온콜 가이드
/CONTRIBUTING.md: 브랜치·커밋·PR·CI 규칙

운영 팁: 문서가 바뀌면 Rules도 같이 업데이트(또는 링크). CI에서 “문서-룰 드리프트” 감시 훅을 걸어두면 좋아요.

9) MCP · Rules · 문서화를 함께 굴리는 권장 워크플로우

Docs‑First: 기능 요청 → /docs/feature/<id>/spec.md 초안 → 팀 합의 → ADR 등록
Rules 업데이트: 새 규칙/예외 발생 시 /docs/rules/ 갱신, 경로별 첨부 범위 조정
MCP 연결: 필요한 데이터 소스(GitHub/DB/Storage 등)를 읽기 전용으로 우선 연결
프롬프트 실행: 위 문서 링크/요약을 짧게 끼워 넣어 컨텍스트를 아껴서 요청
검증/테스트: 사전에 명시한 기준(p95·메모리·테스트)으로 합격/불합격 판정
지속 개선: 산출물 이슈를 Rules·문서에 반영 → 다음 작업의 초기 품질 상승

10) 실전 프롬프트 예시 (Cursor + MCP + Rules)

[Role] 당신은 Node.js 22 + TS ES2024 환경의 시니어 백엔드 엔지니어다.
프로젝트 규칙은 /docs/rules/backend.md, 에러 규약은 /docs/rules/errors.md 를 따른다.

[Task] Redis 캐시 미스 시 MySQL(읽기 전용) 조회 후 setex(600s)로 저장하는
'getUserProfile(userId: string): Promise<UserProfile>' 구현.

[Environment]
- 런타임: Node.js 22 (pnpm)
- MCP: mysql-readonly(스키마: users), redis(default)
- 외부 네트워크 호출 금지, 비동기 함수만 사용

[I/O Contract]
- 입력: userId(string, UUID v4)
- 출력: { id, name, joinedAt, … } (JSON 직렬화 가능 타입만)
- 에러: 미존재 → NotFoundError(status 404, 규약 준수)

[Constraints]
- p95 < 30ms(캐시 히트), 미스 시 p95 < 120ms
- Redis 키: user:profile:{id}, TTL 600s
- 로깅: info(캐시미스), warn(DB 에러), PII 마스킹

[Tests]
- 존재/미존재/TTL 만료/Redis 장애(폴백) 케이스
- 1만 요청 시 캐시 히트율 95% 시나리오

[Deliverable Format]
- 단일 파일 src/services/user-profile.service.ts
- JSDoc + 간단 벤치 주석
- 코드만 Markdown 코드블록으로 출력

11) “사람이 다 쓰기엔 프로그래밍이랑 같다”를 이기는 법

— AI로 스펙 확정 → AI가 프롬프트 작성 → 새 대화로 지시

완벽한 프롬프트를 손으로 쓰려면, 사실상 요구정의·설계·테스트 기획까지 하게 됩니다. 아래 루틴으로 사양 확정과 프롬프트 작성을 AI에게 위임해 보세요.

A. 먼저 “원하는 스펙”을 AI로 확정

1) 목표/제약/성공 기준을 자연어로 던진다.
2) AI의 확인 질문에 답하며 빈칸을 채운다.
3) I/O·에러 규약, 성능·보안 한도를 수치화한다.

B. “프롬프트 자체”를 AI가 써주게 한다 (메타‑프롬프트)

[역할] 너는 시니어 {스택/버전} 엔지니어이자 프롬프트 설계자야.
[목표] 아래 요구를 바탕으로 개발 작업용 “최종 프롬프트”를 작성해.
[포함 규칙]
- Role/Task/Environment/I-O/Constraints/Tests/Deliverables/Non-Goals 모두 포함
- 수치화된 성공 기준과 금지사항 포함
- 파일 경로·런 명령·린트/포맷·로그/에러 규약 명시
- 예제 입출력 3개 이상, 반례 1개 이상
[출력 포맷] 오직 “최종 프롬프트”만 평문으로.
[요구사항 원문] >>> 여기에 요구사항 붙여넣기 <<<

C. 새 대화(New Chat) 로 전달해 격리 실행

완성된 최종 프롬프트를 새 대화에 그대로 붙여 넣어 지시합니다. 이전 대화의 잡음이 섞이지 않아 재현성이 올라갑니다.

D. 60초 점검 체크리스트

성공 기준이 수치로 적혔는가?
입력/출력 스키마와 에러 규약이 있는가?
성능/보안/금지사항이 명확한가?
예제/반례/테스트 조건이 포함됐는가?
산출물 파일 경로/구조가 고정됐는가?

12) Cursor Plan 모드 사용 요령

— 질문으로 빈칸을 메우고, 계획을 편집·검증한 뒤 실행

Plan 모드는 코드를 쓰기 전, 구현 계획을 생성하고 코드베이스를 조사하며 필요한 질문을 먼저 던집니다. 생성된 계획은 UI에서 편집/재정렬 가능하고, 단계별로 실행 → Diff 리뷰 → 수정을 반복할 수 있습니다.

언제 쓰나

요구가 모호/대형/다단계일 때(리팩터링, 전역 규칙 도입, 다중 파일 변경)
명세를 먼저 고정하고 싶을 때(테스트 우선, 릴리즈 체크리스트)
장기 작업에서 중간 점검·수정을 반복해야 할 때

권장 루틴(5단계)
1) 목표·성공 기준·금지사항을 붙여 Plan 모드로 요청
2) Plan이 묻는 확인 질문에 답해 빈칸 제거
3) 생성된 계획을 편집: 범위 축소, 파일 범위 지정, 리스크/롤백 스텁 추가
4) 테스트·검증 단계를 계획에 명시(p95, 메모리 상한, e2e 스텝)
5) 단계별 실행 → Diff 리뷰 → 수정을 반복(필요 시 계획 갱신)

베스트 프랙티스

작게 쪼개기: 한 플랜의 실행 범위를 PR 1~2개로 수렴
읽기 전용부터: MCP/도구는 read‑only로 먼저 연결 후 점증적 확장
문서·룰 연결: 계획 첫 단계에 Rules/ADR 링크를 넣어 일관성 유지
질문 강도 높이기: 애매할수록 “먼저 질문 많이 해”를 명시

13) 자주 하는 실수 & 회피법

“알아서 해줘”: 범위 폭발 → 성공 기준과 비목적을 분명히
환경 미명시: 버전 차이로 빌드 실패 → 런타임/OS/빌드 명령 고정
테스트 부재: 맞는지 모름 → 최소 3~5개 예제·반례 강제
보안 누락: 시크릿/PII 노출 → 도구를 통한 읽기 전용 접근과 마스킹 규칙 문서화
컨텍스트 과잉: 토큰 초과/핵심 실종 → 링크·요약·Rules로 분리

마무리

좋은 프롬프트 = 좋은 명세서
MCP = 안전한 최신 컨텍스트 공급기
Rules = 팀 규칙의 자동 주입기
문서화 = 모든 것을 돌아가게 하는 운영 체계

이 네 가지를 같이 쓰면 정확성·속도·재현성이 동시에 올라갑니다.

아트

이전 포스트