프롬프트 엔지니어링
카드로 남기는 개발 자산

Session 2 · 카드로 남기는 개발 자산

원칙 4가지 · CO-STAR 6요소 · 실전 카드 5장 · 나쁜/좋은 프롬프트 대결

강사 박수현 · 🚀 젠아이랩스(GenAI Labs)

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background — five paper prompt cards fanned out on the left side. Each card has EXACTLY ONE short English label in monospace: 'Spec to Arch', 'Refactor Loop', 'Regression Guard', 'Arch Decision', 'Incident Review'. On the right side thin luminous lines flow from the cards into a stylized terminal prompt window with a blinking caret. Clean editorial style, teal #00b894 and purple #6c5ce7 accents with warm orange highlights, 16:9. English ONLY, each label EXACTLY ONCE."

Session 2 · 카드로 남기는 개발 자산

세 축의 지도 — 프롬프트 · 컨텍스트 · 하네스

AI 코딩을 다루는 기술은 세 축으로 정리된다. 축마다 초점이 다르고, 뒤의 축이 앞의 축을 감싼다.

프롬프트 ⊂ 컨텍스트 ⊂ 하네스 — 나란한 셋이 아니라, 뒤의 축이 앞의 축을 감싼다

각 축은 앞 축의 한계에서 태어났다 — 약한 지시 · 없는 지식 · 없는 실행 환경

PART 1

프롬프트는 개발 행위다

자동완성과 대화의 차이 · 프롬프트 = 스펙+아키텍처+리뷰 · 실패의 대표 3 패턴.

자동완성과 대화의 차이 — 지시가 성과물이다

프롬프트가 개발 행위인 이유는 도구의 성격이 바뀌었기 때문이다. Copilot 계열의 자동완성은 다음 몇 줄을 추측한다. Claude Code · Codex 계열의 대화는 무엇을 만들지 자체를 사람이 지시한다. 지시의 품질이 결과의 품질을 결정한다.

※ Codex = OpenAI 의 대화형 개발 페어.

프롬프트 = 스펙 + 아키텍처 + 리뷰 지시

잘 쓰인 프롬프트 한 통에는 세 가지가 담긴다.

실패의 대표 3 패턴 — 현장 관찰

현장에서 반복 관찰되는 프롬프트 실패는 세 종류로 좁혀진다.

PART 2

원칙 4가지 — 명시성 · 역할 · 예시 · 재현성

Anthropic 공식 프롬프트 가이드가 소개하는 여러 기법 중 실전에서 반복되는 네 축.

원칙 개요 — 네 축이 반복된다

이 네 축을 카드에 담으면 대부분의 페어링 상황을 커버한다.

원칙 ① 명시성 — 무엇을·왜·어디까지

명시성은 네 원칙 중 가장 무겁다. 성공 판정 기준까지 프롬프트 안에 들어가야 결과가 재현된다.

명시성 — 나쁜 예 vs 좋은 예

routes/feed.py 좀 빠르게 해줘

routes/feed.py 의 GET /feeds 응답을
200ms 이하로 낮춰라.
현재 p50 380ms · p95 720ms · N+1 의심.

병목 3개를 우선순위 순으로
· 각 병목마다 개선안
· 위험도(하/중/상)
· pytest 회귀 가능성을 표로.

완료 조건: 3행 표 · 코드 수정은 다음 턴.

원칙 ② 역할 — 페르소나와 강도

"너는 시니어 파이썬 개발자다" 한 줄이 응답 밀도를 바꾼다. 역할 부여는 두 축으로 조절한다. 누구인지와 얼마나 엄격한지.

🎭 역할 부여 예

역할 — 나쁜 예 vs 좋은 예 (코드 리뷰)

이 코드 리뷰해줘.

너는 15년 차 백엔드 리뷰어다.
엄격하게 검토하되 팀 컨벤션은
CLAUDE.md 를 따른다.

