devAlice
← AI Agents

프롬프트 템플릿 — 매일 쓰는 AI 작업을 재사용 가능한 형태로

AI 에이전트에게 같은 일을 두 번 시키지 않기 — 코드 리뷰·디버깅·리팩토링·테스트 작성 템플릿 5종.

AI 에이전트와 1주일 일하면 같은 패턴의 요청을 매일 반복하게 된다 — "이 코드 리뷰해줘", "버그 추적해줘", "테스트 짜줘". 매번 처음부터 컨텍스트를 적는 대신, 재사용 가능한 프롬프트 템플릿을 만들어두면 시간·일관성·결과 품질 모두 잡힌다.

이 가이드는 매일 쓰는 5종 템플릿(코드 리뷰·디버깅·리팩토링·테스트·문서화)과 저장·관리 방법.

TL;DR

  1. 템플릿 = 컨텍스트 + 작업 + 출력 형식 + 제약
  2. 저장 위치: ~/.prompts/ 또는 chezmoi 관리
  3. 매크로 도구: Raycast Snippets, Cursor에서 @docs, Claude Code의 slash commands
  4. 좋은 템플릿 4 요소: 역할 명시 / 입력 명시 / 출력 형식 명시 / 금지 항목 명시

1. 좋은 프롬프트 템플릿의 4요소

플레이스홀더는 본문에서 [...]로 표기한다 (MDX JSX 충돌 회피).

You are a [역할].

Context: [컨텍스트]

Task: [무엇을 할 것인지]

Output format: [어떤 형태로 응답할 것인지]

Constraints:

  • [금지 사항 1]
  • [금지 사항 2]

명확한 4섹션은 모델이 답할 부분과 안 할 부분을 구분하게 한다.

2. 템플릿 1 — 코드 리뷰

You are a senior code reviewer for [language] projects.

Context:

  • Code under review: [paste code or @file]
  • Project conventions: [link or paste relevant style guide / .cursorrules]
  • Reviewer focus: [correctness | security | performance | readability]

Task: Review the code. Identify:

  1. Bugs or logic errors (severity: critical / major / minor)
  2. Security issues (input validation, secrets, auth)
  3. Performance concerns (only if obvious O(n^2) or memory)
  4. Style violations against project conventions
  5. Suggestions for clarity

Output format: SUMMARY: [one-paragraph overall verdict] [CRITICAL] (line N): [issue] -> [fix] [MAJOR] ... [MINOR] ... [STYLE] ... [SUGGESTION] ...

Constraints:

  • Do not rewrite the entire file. Point and suggest.
  • Do not nitpick style if .cursorrules don't enforce it.
  • If no issues found at a level, omit that section.

사용 패턴

Cursor 사이드 채팅 — @code-review.md + @src/auth/login.ts + focus: security.

Claude Code: .claude/commands/review.md에 위 템플릿 저장 후 /review src/auth/login.ts.

3. 템플릿 2 — 버그 디버깅

You are a debugging assistant.

Context:

  • Error message: [paste full stacktrace]
  • Code where it occurs: [paste minimal repro or @file]
  • What I tried: [hypotheses ruled out]
  • Expected behavior: [what should happen]

Task:

  1. Identify the most likely root cause (not just symptoms)
  2. Suggest a fix
  3. Suggest a test to prevent regression

Output format: ROOT CAUSE: [one sentence] EXPLANATION: [2-3 paragraphs of why] FIX: [patched code] REGRESSION TEST: [test code]

Constraints:

  • Do not guess. If you need more info (logs, full file), ask.
  • If 2+ hypotheses are equally likely, present both with discriminating signals.
  • Do not just say "try X" — explain the model.

"What I tried" 섹션이 핵심. 모델이 같은 시도를 반복 제안하지 않게.

4. 템플릿 3 — 리팩토링

You are a refactoring assistant for [language].

Context:

  • Current code: [paste or @file]
  • Pain point: [readability | duplication | testability | performance]
  • Constraints:
    • Must preserve public API
    • Must not break existing tests

Task: Refactor while preserving behavior. Show:

  1. The refactored code
  2. Diff vs original
  3. Tradeoffs of this approach vs at most 1 alternative

Output format: REFACTOR: [new code] DIFF:

  • Removed: [what]
  • Added: [what]
  • Renamed: [old -> new] TRADEOFF: [this approach]: [pros/cons] [alternative]: [pros/cons] RECOMMENDATION: [which and why]

Constraints:

  • Do not change behavior. If you think behavior should change, flag it separately.
  • Keep test compatibility — show how existing tests still pass.
  • Don't introduce new dependencies without explicit ask.

5. 템플릿 4 — 테스트 작성

You are a test writer for [language] (Vitest, Jest, Pytest, etc.).

Context:

  • Code to test: [paste or @file]
  • Existing test style: [paste sample test or @file]
  • Coverage focus: [happy path | edge cases | failure modes | all]

Task: Write tests that:

  1. Cover the happy path
  2. Cover at least 3 edge cases (boundary values, empty input, error cases)
  3. Are deterministic (no flaky time/network without mock)
  4. Follow the existing test style

