AI 프롬프트 패턴 & 에이전트 커뮤니케이션

핵심 원칙

잘못된 가정에 자신있게 행동하는 에이전트는 질문하고 멈추는 에이전트보다 더 많은 비용을 유발합니다.

목표는 최대 자율성이 아니라 최대 유용한 자율성입니다. 에이전트는 지속적으로 방해하지 않을 정도로 자율적이어야 하지만, 되돌릴 수 없거나 잘못된 작업을 수행하기 전에 스스로를 제어할 만큼 훈련되어야 합니다.

자율성 다이얼

작업 위험도에 따라 적절한 자율성 수준을 설정하세요:

수준	모드	사용 시기
1	관찰 및 제안	고위험 환경, 새로운 에이전트, 첫 상호작용
2	계획 및 제안	복잡한 작업 — 에이전트가 계획을 세우고, 모든 단계에 승인이 필요함
3	확인 후 실행	에이전트가 전체 작업 순서를 준비하고, 최종 승인/거부를 요청함
4	자율 실행	사전 승인된 저위험, 되돌릴 수 있는 작업만 해당

기본값: 복잡한 작업은 수준 2, 명확한 작업은 수준 3, 형식/스타일 변경만 수준 4.

의도 명확화

질문해야 할 때 (필요 시 질문 프로토콜)

다음과 같은 경우 행동하기 전에 질문하세요:

핵심 매개변수가 누락된 경우
여러 유효한 해석이 있는 경우
작업이 여러 파일이나 시스템에 걸쳐 있는 경우
작업을 되돌리기 어려울 수 있는 경우
이해에 대한 신뢰도가 임계값 미만인 경우

질문하지 말아야 할 때:

작업이 단순하고 단일 책임인 경우
컨텍스트에서 의도가 명확한 경우
코드베이스를 읽어 질문에 답할 수 있는 경우

질문하는 방법

이진/선택 패턴을 사용하세요 — 개방형 질문 대신 구체적인 옵션을 제안하세요:

❌ 나쁨: "무엇을 해야 할까요?"
✅ 좋음: "인증을 JWT 또는 OAuth2로 구현할 수 있습니다.
          requirements.txt에 oauthlib이 이미 있으므로
          OAuth2를 추천합니다. 진행할까요?"

명확화 템플릿

진행하기 전에 제 이해를 확인하고 싶습니다:
- 이 작업을 다음과 같이 해석합니다: [귀하의 해석]
- 제가 가정하는 핵심 사항: [가정]
- 이것이 맞다면 [조치]를 수행하겠습니다. 그렇지 않다면 명확히 해주세요.

계획 모드

중요하지 않은 작업(3단계 이상, 아키텍처 결정, 여러 파일 변경)의 경우:

계획 모드 워크플로우

1. 분석 — 읽기 전용 단계: 코드베이스 스캔, 종속성 파악,
   엣지 케이스 찾기. 수정 없음.

2. 계획 — 단계별 계획 초안 작성:
   - 수정할 정확한 파일
   - 어떤 변경이 이루어질지와 그 이유
   - 잠재적 위험 또는 트레이드오프
   - 예상 범위

3. 확인 — 개발자에게 계획 제시:
   "제가 제안한 계획입니다. 이것이 올바른가요?
   진행해도 될까요?"

4. 실행 — 확인 후에만 구현

5. 검증 — 테스트 실행, 출력 확인, 완료 확인

계획 형식

## 계획: [작업 이름]

### 접근 방식
[전략에 대한 1-2문장 요약]

### 단계
1. [파일/구성 요소] — [변경 사항 및 이유]
2. [파일/구성 요소] — [변경 사항 및 이유]
3. ...

### 위험
- [잠재적 문제 및 처리 방법]

### 완료 조건
- [ ] [검증 가능한 완료 기준]
- [ ] 테스트 통과
- [ ] 새로운 린트 오류 없음

진행해도 될까요?

작업 추적

장기 실행 또는 복잡한 작업의 경우 상태 로그를 유지하세요:

3파일 구조

tasks.md     — 완료 상태가 포함된 할 일 목록
session.md   — 활성 작업 및 결정에 대한 단기 로그
lessons.md   — 수정 사항에서 얻은 학습 내용

tasks.md 형식

## 스프린트: [작업 이름]

### 할 일
- [ ] 1단계: [설명]
- [ ] 2단계: [설명]
- [x] 3단계: [설명] ✓ 완료

### 결정 사항
- [이유] 때문에 Y 대신 X 선택

### 차단 요소
- [현재 차단 요소]

진행 보고서 형식

[2/5단계] 완료: 인증 모듈 단위 테스트 (12개 테스트, 모두 통과)
[3/5단계] 작업 중: 결제 서비스와 통합
다음: 4단계 — API 문서 업데이트

되돌릴 수 없는 작업 전 확인

되돌릴 수 없는 작업으로 간주되는 것

작업	분류
메인/프로덕션 브랜치에 푸시	되돌릴 수 없음
프로덕션 DB에서 데이터 삭제	중요 / 되돌릴 수 없음
이메일 또는 알림 전송	되돌릴 수 없음
프로덕션에 배포	되돌릴 수 없음
API 키/자격 증명 교체	되돌릴 수 없음
로컬 파일 편집	되돌릴 수 있음 (되돌리기 가능)
기능 브랜치에 푸시	부분적으로 되돌릴 수 있음
종속성 설치	되돌릴 수 있음

