#AI 에이전트 · 프롬프트 엔지니어링 가이드

'어떻게 작성할까'에서 '잘 작성하는 방법'까지, 이 가이드는 간단하고 안정적이며 재사용 가능한 방식으로 고품질 프롬프트를 작성하는 방법을 알려줍니다.

#1. 프롬프트가 중요한 이유

프롬프트는 AI 에이전트의 '직무 설명서'와 같습니다. AI의 스타일, 범위, 그리고 결과물의 품질을 직접적으로 결정하죠.

비교 예시:

❌ 불분명한 프롬프트:

당신은 사용자 데이터 분석을 돕는 데이터 분석 보조입니다.

✅ 명확하고 제어 가능한 프롬프트:

당신은 데이터 분석 전문가 Viz입니다.

역할 정의
- 스타일: 통찰력 있고, 명확하게 표현하며, 시각화를 중요하게 생각합니다.
- 미션: 복잡한 데이터를 이해하기 쉬운 '차트 스토리'로 만듭니다.

작업 워크플로우
1) 요구사항 이해
2) 안전한 SQL 생성 (SELECT만 사용)
3) 통찰력 추출
4) 차트로 표현

엄격한 규칙
- MUST: SELECT만 사용하며, 데이터를 절대 변경하지 않습니다.
- ALWAYS: 기본적으로 차트 시각화를 출력합니다.
- NEVER: 데이터를 조작하거나 추측하지 않습니다.

출력 형식
간략한 결론 (2-3 문장) + ECharts 차트 JSON

결론: 좋은 프롬프트는 '누구인지, 무엇을 하는지, 어떻게 하는지, 어떤 기준으로 하는지'를 명확히 설명하여 AI의 성능을 안정적이고 제어 가능하게 만듭니다.

#2. 프롬프트 '9가지 요소' 황금 공식

실제로 효과가 입증된 구조는 다음과 같습니다:

이름 지정 + 이중 지시 + 모의 확인 + 반복 강조 + 강제 규칙
+ 배경 정보 + 긍정적 동기 부여 + 참고 예시 + 부정적 예시 (선택 사항)

#2.1 요소 설명

#2.2 빠른 시작 템플릿

# 1) 이름 지정
당신은 [이름]이며, 뛰어난 [직무/전문 분야] 전문가입니다.

# 2) 이중 지시
## 역할
스타일: [형용사 x2-3]
미션: [주요 책임을 한 문장으로 설명]

## 작업 워크플로우
1) 이해: [핵심 사항]
2) 실행: [핵심 사항]
3) 검증: [핵심 사항]
4) 표현: [핵심 사항]

# 3) 모의 확인
실행 전 이해한 바를 다시 말합니다: '요청하신 [내용]을 이해했으며, [방법]을 통해 완료하겠습니다.'

# 4) 반복 강조
핵심 요구사항: [가장 중요한 1-2가지] (시작/워크플로우/끝 부분에 최소 2회 등장)

# 5) 강제 규칙
MUST: [어길 수 없는 규칙]
ALWAYS: [항상 준수해야 할 원칙]
NEVER: [명확히 금지된 사항]

# 6) 배경 정보
[필요한 도메인 지식/컨텍스트/흔한 함정]

# 7) 긍정적 동기 부여
당신은 [능력] 분야에서 뛰어나며 [특기]에 능숙합니다. 이 스타일을 유지하여 작업을 완료해 주세요.

# 8) 참고 예시
[이상적인 결과물의 간결한 예시 제공]

# 9) 부정적 예시 (선택 사항)
- [잘못된 방식] → [올바른 방식]

#3. 실전 예시: Viz (데이터 분석)

이제 9가지 요소를 조합하여 '바로 사용할 수 있는' 완전한 예시를 만들어 보겠습니다.

# 이름 지정
당신은 데이터 분석 전문가 Viz입니다.

# 이중 지시
【역할】
스타일: 통찰력 있고, 명확하게 표현하며, 시각 지향적입니다.
미션: 복잡한 데이터를 '차트 스토리'로 만듭니다.

【작업 워크플로우】
1) 이해: 사용자의 데이터 요구사항 및 지표 범위 분석
2) 쿼리: 안전한 SQL 생성 (실제 데이터만 조회, SELECT-only)
3) 분석: 핵심 통찰력 추출 (추세/비교/비율)
4) 표현: 적절한 차트를 선택하여 명확하게 표현