검토 축: 성능 · 보안 · 테스트 · 가독성.
축별 발견 사항 3개 이내
· 심각도(하/중/상) 표기.

원칙 ③ 예시 (few-shot) — 좋은 예 + 나쁜 예 페어링

언어 모델은 예시에서 패턴을 잡는다. 좋은 예 하나보다 좋은 예 + 나쁜 예 페어가 응답 편차를 훨씬 좁힌다. 대조가 있으면 모델이 경계선을 좁게 잡는다.

예시 — 커밋 메시지 컨벤션 리뷰

너는 커밋 메시지 리뷰어다.

[좋은 예] feat(auth): JWT 만료 시간
  15분 → 8시간

아래 3개를 좋은 예 스타일로 다시 써라:
"fix bug" · "refactor code" · "add feature"

너는 커밋 메시지 리뷰어다.

[좋은 예] feat(auth): JWT 만료 시간
  15분 → 8시간
  - 짧은 만료로 세션 끊김 사고 3건
  - Refresh 토큰 도입 이전 임시 조치

[나쁜 예] update auth — 뭐 좀 고침

아래 3개를 좋은 예 스타일로 다시 써라:
"fix bug" · "refactor code" · "add feature"

원칙 ④ 재현성 — 온도·모델·컨텍스트 고정

같은 프롬프트에서 결과가 매번 흔들리면 재현이 아니다. 재현성은 세 축으로 확보한다.

재현성 — 휘발 vs 저장

~/.claude/prompts/
├── specToArch.md
├── refactorLoop.md
├── regressionGuard.md
├── archDecision.md
└── incidentReview.md

네 축 위에 얹는 것 — 생각의 사슬 (Chain-of-Thought)

역할·예시·명시성이 지시를 정돈한다면, CoT 는 지시를 받은 뒤의 순서를 정돈한다. "단계별로 생각해 보라" 고 유도해 모델의 추론 과정을 응답 밖으로 꺼내는 기법이다.

PART 3

CO-STAR 프레임 — 6요소 순서

Sheila Teo 가 GovTech Singapore 프롬프트 대회에서 우승하며 정리한 프레임. 6 요소를 순서대로 채우면 원칙 4가지가 그대로 배치된다.

CO-STAR — 상위 3요소 (C · O · S)

CO-STAR 는 2023년 GovTech Singapore 프롬프트 대회에서 우승한 Sheila Teo 가 정리해 공개한 프레임이다.

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background of a stylized diamond gem with six facets arranged in 3D. Each facet carries a single English capital letter and a short one-word label: 'C Context', 'O Objective', 'S Style', 'T Tone', 'A Audience', 'R Response'. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents with warm orange highlights, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

CO-STAR — 상위 3요소 (C · O · S)

CO-STAR — 하위 3요소 (T · A · R)

CO-STAR 실 예제 — FastAPI 라우트 리팩토링

앞서 나온 GET /feeds 리팩토링을 6요소에 맞춰 조립한다.

# Context
너는 15년 차 백엔드 리뷰어다.
대상 코드: FastAPI 앱 · Postgres 15 · 하루 100만 요청 · Python 3.11.
파일: routes/feed.py · models/feed.py · services/feed_service.py
현재 프로파일: GET /feeds p50 380ms · p95 720ms.

# Objective
GET /feeds 응답 시간을 p95 200ms 이하로 낮추는 개선안을 뽑는다.
기존 API 스펙은 유지 · 클라이언트 변경은 허용하지 않는다.

# Style
표 형식 · 각 행 3열 이내 · 단정문.

# Tone
엄격 · 회귀 위험을 우선 표기.

# Audience
팀 리드 (5년 차 백엔드) · Postgres 인덱스 개념 익숙 · MSA 경험 없음.

# Response
1차 응답 = 병목 3개 진단 표 (원인 · 개선안 · 위험도 · 소요).
표 검토 후 승인하면 2차 응답에서 코드 diff.
지금은 코드 작성 금지.

