[AI 에이전트 파이프라인 #10] 완성된 앱과 회고
지난 편에서는 파이프라인을 운영하면서 발견한 개선점들을 다뤘습니다.
이번 편은 마지막 편입니다. 완성된 앱의 UI와 기술 선택에 대한 회고를 다룹니다.
1. 완성된 콘텐츠 UI
에이전트 파이프라인이 생성한 마크다운이 앱에서 어떻게 렌더링되는지 보여드리겠습니다.
앱을 실행하면 먼저 카테고리와 토픽 목록이 나타납니다. RN 앱은 별도의 메타데이터 API에서 목록 데이터를 가져옵니다. 사용자가 토픽을 선택하면 WebView가 콘텐츠를 렌더링하는 웹앱을 로드합니다.
(스크린샷 추가 예정)
토픽 화면은 4개 섹션으로 구성됩니다: 개요, 핵심개념, 실습, 퀴즈. 핵심개념 섹션에서는 concepts-writer가 생성한 3단계 난이도 설명을 탭으로 전환하며 볼 수 있습니다. “쉬움”을 선택하면 “중학생도 이해할 수 있는 설명”이라는 배지가 표시되고, “전문가”를 선택하면 “20년 이상 전문가를 위한 깊은 설명”이라는 배지가 표시됩니다. 기본값은 “일반”입니다.
(스크린샷 추가 예정)
실습 섹션에는 코드 패턴과 실험 예제가 담겨 있습니다. 다만 9편에서 다뤘듯이 practice-writer는 제거되었고, 현재는 concepts-writer가 이 부분을 함께 생성합니다.
(스크린샷 추가 예정)
마지막 퀴즈 섹션에서는 quiz-writer가 생성한 12문제로 학습 내용을 점검합니다. 난이도별로 쉬움 4문제, 일반 5문제, 전문가 3문제가 고정 배분됩니다.
(스크린샷 추가 예정)
2. 콘텐츠 구조 변경
9편에서 다뤘듯이 practice-writer를 제거했습니다.
원래 실습 섹션은 코드 패턴(Code Patterns)과 실험(Experiments) 두 파트로 구성되어 있었습니다. 하지만 두 파트가 중복되는 느낌이 있었고, 무엇보다 모바일 앱에서 코드를 직접 실행하기 어렵다는 한계가 있었습니다. 개발 외 다른 주제(역사, 언어 등)로 테스트해보니 코드 실습 섹션이 어색하기도 했습니다.
결국 practice-writer를 제거하고, 실습 관련 내용은 concepts-writer가 핵심 개념 설명에 포함시키도록 변경했습니다.
3. 왜 Claude Code였는가
이 작업을 시작한 2025년 7-8월에는 에이전트 프레임워크에 대해 알지 못했습니다. 당시 Max Plan을 구독하고 있었는데 매주 사용 가능한 토큰을 다 소진하지 못하고 있었습니다. 그래서 이 토큰을 활용할 방법을 찾다가 Claude Code CLI 문서에서 -p 옵션으로 프롬프트를 전달할 수 있다는 걸 알게 됐습니다. CLI 기반 반복 작업을 자동화하려면 쉘 스크립트가 자연스러운 선택이었습니다.
파이프라인이 어느 정도 완성된 후에 에이전트 프레임워크들을 알게 됐습니다.
| 프레임워크 | 특징 |
|---|---|
| LangGraph | LangChain 기반 그래프 워크플로우. 상태 관리와 체크포인팅 내장, 조건부 분기 지원 |
| CrewAI | 역할 기반 멀티에이전트. 에이전트 간 협업 패턴이 잘 정의됨, 러닝커브 낮음 |
| AutoGen | Microsoft의 대화형 에이전트. 코드 실행 환경 내장, 멀티에이전트 대화 지원 |
체계적인 상태 관리와 체크포인팅을 제공하고, 에이전트 간 협업 패턴도 잘 정의되어 있었습니다. 6편에서 다룬 WSM(Work Status Markers)이나 Contract의 Precondition/Postcondition 검증처럼 쉘 스크립트로 직접 구현한 것들이 이미 프레임워크에 내장되어 있었습니다.
당연히 마이그레이션을 고민했습니다. 하지만 이 프레임워크들은 API 호출 방식이라 사용량 기반 과금이 필요합니다. 1,690개 이상의 토픽을 생성하려면 비용 부담이 큽니다. Max Plan 구독을 활용하려면 CLI 기반이어야 했습니다. 무엇보다 이미 동작하는 파이프라인이 있었습니다. 새 프레임워크로 다시 구축하는 비용이 현재 방식을 유지하는 비용보다 컸습니다.
“쉘 스크립트 대신 Python이나 Node.js로 짜면 더 깔끔하지 않나?”라는 생각이 들 수도 있습니다. 맞습니다. 하지만 이미 동작하는 코드가 가장 좋은 코드입니다.
4. 전체 시리즈 정리
10편에 걸쳐 다룬 내용을 정리해봤습니다.
| # | 제목 | 핵심 |
|---|---|---|
| 1 | 학습 앱을 만들기 시작한 이유 | 동기와 목표 |
| 2 | 무엇을 생성할 것인가 | 토픽 문서 설계 |
| 3 | 하나의 프롬프트로는 왜 안 됐을까 | 단일 프롬프트 실패 |
| 4 | 분리했는데 왜 여전히 안 됐을까 | 프롬프트 오염 |
| 5 | 프롬프트 완성까지의 4단계 | XML 태그 도입 |
| 6 | 7개 에이전트는 어떻게 협업하는가 | WSM과 Contract |
| 7 | 쉘 스크립트로 에이전트 실행하기 | 정상 실행 흐름 |
| 8 | 재시도와 롤백 | 실패 처리 흐름 |
| 9 | 개선점 발견과 리팩토링 | 에이전트 단순화 |
| 10 | 완성된 앱과 회고 (이번 편) | UI와 기술 선택 회고 |
5. 마무리
2025년 8월부터 2026년 1월까지, 약 6개월간의 여정이었습니다.
메타데이터 파이프라인은 처음부터 잘 작동했습니다. 문제는 콘텐츠 생성이었습니다. 약 1,400줄의 마크다운을 안정적으로 생성하는 게 쉽지 않았습니다. 단일 프롬프트로 시도했다가 실패하고, 7개 에이전트로 분리했지만 여전히 불안정했습니다. 에러가 나면 규칙을 추가했고, 규칙이 늘어날수록 더 나빠졌습니다.
AI-DLC 방법론을 적용하면서 Contract 패턴을 도입했습니다. 각 에이전트가 무엇을 입력받고 무엇을 출력해야 하는지 명확히 정의했습니다. 하지만 마크다운 프롬프트로 마크다운 콘텐츠를 생성하니 LLM이 둘을 혼동했습니다. XML 태그로 프롬프트 구조와 콘텐츠 구조를 분리하자 first-try 성공률이 100%에 가까워졌습니다.
에이전트 프레임워크를 알게 된 건 파이프라인이 어느 정도 완성된 후였습니다. LangGraph나 CrewAI로 마이그레이션하면 더 체계적인 구조를 갖출 수 있겠지만, 이미 동작하는 시스템이 있고 마이그레이션 비용이 유지 비용보다 큽니다. 완벽한 도구보다 동작하는 시스템이 중요합니다.
1,690 + α개 토픽을 위한 파이프라인이 완성되었습니다. 이제 시간만 투자하면 나머지 콘텐츠도 생성할 수 있습니다.
이 시리즈가 비슷한 시도를 하는 분들께 도움이 되길 바랍니다.
이 시리즈는 AI-DLC(AI-assisted Document Lifecycle) 방법론을 실제 프로젝트에 적용한 경험을 공유합니다. AI-DLC에 대한 자세한 내용은 경제지표 대시보드 개발기 시리즈를 참고해주세요.