Output format: a single test file in [language].

Constraints:

  • Use the same assertion library as existing tests
  • Mock external dependencies (don't hit real network/DB)
  • Keep each test focused (one assertion topic per test)
  • Name tests descriptively: "returns X when Y"
  • Do NOT write tests that just mirror implementation. Test behavior.

6. 템플릿 5 — 문서화

You are a technical writer.

Context:

  • Code: [paste or @file]
  • Audience: [beginner | intermediate | expert]
  • Doc type: [README section | JSDoc | tutorial | reference]

Task: Write documentation that:

  1. States the purpose in 1 sentence
  2. Shows minimal usage example
  3. Lists parameters/returns with types
  4. Notes edge cases or gotchas (if any)

Output format: markdown or specific JSDoc/TypeDoc format.

Constraints:

  • No filler. Be direct.
  • Code examples must be runnable / pasteable
  • If the API is complex, link to deeper reference rather than dumping
  • For library/framework specifics, prefer official terminology

7. 저장 / 관리

옵션 A — Claude Code slash commands

~/.claude/commands/review.md에 템플릿 저장. CLI에서 /review src/foo.ts 호출 시 자동 시스템 프롬프트 주입.

옵션 B — Cursor @docs

Cursor → Settings → Features → Docs → Add → URL/Local 경로. 채팅에서 @my-review-template 호출.

옵션 C — Raycast Snippets

mac/productivity의 Raycast Snippets:

  • Snippet 추가: 본문에 템플릿 전체
  • Keyword: !review
  • 어떤 텍스트 입력 영역에서든 !review → 자동 확장

옵션 D — 단순 디렉토리 + alias

~/.prompts/ 디렉토리에 각 템플릿을 .md 파일로 저장. .zshrc:

alias prompt='ls ~/.prompts'

prompt → 리스트 → cat ~/.prompts/review.md | pbcopy → 어디서든 붙여넣기.

chezmoi 통합

~/.prompts/ 디렉토리를 dotfiles chezmoi 관리에 추가. 새 머신에서도 즉시 사용.

8. 템플릿 진화

처음 만든 템플릿은 70% 품질이다. 사용하면서 다음 패턴으로 개선:

  1. 결과가 자주 길어진다 → "Keep under N lines" 또는 "Output only diff" 추가
  2. AI가 자꾸 다른 방향으로 간다 → "Constraints" 섹션 강화 (구체적 금지)
  3. 컨텍스트 누락 → "What I tried" 같은 명시적 입력 슬롯
  4. 출력이 일관성 없음 → "Output format" 섹션을 예시로 보여줌
  5. 너무 보수적 → "Recommend the best option, not all options"

매 phase 끝에 1줄 메모로 템플릿 진화. 1년 후 자기 패턴이 codified된 자산이 된다.

9. 안티패턴

너무 추상적

❌ "Be a good code reviewer." ✅ "You are a senior reviewer. Identify bugs / security / style. Output in format X."

결과를 짐작 못 함

❌ "Make this better." ✅ "Make this more readable. Don't change behavior. Show diff."

Output format 없음

모델마다 결과가 다른 포맷으로. 비교·자동화 어려움.

너무 길게 — "보험성" 제약

"And also do X. And maybe Y. Don't forget Z." → 모델이 우선순위 잡지 못함. 핵심 3-5개만.

항상 한국어

영어 코드베이스에 한국어 프롬프트는 모델이 토큰 비효율적. 코드 컨텍스트가 영어면 프롬프트도 영어가 결과 품질 ↑.

검증

  1. 같은 코드를 템플릿 없이 vs 템플릿으로 리뷰 → 결과 일관성·완결성 차이
  2. 새 머신에서 chezmoi 적용 → ~/.prompts/가 즉시 사용 가능
  3. Raycast !review 트리거 → 어디서든 확장
  4. Claude Code /review file.ts → 같은 결과 형식으로 응답
  5. 1주일 사용 후 매주 1개 템플릿 진화 (메모 1줄)

트러블슈팅

AI가 템플릿을 무시함

  • 템플릿이 너무 길면 모델이 중간 지시를 잊음. 200줄 미만 권장
  • 가장 중요한 제약은 끝에 한 번 더 (Recency bias)
  • Cursor @docs는 일부 모델에서 컨텍스트 압축됨 — 핵심만 추출

Slash command가 안 됨

  • Claude Code: ~/.claude/commands/foo.md 파일명·위치 정확
  • Cursor: 슬래시 명령은 일부 모델만 지원

출력 포맷이 깨짐

Output format 예시를 명시적으로 보여줌. "Use this exact format:" 같은 강한 표현.

길어지는 답변

"Maximum N lines." 또는 "Only the diff, no explanation." 같은 명시.

한국어/영어 혼용

프롬프트와 출력 언어 모두 명시. "Respond in Korean." 또는 "Respond in English."

참고

변경 이력

  • 2026-05-12: 첫 작성. 템플릿 5종 + 저장 4가지 + 진화 패턴 + 안티패턴 5종 + 트러블슈팅 5종.

댓글