시리즈: 모듈형 평가 엔진 구축하기 (1/10)

사용자가 "직장 스트레스 평가 도구를 만들어줘"라는 문장 하나만 입력하면, 채점 엔진, 스타일이 적용된 UI, 개인화된 PDF 보고서, 그리고 AI 전문가 어시스턴트가 포함된 완성된 형태의 게시 가능한 평가 애플리케이션을 얻을 수 있다면 어떨까요?

그것이 바로 제가 지난 1년 동안 구축해 온 것입니다. 이 시리즈에서는 프로젝트를 거의 무너뜨릴 뻔했던 버그들을 포함하여, 아키텍처를 모듈별로 상세히 분석합니다.

한 문장 입력 문제 (The One-Sentence Input Problem)

핵심 과제는 자연어(Natural Language)를 완전히 기능하는 애플리케이션으로 전환하는 것입니다. 템플릿이나 마법사(Wizard)가 아닙니다. 입력 필드, 채점 로직, 시각적 디자인, 그리고 PDF 보고서가 모두 생성되고 작동하는 실제 앱을 만드는 것입니다.

제가 도달한 해결책은 **모듈형 기술 파이프라인 (modular skill pipeline)**입니다. 6개의 독립적인 모듈이 있으며, 각 모듈은 고유한 AI 프롬프트 명세(SKILL.md)를 가지고, 공유된 도메인 모델(Domain Model)을 변경하는 CLI 명령어를 생성합니다. 플래닝 에이전트(Planning Agent)는 어떤 모듈을 어떤 순서로 활성화할지 결정합니다.

6개의 모듈

사용자 입력 → [플래닝 에이전트 (Plan Agent)] → 작업 시퀀스 (Task Sequence) → 실행 엔진 (Execution Engine) → 게시된 앱

모듈:
...

각 모듈은 다음을 포함합니다:

• AI의 시스템 프롬프트(명령어, 규칙, 예시) 역할을 하는 SKILL.md 파일
• 도메인 모델을 변경하기 위한 CLI 명령어 세트 (CLI command set)
• 참조 (References) — AI가 명령어를 생성하기 전에 읽는 런타임 데이터 (현재 입력 필드, 척도 차원, 보고서 페이지 등)

AI는 코드를 직접 작성하지 않습니다. 대신 CLI 명령어를 작성합니다. 실행 엔진은 이 명령어들을 도메인 모델에 대해 실행합니다.

플래닝 에이전트 (The Plan Agent)

플래닝 에이전트는 두뇌 역할을 합니다. 사용자 입력을 받아 YAML 형식의 작업 목록을 출력합니다:

planType: assessment
description: 'Workplace Stress Assessment'
tasks:
...

knowledge 필드가 매우 중요합니다. 이는 각 기술(Skill)이 실행 중에 받는 **유일한 컨텍스트 (context)**입니다. 작업 A의 지식은 작업 B로 유출되지 않습니다. 이로 인해 각 지식 블록은 차원(Dimensions), 질문 개수, 채점 규칙 등 모든 것을 스스로 포함하는 독립적인 형태를 갖추어야 합니다.

이는 뼈아픈 교훈이었습니다. 초기 버전에서는 "위와 동일" 또는 "form task 참조"와 같이 다른 작업을 참조하는 태스크들이 있었습니다. 실행 엔진(Execution engine)은 각 태스크를 독립적으로 실행하기 때문에, 이러한 참조들은 아무것도 찾아내지 못했습니다. 결과적으로 생성된 앱의 절반이 제대로 작동하지 않았습니다.

실행 엔진 (The Execution Engine)

실행은 SSE 스트리밍 (SSE-streamed) 방식으로 이루어집니다. 각 태스크에 대해 다음 과정을 거칩니다:

1. 해당 스킬(Skill)의 SKILL.md를 시스템 프롬프트(System prompt)로 로드합니다.
2. 태스크의 knowledge와 런타임 참조(현재 앱 상태)를 주입합니다.
3. AI 모델로 SSE 스트림을 시작합니다.
4. AI가 생성하는 각 라인은 CLI 명령입니다 — 이를 즉시 실행합니다.
5. 실행 결과를 다시 실행 컨텍스트(Execution context)에 전달합니다.