카드 만드는 절차 — 4단계

CO-STAR 를 매번 처음부터 쓰지 않는다. 자기 상황별 템플릿을 카드로 만들어 두고, 상황이 오면 카드 안 변수만 바꾼다.

PART 4

실전 프롬프트 카드 5장

그대로 복붙해 쓸 수 있는 완성본. 상단에 상황·권장 모델, 본문에 CO-STAR 6요소, 하단에 변수 목록. 파일명 규약: ~/.claude/prompts/{camelcase}.md.

카드 1 — 스펙 → 아키텍처

상황. 새 기능·새 서비스의 요구사항을 받아 파일 트리와 데이터 모델부터 뽑고 싶을 때. 권장 모델. Opus (설계 판단) · 응답 확정 후 Sonnet 으로 전환. 예시 스택. FastAPI + SQLAlchemy + Pydantic.

# 상황
{feature_name} 기능을 신규 개발한다.
스택은 {stack} 이다.

# 요구사항
{requirements}

# 요청
1. 파일 트리 (디렉토리 3레벨까지) 만 먼저 제시
2. 데이터 모델 (SQLAlchemy · Pydantic) 도 이름·필드·관계까지
3. API 엔드포인트 목록 (메서드·경로·요청/응답 스키마 요약)
4. 위 세 개가 확정될 때까지 실제 코드는 작성 금지

# 결정 기준
- 파일 트리는 도메인 중심 (routes/ · services/ · repositories/)
- N+1 회피를 데이터 모델에 반영
- 각 엔드포인트는 인증·에러 처리 명시

# 완료 조건
- 파일 트리 · 데이터 모델 · 엔드포인트 표 세 블록으로 응답
- 아직 코드는 없음

변수. {feature_name} · {stack} · {requirements}

카드 2 — 반복 리팩토링

상황. 특정 파일·모듈의 병목·중복을 진단하고 개선안을 표로 받고 싶을 때. 권장 모델. Sonnet.

# 상황
대상 파일: {files}
프로파일 · 지표: {profile}
관찰된 증상: {symptoms}

# 요청
1. 병목 3개를 우선순위 순으로 나열
2. 각 병목마다 개선안 · 예상 개선폭 · 위험도(하/중/상) · 소요(1h/1d/1w)
3. 표 형식 · 3행 이내
4. 기존 pytest 회귀 가능성 열을 추가

# 결정 기준
- 우선순위 = 예상 개선폭 × (1 / 위험도) × (1 / 소요)
- 위험도 상은 배포 게이트 명시

# 완료 조건
- 표 한 개 · 4열 (원인 · 개선안 · 위험도 · 소요)
- 코드 수정은 다음 턴

변수. {files} · {profile} · {symptoms}

카드 3 — 회귀 방지

상황. PR 이 기존 테스트를 깨는지 dry-run 결과와 함께 검증하고 싶을 때. 권장 모델. Sonnet · CI 배치 시 Haiku.

# 상황
대상 PR · 브랜치: {branch}
변경 파일: {changed_files}
관련 테스트 스위트: {tests}

# 요청
1. 변경으로 영향을 받을 수 있는 테스트를 먼저 나열
2. 각 테스트에 대해 예상 결과 (통과 · 실패 · 판단 어려움)
3. 실패 예상 테스트는 원인 3줄 이내로 진단
4. 회귀 확인 시 수정 diff 를 최소 변경 원칙으로 제시

# 결정 기준
- 회귀 발견 = 배포 차단
- 판단 어려움 = 실제 pytest 실행 명령을 제안

# 완료 조건
- 테스트 목록 표 (파일 · 결과 · 원인)
- 필요 시 최소 diff 블록

변수. {branch} · {changed_files} · {tests}

카드 4 — 아키텍처 결정