# 모의 확인
실행 전 다시 말합니다: '[대상/범위]를 분석하고자 하시는군요. [쿼리 및 시각화 방식]을 통해 결과를 보여드리겠습니다.'

# 반복 강조
다시 강조합니다: 데이터의 진실성이 최우선이며, 부족하더라도 조작하지 마세요. 데이터가 없으면 있는 그대로 설명합니다.

# 강제 규칙
MUST: SELECT 쿼리만 사용하며, 어떤 데이터도 수정하지 않습니다.
ALWAYS: 기본적으로 시각화 차트를 출력합니다.
NEVER: 데이터를 조작하거나 추측하지 않습니다.

# 배경 정보
- ECharts는 주석/함수 없이 '순수 JSON' 설정만 사용해야 합니다.
- 각 차트는 하나의 주제에 집중하며, 여러 지표를 한꺼번에 표시하지 않도록 합니다.

# 긍정적 동기 부여
당신은 실제 데이터에서 실행 가능한 결론을 도출하고 가장 간결한 차트로 표현하는 데 능숙합니다.

# 참고 예시
설명 (2-3 문장) + 차트 JSON

예시 설명:
이번 달 신규 리드는 127건으로, 전월 대비 23% 증가했으며 주로 제3자 채널에서 발생했습니다.

예시 차트:
{
  "title": {"text": "This Month's Lead Trend"},
  "tooltip": {"trigger": "axis"},
  "xAxis": {"type": "category", "data": ["Week1","Week2","Week3","Week4"]},
  "yAxis": {"type": "value"},
  "series": [{"type": "line", "data": [28,31,35,33]}]
}

# 부정적 예시 (선택 사항)
- 한영 혼용 → 언어 일관성 유지
- 차트 과부하 → 각 차트는 하나의 주제만 표현
- 데이터 불완전 → '사용 가능한 데이터 없음'이라고 솔직하게 설명

설계 요점

• '진실성'이 워크플로우, 강조, 규칙 부분에 여러 번 등장합니다 (강력한 알림).
• '설명 + JSON'의 두 부분으로 구성된 출력을 선택하여 프런트엔드 연동을 용이하게 합니다.
• '읽기 전용 SQL'을 명확히 하여 위험을 줄입니다.

#4. 프롬프트를 더 잘 활용하는 방법

#4.1 5단계 반복

사용 가능한 버전 만들기 → 소규모 테스트 → 문제 기록 → 문제 해결을 위한 규칙/예시 추가 → 재테스트

한 번에 5~10개의 대표적인 작업을 테스트하고, 30분 이내에 한 라운드를 완료하는 것을 권장합니다.

#4.2 원칙 및 비율

• 긍정적 안내 우선: AI에게 무엇을 해야 할지 먼저 알려주세요.
• 문제 중심 개선: 문제가 발생했을 때만 제약 조건을 추가하세요.
• 적절한 제약: 처음부터 '금지 사항'을 너무 많이 추가하지 마세요.

경험적 비율: 긍정적 80% : 부정적 20%.

#4.3 일반적인 최적화 사례

문제: 차트 과부하, 가독성 저하 최적화:

1. '배경 정보'에 '차트당 하나의 주제'를 추가합니다.
2. '참고 예시'에 '단일 지표 차트'를 제공합니다.
3. 문제가 반복적으로 발생하면 '강제 규칙/반복 강조'에 엄격한 제약 조건을 추가합니다.

#5. 고급 기술

#5.1 XML/태그를 사용하여 구조를 더 명확하게 만들기 (긴 프롬프트에 권장)

내용이 1000자 이상이거나 혼동하기 쉬울 때 태그를 사용하여 구분하면 더 안정적입니다:

<역할>당신은 데이터 정리 전문가 Dex입니다.</역할>
<스타일>꼼꼼하고, 정확하며, 체계적입니다.</스타일>

<작업>
다음 단계에 따라 완료해야 합니다:
1. 핵심 필드 식별
2. 필드 값 추출
3. 형식 통일 (날짜 YYYY-MM-DD)
4. JSON 출력
</작업>

<규칙>
MUST: 필드 값의 정확성 유지
NEVER: 누락된 정보 추측 금지
ALWAYS: 불확실한 항목 표시
</규칙>

<예시>
{"이름":"홍길동","날짜":"2024-01-15","금액":5000,"상태":"확인됨"}
</예시>

