📝 프롬프트; 나의 AI 를 발전시킬 지침서

Background

하루가 다르게 AI 는 발전하고 있지만, 정작 내가 경험한 AI 는 왜 그닥 똑똑하지 않다고 느껴질까?

바로 그 이유는 AI는 내 머릿속의 맥락(context) 💭 을 공유하고 있지 못하기 때문이다.

우리는 대화를 할 때, 내용 속의 맥락을 기반으로 유추하면서 이야기를 이어나간다.

하지만 우리와 대화하는 AI 는 그럴 수 없고, 우리는 곧잘 답답함을 느낀다.

ex. "최대한 간단하게 작성해줘." - "최대한 간단하게가 몇 글자인데요?"

따라서, AI 를 최대한 잘 활용하기 위해서는 우리의 맥락을 공유해야 한다.

이것이 명시적이고 구조화된 지시가 필요한 이유이고, prompt 는 이것을 AI 에게 전달할 수 있는 도구이다.

ver. Programming

Programming 에서도 사람과 AI 가 생각하는 프로세스는 다음과 같은 차이가 있다.

🧑‍🎨 사람

"CRUD API 만들어야지"
→ (머릿속) 레이어 분리, 보안, 테스트...
→ ✅ 완전한 코드 작성

🤖 AI

"CRUD API"
→ 학습 데이터에서 가장 유사한 패턴 찾기
→ 패턴 복제
→ ❌ 컨텍스트 부족으로 단순화된 코드 생성

따라서, AI 에게 내 머릿속의 생각을 동기화 시키려면 맥락(context)을 공유시켜야 한다.

이를 설명할 수 있는 수단은 prompt 인 것이다.

Prompt

1. 구조적 명확성: 역할, 컨텍스트, 제약사항 분리

개발자 답게 project 에 적용시킬 prompt 를 예시로 들어보자.

❌ 나쁜 예시 - 모호한 요청

사용자 관리 API를 만들어줘.

✅ 좋은 예시 - 구조화된 프롬프트

<role>
Spring Boot, JPA, RESTful API


<project_context>
- 프로젝트: E-commerce 플랫폼
- 기술 스택: Spring Boot 3.2, Java 17, PostgreSQL, Gradle
- 아키텍처: Layered Architecture (Controller → Service → Repository)
- 인증: JWT 기반

<task>
User 도메인을 위한 CRUD API를 구현

<requirements>
1. RESTful 설계 원칙 준수
2. DTO 패턴 사용 (Entity 직접 노출 금지)
3. 입력 검증 (@Valid 사용)
4. 글로벌 예외 처리
5. 비밀번호는 BCrypt로 암호화

<constraints>
- 하나의 파일에 모든 코드를 넣지 말 것
- 각 레이어별로 파일 분리 (Controller, Service, Repository, DTO, Entity)
- 패키지 구조: com.ecommerce.user.*

<output_format>
파일별로 코드를 구분하여 제공:
1. User.java (Entity)
2. UserDTO.java
3. UserRepository.java
4. UserService.java
5. UserController.java
6. GlobalExceptionHandler.java

💡 .md 파일에 프로젝트의 스펙을 명시하면 좋다.

2. 명시적 지시: "좋은 코드"가 아니라 구체적 기준 제시

❌ 나쁜 예시

이 코드를 리팩토링해줘. 더 좋게 만들어.

public class OrderService {
    public void processOrder(Order order) {
        // ... 100줄의 복잡한 코드
    }
}

✅ 좋은 예시

<task>
다음 OrderService 코드를 리팩토링

<current_problems>
1. processOrder 메서드가 100줄 이상 (Single Responsibility 위반)
2. 비즈니스 로직, 외부 API 호출, DB 접근이 모두 섞여있음
3. 테스트가 어려움 (의존성이 하드코딩됨)
4. 트랜잭션 경계가 불명확함

<refactoring_goals>
1. 메서드를 5개 이하의 작은 메서드로 분해
2. 각 메서드는 하나의 책임만 가져야 함
3. 외부 API 호출은 별도 클래스로 분리 (PaymentClient, InventoryClient)
4. @Transactional 적절히 적용
5. 의존성 주입으로 테스트 가능하게 개선

<coding_standards>
- 메서드명: 동사로 시작 (validateStock, deductInventory)
- 변수명: camelCase, 의미있는 이름 사용
- 주석: 복잡한 비즈니스 로직에만 추가
- 매직 넘버 사용 금지 (상수로 정의)

💡 .md 파일에 본인의 개발 철학을 명시하면 좋다.

3. 단계별 추론 유도: Think Step-by-Step

✏️ 실전 예시 - 분산 트랜잭션 설계

<task>
마이크로서비스 환경에서 주문 생성 로직을 구현

<scenario>
주문 생성 시 다음 작업이 원자적으로 수행되어야 함:
1. Order Service: 주문 생성
2. Inventory Service: 재고 차감
3. Payment Service: 결제 처리
4. Notification Service: 알림 발송

