에이전트 프롬프트 설계

클린 컨텍스트 원칙

서브에이전트는 깨끗한 컨텍스트 윈도우 로 시작합니다. 부모 에이전트의 대화 히스토리, 이전에 읽은 파일 내용, 이전 도구 실행 결과 등 어떤 것도 자동으로 전달되지 않습니다.

부모 에이전트 컨텍스트:
  [사용자와 50번의 대화]
  [10개 파일을 읽음]
  [auth.ts의 버그를 발견함]
  [수정 방법을 논의함]
      ↓ Task 도구 호출
서브에이전트 컨텍스트:
  [비어있음 — 오직 Task prompt만 존재]

이 원칙을 이해하지 못하면 서브에이전트에 불완전한 프롬프트를 작성하게 됩니다.

나쁜 프롬프트 vs 좋은 프롬프트

나쁜 예시

// ✗ 서브에이전트는 "앞서 발견한 버그"가 무엇인지 전혀 모름
Task({
  description: "버그 수정",
  prompt: "앞서 논의한 방식으로 버그를 수정해줘"
})

// ✗ 파일 경로도, 어떤 문제인지도 모름
Task({
  description: "수정 작업",
  prompt: "그 함수의 null 참조 오류를 고쳐줘"
})

좋은 예시

// ✓ 모든 필요한 컨텍스트가 포함됨
Task({
  description: "UserService.getProfile() null 참조 버그 수정",
  prompt: `다음 버그를 수정해주세요:

**파일**: src/services/user.ts
**함수**: UserService.getProfile()
**라인**: 247

**문제**:
user 객체가 null일 때 user.profile을 접근하여 TypeError 발생.
오류 메시지: "Cannot read properties of null (reading 'profile')"

**재현 조건**:
- 로그아웃 상태에서 /api/users/profile 호출 시 발생

**기대 동작**:
- user가 null이면 null을 반환하고 오류를 발생시키지 않을 것

**제약사항**:
- TypeScript strict mode 유지
- 기존 테스트가 통과해야 함
- src/services/user.test.ts에 재현 테스트 추가 필요`
})

효과적인 프롬프트의 5가지 구성 요소

1. 작업 목적과 컨텍스트

왜 이 작업이 필요한지, 전체 프로젝트에서 어떤 위치인지 설명합니다.

예: "이 작업은 사용자 인증 모듈 리팩토링의 일부입니다.
    현재 Express 미들웨어 기반 인증을 JWT 검증 방식으로 전환하고 있습니다."

2. 관련 파일 경로와 함수명

서브에이전트가 어디를 봐야 하는지 정확히 지정합니다.

예: "주요 파일:
    - src/middleware/auth.ts (현재 구현)
    - src/types/user.ts (User 인터페이스 정의)
    - tests/middleware/auth.test.ts (기존 테스트)"

3. 예상 출력 형식

결과물의 형식을 명확히 지정합니다.

예: "다음 형식으로 보고해주세요:
    1. 변경한 파일 목록
    2. 각 변경사항 요약 (한 줄)
    3. 테스트 실행 결과
    4. 주의사항이 있으면 마지막에 추가"

4. 제약 조건

하지 말아야 할 것, 지켜야 할 규칙을 명시합니다.

예: "제약사항:
    - package.json 수정 금지 (새 의존성 추가 불가)
    - 기존 API 인터페이스 변경 금지 (하위 호환성 유지)
    - TypeScript 컴파일 오류 없어야 함"

5. 이전 시도 (있는 경우)

이미 시도했지만 실패한 접근법을 알려줍니다.

예: "참고: 이미 시도한 방법:
    - try-catch로 감쌌지만 상위 컴포넌트에서 다시 throw됨
    - optional chaining(user?.profile)은 타입 오류 발생"

프롬프트 템플릿

// 재사용 가능한 에이전트 프롬프트 템플릿
function buildAgentPrompt({
  context,
  targetFiles,
  task,
  outputFormat,
  constraints,
  previousAttempts
}: AgentPromptParams): string {
  return `
## 컨텍스트
${context}

## 대상 파일
${targetFiles.map(f => `- ${f}`).join('\n')}

## 작업 내용
${task}

## 출력 형식
${outputFormat}

## 제약사항
${constraints.map(c => `- ${c}`).join('\n')}

${previousAttempts ? `## 이전 시도 (실패)\n${previousAttempts}` : ''}
`.trim()
}

에이전트 메모리 영속성

서브에이전트는 컨텍스트가 격리되어 있지만, 메모리 파일 을 통해 정보를 영속적으로 저장하고 공유할 수 있습니다.

3가지 메모리 범위

범위	경로	접근 범위	용도
user	~/.claude/agent-memory/	모든 프로젝트	개인 설정, 선호도
project	.claude/agent-memory/	해당 프로젝트	프로젝트 컨벤션, 아키텍처 결정
local	.claude/agent-memory-local/	로컬 전용 (gitignore)	임시 메모, 개인 실험

// 에이전트가 메모리에 정보 저장 (Bash 도구 활용)
Bash(`echo '{"lastRefactored": "auth.ts", "pattern": "functional"}' \
  > .claude/agent-memory/refactoring-log.json`)

// 다음 에이전트 세션에서 해당 파일을 Read로 로드
Read(".claude/agent-memory/refactoring-log.json")

메모리 파일 자동 로드

프로젝트의 .claude/agent-memory/ 디렉토리에 있는 파일들은 새 에이전트 세션 시작 시 컨텍스트 어셈블리 단계에서 자동으로 로드 됩니다. 에이전트가 명시적으로 Read하지 않아도 됩니다.

에이전트 시작
    ↓
getUserContext() 호출
    ↓
.claude/agent-memory/ 파일 자동 탐색
    ↓
모든 파일 내용을 시스템 컨텍스트에 포함
    ↓
에이전트가 프로젝트 메모리를 자동으로 인지

퀴즈를 불러오는 중...