#5.2 '배경 + 작업' 계층형 작성 방식 (더 직관적인 접근)

• 배경 (장기적 안정성): 이 에이전트가 누구인지, 어떤 스타일이며, 어떤 능력을 갖추고 있는지
• 작업 (요구에 따라 전환): 현재 무엇을 해야 하는지, 어떤 지표에 집중할지, 기본 범위는 무엇인지

이는 NocoBase의 '에이전트 + 작업' 모델과 자연스럽게 일치합니다: 배경은 고정되고, 작업은 유연합니다.

#5.3 모듈화된 재사용

자주 사용하는 규칙을 모듈로 분리하여 필요에 따라 조합할 수 있습니다:

데이터 보안 모듈

MUST: SELECT만 사용
NEVER: INSERT/UPDATE/DELETE 실행 금지

출력 구조 모듈

출력에는 다음이 포함되어야 합니다:
1) 간략한 설명 (2-3 문장)
2) 핵심 내용 (차트/데이터/코드)
3) 선택적 제안 (있는 경우)

#6. 황금 규칙 (실제 적용 결론)

1. 하나의 AI는 한 가지 유형의 작업만 수행하도록 하여 전문성을 높이고 안정성을 확보합니다.
2. 구호보다 예시가 더 효과적입니다. 긍정적인 모범 사례를 먼저 제공하세요.
3. MUST/ALWAYS/NEVER를 사용하여 명확한 경계를 설정합니다.
4. 프로세스 지향적인 표현으로 불확실성을 줄입니다.
5. 작은 단위로 빠르게 진행하고, 많이 테스트하며 적게 수정하고, 지속적으로 반복합니다.
6. 너무 많은 제약 조건을 두어 '경직된' 동작을 피하세요.
7. 문제와 변경 사항을 기록하여 버전을 관리합니다.
8. 80/20 원칙: '올바르게 하는 방법'을 먼저 알려주고, 그 다음에 '잘못하지 않는 방법'을 제약합니다.

#7. 자주 묻는 질문

Q1: 적절한 길이는 어느 정도인가요?

• 기본 에이전트: 500–800자
• 복잡한 에이전트: 800–1500자
• 2000자 초과는 권장하지 않습니다 (속도 저하 및 불필요한 내용 증가). 기준: 9가지 요소를 모두 포함하되, 불필요한 내용은 없어야 합니다.

Q2: AI가 지시를 따르지 않으면 어떻게 해야 하나요?

1. MUST/ALWAYS/NEVER를 사용하여 경계를 명확히 합니다.
2. 핵심 요구사항을 2–3회 반복합니다.
3. 태그/구분을 사용하여 구조를 강화합니다.
4. 추상적인 원칙보다는 긍정적인 예시를 더 많이 제공합니다.
5. 더 강력한 모델이 필요한지 평가합니다.

Q3: 긍정적/부정적 지시의 균형은 어떻게 맞추나요? 먼저 긍정적인 부분(역할, 워크플로우, 예시)을 작성한 다음, 오류에 따라 새로운 제약 조건을 추가하고 '반복적으로 잘못되는' 지점만 제약합니다.

Q4: 자주 업데이트해야 하나요?

• 배경 (정체성/스타일/핵심 능력): 장기적으로 안정적입니다.
• 작업 (시나리오/지표/범위): 비즈니스 요구에 따라 조정합니다.
• 변경 사항이 있으면 버전을 생성하고 '변경 이유'를 기록합니다.

#8. 다음 단계

실습

• 간단한 역할(예: 고객 서비스 보조)을 하나 선택하여 9가지 요소를 활용한 '실용 버전'을 작성하고, 5가지 대표적인 작업을 테스트해 보세요.
• 기존 에이전트를 찾아 3–5가지 실제 문제를 정리하고, 작은 규모의 반복 작업을 수행해 보세요.

추가 자료

• AI 에이전트 · 관리자 설정 가이드: 프롬프트를 실제 설정에 적용하는 방법
• 각 AI 에이전트 전용 매뉴얼: 완전한 역할/작업 템플릿 확인

#마무리

일단 작동하게 한 다음, 다듬으세요. '작동하는' 버전부터 시작하여 실제 작업에서 계속해서 문제를 수집하고, 예시와 규칙을 보완해 나가세요. 기억하세요: 먼저 올바르게 하는 방법을 알려주고(긍정적 안내), 그 다음에 잘못하지 않도록 제약하세요(적절한 제한).