<thinking_process>
다음 순서대로 생각하고 답변
<step1>
문제 분석:
- 어떤 분산 트랜잭션 패턴이 적합한가? (2PC, Saga, Event Sourcing)
- 각 패턴의 장단점은?
- 이 시나리오에 가장 적합한 패턴은?
<step2>
패턴 선택 이유:
- 선택한 패턴이 이 시나리오에 적합한 이유
- 다른 패턴을 배제한 이유
<step3>
구현 설계:
- 어떤 컴포넌트가 필요한가?
- 각 컴포넌트의 책임은?
- 실패 시나리오별 보상 트랜잭션은?
<step4>
코드 구현:
- Java 코드로 구현
- 각 단계별 주석 추가

<constraints>
- Spring Boot 사용
- 메시징: Kafka
- 최종 일관성(Eventual Consistency) 허용

💡 .md 파일에 AI 에게 스스로 전략 n 가지를 지정하고, 전략에 따른 점수를 분배하여 점수가 높은 전략을 수행하도록 할 수 있다.

4. 제약사항 명시: 금지 사항 리스트

✏️ 실전 예시

<task>
결제 처리 로직을 구현

<must_do>
✓ 멱등성(Idempotency) 보장 (동일 요청 중복 처리 방지)
✓ PCI-DSS 준수 (카드 정보는 절대 로그에 남기지 않음)
✓ 트랜잭션 원자성 보장
✓ 재시도 로직 포함 (외부 API 실패 시)
✓ 결제 상태는 Enum으로 관리

<must_not_do>
✗ 카드 번호를 DB에 평문 저장 금지
✗ 결제 금액을 float/double로 처리 금지 (BigDecimal 사용)
✗ 동기 처리로 타임아웃 발생하면 안됨 (비동기 권장)
✗ 예외를 catch만 하고 무시하지 말 것
✗ 하드코딩된 API 키 사용 금지

<implementation_requirements>
- 외부 결제 게이트웨이: Stripe API
- 결제 이력 저장 필수
- 실패 시 알림 발송
- 테스트 코드 포함 (모킹 사용)

💡 .md 파일에 하지 말아야 할 것을 서술하는 것은 필수이다.

효율적인 Promt 작성법

템플릿 기반 프롬프트

반복적인 작업에는 재사용 가능한 템플릿(.md)을 만든다.

이것이 바로 AGENTS.md 파일이다.

Example

<task>
상품 재고 관리 기능을 구현하세요.
</task>

<business_requirements>
AS-IS: 재고는 수동으로 관리되며, 실시간 추적이 불가능
TO-BE: 
- 실시간 재고 추적
- 재고 부족 시 자동 알림
- 재고 히스토리 관리
- 동시성 제어 (동시 주문 시 재고 차감 정확성 보장)
</business_requirements>

<technical_requirements>
<tech_stack>
- Framework: Spring Boot 3.2
- Database: PostgreSQL 15
- Build Tool: Gradle 8
- Java Version: 17
</tech_stack>

<architecture>
- Pattern: Layered Architecture
- Communication: REST API
- Concurrency: Pessimistic Locking (재고 차감)
</architecture>

<quality_requirements>
- Test Coverage: 최소 85%
- Performance: 재고 조회 < 50ms, 차감 < 100ms
- Security: JWT 기반 인증, ROLE_ADMIN만 재고 추가/수정 가능
</quality_requirements>
</technical_requirements>

<specific_requirements>
1. 동시성 제어 전략
   - 비관적 락 (Pessimistic Lock) 사용
   - 데드락 방지 로직 포함
   
2. 재고 부족 알림
   - 재고가 안전 재고량(safety stock) 이하로 떨어지면 이메일 발송
   - 알림 중복 발송 방지 (1일 1회)
   
3. 히스토리 관리
   - 모든 재고 변동 이력 저장
   - 변동 사유(주문, 반품, 조정 등) 기록
</specific_requirements>

<deliverables>
1. [✓] Inventory Entity (재고)
2. [✓] InventoryHistory Entity (재고 이력)
3. [✓] InventoryRepository (with Locking)
4. [✓] InventoryService (비즈니스 로직)
5. [✓] InventoryController (API)
6. [✓] InventoryDTO
7. [✓] Custom Exception (InsufficientStockException)
8. [✓] Unit Tests (Mockito)
9. [✓] Integration Tests (Testcontainers)
10. [✓] Concurrency Test (멀티스레드 환경)
</deliverables>

best-practice

그리고, 이미 곳곳에 best-practice .md 파일들이 즐비해있다.

대표적으로, Open AI 팀에서 공유한 아티클 이 있다.

Summary

결국, AI 가 읽는 글인 프롬프트는 간단하다.

✅ 해야할 것(프로젝트의 스펙, 요구사항, ..)과 ❌ 하지 말아야 할 것(유의 사항)이 나뉘어져서 작성되면 된다.

사람이 읽을 글은 이해를 돕기 위해 여러 미사어구나 보충 자료가 태그될 수 있다.

하지만 AI 의 경우는 그럴 필요도 없을 뿐더러 그래서는 안된다.

직관적이지 않은 많은 content 는 오히려 AI 를 혼란스럽게 할 수 있고, AI 에게 보내는 request 하나하나가 돈으로 직결되기 때문이다.

따라서, AI 를 보다 잘 활용하기 위해서는 철저히 AI 를 고려한 prompt 를 사용해야 한다.