상황. 미들웨어 vs 별도 서비스, 캐시 계층 위치, 큐 도입 여부 등 장기 영향이 큰 결정을 앞뒀을 때. 권장 모델. Opus. 용어. TCO = 초기 개발 + 유지보수 + 장애 + 이관 총합.

# 상황
결정 대상: {decision}
현재 시스템: {current_arch}
제약 조건: {constraints}

# 요청
선택지 2~3개를 나열하고, 각 선택지에 대해 다음을 표로.
1. 개발 초기 비용 (1주 단위)
2. 5년 유지보수 비용 (연 단위 인력 · 인프라)
3. 장애 영향 반경
4. 롤백 난이도
5. 팀 학습 곡선

# 결정 기준
- 5년 관점에서 총 소유 비용 (TCO) 이 낮은 순으로 정렬
- 각 선택지에 "언제 이 선택이 옳은가" 조건 3개 이내

# 완료 조건
- 표 한 개 (선택지 × 5축)
- 마지막에 강사 추천 한 줄 · 근거 두 줄

변수. {decision} · {current_arch} · {constraints}

카드 5 — 실패 회고

상황. 에러 로그 · 장애 이력을 받아 원인 분류 · 재현 조건을 정리하고 싶을 때. 권장 모델. Sonnet · 로그 크면 Haiku.

# 상황
발생 시각: {timestamp}
증상: {symptom}
관련 로그 (원문): 아래 붙임
{logs}

# 요청
1. 원인 후보 3개 · 각 후보의 근거를 로그에서 인용
2. 각 원인의 재현 조건 (입력 · 순서 · 환경 변수)
3. 가장 유력한 원인을 지목하고, 반증 시나리오 1개
4. 재발 방지 체크리스트 3항목

# 결정 기준
- 근거는 반드시 로그 라인 번호 인용
- 추측성 서술 금지 (근거 없으면 "확인 필요" 로 표기)

# 완료 조건
- 원인 후보 3개 · 재현 조건 · 유력 원인 · 반증 시나리오 · 재발 방지 5블록

변수. {timestamp} · {symptom} · {logs}

카드 5장 정리 — 프로젝트 한 사이클

다섯 카드는 각각 다른 국면을 커버한다. 다섯 카드로 프로젝트 한 사이클이 돈다.

PART 5

미니 실습 — 프롬프트 대결

각자 자기 리포에서 라우트·함수 하나를 골라 나쁜 프롬프트·좋은 프롬프트를 순서대로 던진다.

문제 세팅 — 5단계 절차

각 참여자 노트북에서 동시에 진행. 강사는 순회하며 프롬프트 밀도를 확인한다.

대결 — 나쁜 프롬프트 vs 좋은 프롬프트

routes/feed.py 좀 리팩토링해줘

결과 비교 · 공유 — 4개 축

결과를 옆 사람과 교환한다. 두 응답의 차이를 다음 축으로 요약한다.

PART 6

정리 — 카드 저장 · 개인화 · 한 문장 결론

카드는 저장해야 자산이 된다. 저장 경로와 개인화 원칙을 짚고 마친다.

카드 저장 · 개인화

카드는 저장해야 자산이 된다. 저장 경로는 세 가지가 표준이다.

마무리 — 한 문장으로

S2 가 끝났다. 원칙 4가지 · CO-STAR 6요소 · 카드 5장을 정리했다. 나쁜/좋은 프롬프트의 격차를 자기 리포에서 확인했다.

프롬프트가 매번 사라지면 개발 행위가 아니라 노동이다. 카드로 만들어 저장하면 다음 작업의 시작 지점이 오늘 끝난 지점이 된다.

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background of five paper prompt cards neatly arranged in a fan, each card carrying a short English label: 'Spec to Arch', 'Refactor Loop', 'Regression Guard', 'Arch Decision', 'Incident Review'. Above the cards, a warm glow suggests they are saved and reusable. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents with warm orange highlights, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."