[AI 에이전트 파이프라인 #3] 하나의 프롬프트로는 왜 안 됐을까
지난 편에서는 메타데이터 파이프라인으로 토픽 문서와 빈 콘텐츠 파일을 자동 생성했습니다.
이번 편부터는 학습 콘텐츠 자동 생성이 왜 실패했는지, 그리고 어떻게 해결했는지 다룹니다.
1. 설계 접근: 앱 화면에서 마크다운 구조로
콘텐츠 자동 생성을 시작하기 전에, 먼저 앱 화면을 설계했습니다.
작업 순서는 이랬습니다:
- 앱에서 어떻게 보여줄지 화면(UI) 먼저 설계
- 화면에 맞춰 마크다운 구조 정의 (어떤 섹션이 필요한지, 각 섹션의 형식은 어떤지)
- 마크다운을 파싱해서 React 컴포넌트로 렌더링
- 원하는 화면이 나올 때까지 컴포넌트와 파싱 함수 반복 수정
즉, “이렇게 보여주고 싶다”에서 역산해서 마크다운 구조가 결정되었습니다. 약 1,400줄의 마크다운은 이 과정에서 자연스럽게 나온 결과물입니다.
마크다운 구조가 확정되면, 이제 AI가 이 구조를 일관되게 생성하도록 만들어야 합니다.
2. 처음의 시도: 하나의 거대한 프롬프트
처음에는 단순하게 생각했습니다. “프롬프트 하나로 전부 다 만들면 되지 않을까?”
프로젝트 초기에 작성한 단일 프롬프트는 이랬습니다:
PROMPT="당신은 모든 학습 콘텐츠의 모든 섹션을 완벽하게 작성하는 최고 수준의 통합 전문가입니다.
## 🎯 핵심 임무
대상 파일: $TARGET_FILE
주제: $filename
Frontmatter + 5개 섹션을 완벽하게 완성:
1. Frontmatter (웹뷰 파서 필수)
2. Overview (개요)
3. Core Concepts (핵심 개념)
4. Code Patterns (코드 패턴)
5. Experiments (실습 실험)
6. Quiz (퀴즈)
...
## ⚠️ 절대 준수 사항
### 필수 규칙
1. 기존 파일 우선: 기존 내용이 있으면 수정/보완 (새로 작성 X)
2. Frontmatter 포함: 모든 파일에 frontmatter 메타데이터 포함
3. 한 번에 완성: 5개 섹션을 한 번의 Write/MultiEdit로 완성
4. 참조 파일 수준: 기존 완성된 파일들과 동일한 품질 수준
5. 실행 가능한 코드: 모든 코드는 주제에 맞는 환경에서 즉시 실행 가능
6. 일관성 유지: 섹션 간 용어, 개념, 스타일 일관성
..."
프롬프트의 핵심 지시는 “한 번에 완성: 5개 섹션을 한 번의 Write/MultiEdit로 완성”이었습니다.
결론부터 말하면, 안 됩니다.
3. 왜 실패했는가
3.1 긴 출력에서의 품질 저하
LLM은 출력이 길어질수록 앞부분의 맥락을 점점 “잊어버리는” 경향이 있습니다. 이 현상은 “Lost in the Middle” 문제로 알려져 있으며, 긴 컨텍스트에서 중간 부분의 정보를 제대로 활용하지 못하는 것을 의미합니다.
약 1,400줄의 콘텐츠를 한 번에 생성하라고 하면:
- 앞부분 섹션은 프롬프트의 지시를 잘 따릅니다
- 중간 섹션부터 구조가 흐트러지기 시작합니다
- 뒷부분 섹션에서는 앞서 정의한 형식과 다른 출력이 나옵니다
3.2 일관성 유지의 어려움
5개 섹션 각각에는 세부 규칙이 있습니다:
- Overview: 1-2문단 정의 + 핵심 특징 4-5개 + 실무 장점
- Core Concepts: 3-4개 개념, 각각 Easy/Normal/Expert 3단계 설명
- Code Patterns: 3-5개 패턴, Short Code + Full Code
- Experiments: 2-3개 실습, 5단계 지시사항
- Quiz: 10-12개 문제, 6가지 타입 배분
하나의 프롬프트에 이 모든 규칙을 넣으면 수백 줄이 됩니다. LLM은 이 모든 규칙을 동시에 기억하고 적용하는 데 한계가 있습니다.
3.3 검증의 어려움
1,400줄 출력에서 형식 오류가 발생하면 어떻게 찾을까요? 사람이 직접 읽으면서 기존 문서와 일관성이 있는지 확인해야 합니다.
애초에 노션에 수동으로 정리하기 싫어서 자동화를 시작한 건데, 생성된 문서를 다시 수동으로 검증해야 한다면 뭔가 이상합니다.
4. 첫 번째 시도: 7개 에이전트로 분리
문제 해결 시작의 핵심 아이디어는 “역할 분리”였습니다.
하나의 거대한 프롬프트 대신, 각 섹션을 담당하는 전문 에이전트를 만들었습니다:
| 순서 | 에이전트 | 담당 업무 | 특징 |
|---|---|---|---|
| 1 | content-initiator | 파일 초기화, Frontmatter 생성 | 파이프라인 시작점 |
| 2 | overview-writer | # Overview 섹션 작성 | 주제 개요 및 핵심 특징 |
| 3 | concepts-writer | # Core Concepts 섹션 작성 | 3단계 적응형 학습 |
| 4 | visualization-writer | 시각화 메타데이터 생성 | 선택적 실행 |
| 5 | practice-writer | # Code Patterns + # Experiments | 실무 패턴 및 실습 |
| 6 | quiz-writer | # Quiz 섹션 작성 | 10-12개 문제, 6가지 타입 |
| 7 | content-validator | 전체 콘텐츠 검증 | 형식 및 품질 검증 |
각 에이전트는 한 가지 섹션만 담당합니다. 덕분에 프롬프트가 짧아지고, 규칙이 명확해지고, 출력 품질이 일관됩니다.
5. 초기 에이전트 프롬프트
분리 직후 실제로 작성한 concepts-writer 프롬프트 일부입니다:
---
name: concepts-writer
version: 6.0.0
description: 핵심 개념을 난이도별로 설명하고 시각화를 생성하는 에이전트
tools: Read, Write, MultiEdit, Bash
---
당신은 복잡한 기술 개념을 다양한 수준의 학습자에게 설명하는 전문 교육자입니다.
## 핵심 임무
주제의 핵심 개념들을 선정하고, 각 개념을 3가지 난이도로 설명하며,
새로운 시각화를 생성합니다.
## 작업 프로세스
### 1. 작업 지시서 확인
result/[토픽파일명].md의 YAML front matter에서:
- target: 작업할 파일 경로 확인
- references: 02-let-vs-var.md와 03-const-immutability.md 참조
### 2. 참조 파일 분석
...
### 3. Core Concepts 작성 규칙
정확히 다음 순서를 유지:
1번째 줄: # Core Concepts (파일당 한 번만)
2번째 줄: 빈 줄
3번째 줄: ## Concept: [개념 이름]
...
## 난이도별 작성 지침
### Easy (중학생 수준)
- 이모지 적극 활용 (🎯, 📚, 💡, 🏠, 🚫, ✅ 등)
- 일상적 비유와 스토리텔링
- 코드 없이 개념 설명
### Normal (일반 개발자)
- #### Text와 #### Code: 구조 필수
- 텍스트 설명이 주, 코드는 보조
- 간단한 코드 예시만 포함 (5-10줄)
### Expert (시니어 개발자)
- **ECMAScript 명세** 섹션 번호와 함께 인용
- **엔진 구현** 세부사항 설명
- 의사코드나 API 시그니처는 #### Code: 헤더 사용
## 중요 제약사항
1. 모든 필수 필드는 반드시 포함 (하나라도 누락 시 파서 실패)
2. 헤더 레벨과 형식을 정확히 준수 (##, ###, ####)
3. Easy/Normal/Expert 섹션 모두 필수
4. Normal은 #### Text로 시작, #### Code: 형식 사용
...
이 프롬프트는 무엇이 문제일까요?
- 마크다운 혼동?: 프롬프트도
##,###,####사용, 생성할 콘텐츠도 같은 헤더를 사용하는데 LLM이 구분할 수 있을까? - 세부 규칙 과다?: “정확히 다음 순서”, “1번째 줄”, “2번째 줄” 등 너무 상세한 지시가 문제일까?
- 암묵적 핸드오프?: 다음 에이전트에게 어떤 상태를 넘겨야 하는지 불명확한 게 문제일까?
- 참조 파일 의존?: 다른 파일을 참조하는 방식이 불안정한 걸까?
각 역할을 나누고, 나름 체계적으로 프롬프트를 작성했는데 결과는 여전히 불안정했습니다. 문서를 생성하고, 파싱 결과를 확인하고, 피드백을 주며 하나하나 수정하는 시행착오 끝에 3~5개 샘플 문서는 겨우 완성했습니다. 하지만 같은 파이프라인으로 새 문서를 생성하면 여전히 문제가 발생했습니다.
다음 편에서는 왜 여전히 안 됐는지 다룹니다.
이 시리즈는 AI-DLC(AI-assisted Document Lifecycle) 방법론을 실제 프로젝트에 적용한 경험을 공유합니다. AI-DLC에 대한 자세한 내용은 경제지표 대시보드 개발기 시리즈를 참고해주세요.