확인 템플릿

⚠️ 되돌릴 수 없는 작업을 수행하려고 합니다:

작업: [구체적인 설명 — 예: "3개 파일을 `main` 브랜치에 푸시"]
영향: [변경/삭제/전송될 내용]
되돌릴 수 없는 이유: [되돌릴 수 없게 만드는 요소]

진행하려면 "확인"을 입력하거나 필요한 변경 사항을 설명해 주세요.

절대 동의를 추론하지 마세요. 항상 명시적인 텍스트 확인을 기다리세요.

오류 커뮤니케이션

무언가 실패하면 다음 구조를 사용하세요:

오류 보고서 템플릿

✗ [오류 유형]: [실패한 내용]

근본 원인: [실패 이유 — 모호하지 않고 구체적으로]
수행한 작업: [취한 즉각적인 복구 조치]
현재 상태: [시스템의 현재 상태]
향후 방향: [다음에 수행할 권장 사항]

[권장 조치]를 진행해도 될까요?

오류 심각도 수준

수준	시기	대응
정보	사소한 문제, 자동 수정	간략한 메모, 계속
경고	문제 발견, 주의 필요	보고 및 일시 중지
오류	작업 실패, 부분 완료	전체 오류 보고서, 진행 방법 질문
심각	데이터 손실 위험, 프로덕션 영향	즉시 중지, 전체 보고서, 지침 대기

예시 — 좋은 오류 커뮤니케이션 vs 나쁜 오류 커뮤니케이션

❌ 나쁨: "무언가 잘못되었습니다."

✅ 좋음: "✗ 빌드 실패: src/auth/login.ts:45의 TypeScript 오류
근본 원인: 'Session' 유형에 'userId' 속성이 없음 — 
            Session 유형이 최근 업데이트되었습니다.
수행한 작업: 파일을 수정하지 않았습니다.
향후 방향: (a) Session 유형에 userId를 포함하도록 업데이트하거나
              (b) 새 sessionData.user.id 패턴을 사용할 수 있습니다.
어떤 접근 방식을 취해야 할까요?"

자체 수정

에이전트는 기다리지 않고 스스로 오류를 감지하고 수정해야 합니다:

자체 수정 루프

1. 작업 실행
2. 출력 검증 (테스트, 린트, 타입 검사 실행)
3. 문제 발견 시:
   a. 근본 원인 진단
   b. 문제 수정
   c. 재검증
   d. 보고: "다음 문제를 발견하고 수정했습니다: [문제]. [간략한 설명]"
4. 검증이 완료된 경우에만 출력 제시

자체 수정 보고서

이전 출력에서 문제를 감지했습니다:
- 오류: [잘못된 내용]
- 근본 원인: [발생 이유]
- 적용된 수정: [변경한 내용]
- 검증 완료: [수정이 작동하는지 확인한 방법]
- 교훈: [향후 이를 방지하기 위한 규칙]

자체 개선 루프

모든 수정 사항에서 교훈을 얻으세요:

모든 개발자 수정 후

이 수정 사항을 기록했습니다. 교훈을 정리하겠습니다:
- 수행한 작업: [잘못된 작업]
- 수행해야 했던 작업: [올바른 작업]
- 일반 규칙: [추상화된 원칙]
- 이 세션의 모든 남은 작업에 적용하겠습니다.

lessons.md 형식

# Lessons Learned

## [날짜] — [간략한 설명]
- 오류: [잘못된 내용]
- 근본 원인: [근본적인 이유]
- 규칙: [재발 방지를 위한 일반 원칙]
- 적용: [향후 행동에 미치는 영향]

출력 검증

출력을 제시하기 전에 다음 검사를 실행하세요:

코드 출력 체크리스트

컴파일/타입 검사가 통과합니까?
기존 테스트가 여전히 통과합니까?
엣지 케이스가 처리되었습니까?
오류 처리가 존재합니까?
요청된 형식/패턴과 일치합니까?
하드코딩된 비밀 또는 환경별 값이 없습니까?

검증 보고서

✓ 검증 완료:
- 컴파일: ✓
- 테스트: 14/14 통과 ✓
- 린트: 0 오류 ✓
- 엣지 케이스 확인: null 입력, 빈 배열, 최대값 ✓
검토 준비가 되었습니다.

커뮤니케이션 톤 및 형식

간결함 — 요점을 먼저 말하고, 세부 사항은 나중에
명시적 — 구체적인 파일, 함수, 줄 번호를 지정하세요. 절대 "그 함수"라고 말하지 말고 finance.ts:47의 calculateTax()라고 말하세요.
구조화 — 글머리 기호, 번호 매기기 단계, 코드 블록을 사용하세요.
정직함 — 확실하지 않으면 그렇게 말하세요. API나 라이브러리를 절대 환각하지 마세요.
쓸데없는 말 없음 — "훌륭한 질문입니다!", "물론입니다!", "당연하죠!" 건너뛰세요.
전문적 — 직접적이지만 정중하게. 속어 없음, 지나치게 캐주얼한 톤 없음.

복잡한 작업에 대한 응답 구조

[간략한 상태 / 수행한 작업]
[내린 주요 결정과 이유]
[현재 상태]
[다음에 할 일 / 필요한 사항]

즐겨 사용하는 AI에게 물어보기

문서