Task: form
  AI generates:  assess form add --id name --type input --title "Your Name"
  Engine:        → executes, field created
...

스트리밍 방식을 사용하면 전체 응답이 완료된 후가 아니라, 명령어가 생성되는 즉시 실행됩니다. 이를 통해 일반적인 앱 생성 시 생성 시간을 약 40% 단축했습니다.

도메인 모델 (The Domain Model)

내부적으로는 빌더 패턴 (Builder pattern)을 사용하는 Java 도메인 모델 (Domain model)이 존재합니다:

Flower (root)
  └── Model
       ├── Factor
...

각 CLI 명령어는 이 트리를 변형(Mutate)합니다. SessionContext는 실행 중인 메모리 내 상태를 보유하며, 마지막에 모든 것을 한 번에 배치(Batch)로 영속화(Persist)합니다. 이를 통해 50개의 명령어가 포함된 폼(Form) 태스크를 수행하는 동안 50번의 개별 데이터베이스 쓰기가 발생하는 것을 방지합니다.

두 가지 에이전트 (The Two Agents)

시스템에는 실제로 두 개의 AI 에이전트 (AI agents)가 있습니다:

AssessAgent — 원샷 생성기 (One-shot generator)입니다. 사용자 입력을 받아 → 계획을 세우고 → 실행한 뒤 → 완료합니다. 처음부터 새로운 앱을 만들 때 사용됩니다. 두 단계로 구성됩니다: plan() 및 execute().

BuilderAgent — 대화형 편집기 (Conversational editor)입니다. 기존 앱을 수정할 때 사용됩니다. 네 단계로 구성됩니다: Think (현재 상태 분석) → Plan (PATCH 태스크 생성) → Execute (명령어 스트리밍) → Reflect (AI가 결과를 검증하고 사용자에게 응답).

두 에이전트 모두 동일한 스킬 SKILL.md 파일로 구동됩니다. 차이점은 컨텍스트(Context)입니다: AssessAgent는 빈 상태에서 시작하고, BuilderAgent는 기존 앱의 스냅샷(Snapshot)에서 시작합니다.

다음 단계

이 시리즈에서는 각 모듈과 그 주변 인프라(Infrastructure)를 심층적으로 다룰 예정입니다:

1. [본 포스트] 아키텍처 개요 (Architecture overview)
2. Planning Engine: YAML 작업 라우팅 (task routing) 및 지식 자기 완결성 (knowledge self-containment)
3. Form Module: 장면 인식 필드 타입 (Scene-aware field types) 및 인라인 스코어링 (inline scoring)
4. Scale Module: 차원 방향 문제 (dimension direction problem) 해결
5. Connect Module: AI 기반 커버 페이지 및 시각적 스타일
6. Report Module: 페이지 템플릿 기반 PDF 생성
7. Expert Module: AI 어시스턴트에게 페르소나 (personality)와 경계 (boundaries) 부여하기
8. 원클릭 파이프라인 (The One-Click Pipeline): 단일 SSE 스트림이 모든 것을 오케스트레이션 (orchestrate)하는 방법
9. SSE 신뢰성 (SSE Reliability): 이벤트 손실을 해결하기 위한 세 차례의 수정 과정
10. PDF 렌더링 전쟁 (PDF Rendering War): SVG, 이모지 (emoji), 그리고 iText NPE

각 포스트에는 실제 코드, 실제 버그, 그리고 프로덕션 (production) 환경에서 살아남은 해결책들이 포함되어 있습니다.

이 시리즈는 평가 플랫폼의 아키텍처를 기록합니다. 저는 제품을 홍보하려는 것이 아니라, 엔지니어링 결정과 실패 사례들을 공유하고자 합니다. 만약 여러분이 유사한 것(AI 기반 코드 생성, 모듈형 기술 시스템, PDF 렌더링 파이프라인 등)을 구축하고 있다면, 이 글이 여러분의 고통을 줄여줄 수 있기를 바랍니다.