캡스톤 프로젝트에서 AI 문서 편집 서비스를 만들며 겪은 트러블슈팅 기록입니다. "입력은 자유로운데 처리는 고정되어 있던" 룰 베이스 챗봇을, 모델이 직접 도구를 선택해 사용하는 에이전트 구조로 바꾼 과정을 정리했습니다.
성과
정해진 루트로만 동작하던 챗봇이 도메인 내 자유 발화를 처리할 수 있게 되었습니다. "이거 수정해줘", "이전 게 더 나은데 되돌려줘", "이 문서도 추가해줘" 같은 발화가 별도 분기 추가 없이 처리됩니다.
들어가며
사용자가 내용 문서와 양식 문서를 넣으면 양식에 맞춰 정리된 문서를 만들어주는 서비스입니다. 여기에 챗봇을 통한 문서 편집 기능이 필요했습니다.
이 글에서는 그중 챗봇 아키텍처를 어떻게 바꿨는지 다룹니다.
문제 상황: 입력은 자유로운데 처리는 고정되어 있다
초기 구조는 LangGraph만으로 구현한 룰 베이스 챗봇이었습니다. 문제는 여기서 발생했습니다.
발화의 입력은 자유롭지만 처리는 제한적이었습니다. 사용자는 아무 말이나 할 수 있는데, 시스템은 미리 정의된 루트로만 반응합니다. 그 결과 사용자의 실제 의도가 전달되지 않았습니다.
우리가 설계한 흐름은 이랬습니다.
문단별 주제문 선정 → 부정문 선정 → 수정
논리적으로는 말이 되지만, 실제로 써보면 전혀 똑똑해 보이지 않았습니다. 사용자는 "이 부분 좀 더 부드럽게 고쳐줘"라고 말하고 싶은데, 시스템은 정해진 순서를 밟으라고 요구합니다. 답답한 경험이었습니다.
처리하지 못하던 것
- 도메인 내 자유 발화 — "이거 수정해줘", "이거 반영해줘", "이 문서도 추가해줘"
- 도메인 밖 발화의 부드러운 마무리 — "근처 밥집 괜찮은 곳 있어?"에 대해 "저는 밥집은 잘 모르지만 문서 관련해서는 도와드릴 수 있어요"라고 답하는 정도
목표
룰 베이스 챗봇을 현대적인 에이전트 시스템으로 전환한다.
단, 도메인 밖 발화와 욕설은 여전히 걸러져야 합니다. 자유도를 올리되 통제는 유지해야 했습니다.
설계: LangGraph를 버리지 않고 역할을 바꾸다
기존 LangGraph 구조를 전부 걷어내는 대신, 역할을 필터와 조건 분기 수준으로 축소했습니다. 실제 작업 수행은 모델이 도구를 직접 가져다 쓰는 LangChain 형태로 옮겼습니다.
판단이 필요한 부분은 모델에게, 규칙으로 충분한 부분은 그래프에게 맡기는 구조입니다.
아키텍처
각 노드의 역할은 다음과 같습니다.
Filtering / Domain Guard
기존 LangGraph 구조를 그대로 사용한 파트입니다. 서비스에 해당하지 않는 발화와 욕설을 판별합니다.
명시적 텍스트 쌍을 미리 만들어두고 벡터 유사도 검색을 수행해, 임계값 이하의 발화만 다음 단계로 넘어갑니다. 이 판단에는 LLM이 필요 없기 때문에 규칙 기반을 유지했습니다.
Style Intent
팀 단위 문서 관리 기능을 제공하다 보니, 팀장이 선호하는 문서 작성 방식이 있을 수 있습니다. 두괄식 같은 것들입니다. 이 정보를 반영해 다음 프롬프트로 넘깁니다.
Plan
사용자 발화를 분석하고 도구 사용 계획을 세웁니다. 다음 노드의 모델이 실제로 도구를 호출할 수 있도록 준비하는 단계입니다.
Dispatcher / Tool Node
실제로 도구를 사용해 문서 편집을 수행합니다. 현재 사용 가능한 도구는 10가지이며, QA를 통해 실제 사용 시나리오에서 필요한 것들을 추려 설계했습니다.
예를 들어 사용자가 이렇게 말했다고 해봅시다.
"아 이전 게 더 나은데? 그리고 내용은 좀 더 보수적으로 잡고 작성해주면 좋을 거 같아."
이 한 문장에 다음 도구들이 동원됩니다.
- 수정 전후 비교
- 수정 취소
- 문서 기반 질의 응답
- 최근 제안 반영
- 필요에 따른 추가 도구
룰 베이스였다면 이 조합마다 분기를 만들어야 했을 겁니다.
문서 형식 복원 도구
가끔 문서 형식이 풀리는 경우가 있었는데, 경험적으로 반복 횟수를 늘리면 해결되는 경우가 많았습니다. 이를 도구로 만든 것입니다.
참고 — 반복 종료 조건에 대해 Claude Code는 도구 호출이 포함되지 않은 응답이 나올 때까지 평가–도구 실행–결과 반영을 반복합니다. 종료 조건이 외부 판정이 아니라 모델의 출력 형태라는 점이 특징이고, 대신 턴 수와 비용 상한으로 폭주를 막습니다.
Feedback
작성된 문서의 각 문장에 대해 가벼운 피드백을 제공합니다. 사용자가 확인할 수 있습니다.
Ban Check
팀장이 금칙어를 설정할 수 있습니다. 회사라면 회장님 성함이나 특정 호칭 자체를 문서에 담을 수 없는 경우가 있습니다. 해당 단어가 들어가면 AI가 작성한 문서에 대해 피드백을 주고 수정할 수 있게 했습니다.
달성
도메인 내에서 자유로운 발화 처리가 가능해졌습니다. 일종의 문서 편집기용 AI 봇이 되었고, 사용자 발화만으로 문서 수정·편집·내용 추가가 모두 처리됩니다.
한계
토큰량을 줄이기 어려운 구조적 제약이 있습니다.
문서를 화면에 보여주려면 Quill 에디터 형식에 맞는 출력이 필요합니다. 그래서 최종 생성물이 단순한 문서가 아니라 일종의 코드에 가까운 형태를 띱니다. 이 때문에 모델 크기를 낮추기 어려워졌습니다.
토큰량 감소와 성능 안정화는 서비스 발전을 위해 둘 다 필요한 목표인데, 현재로서는 이 둘이 매우 강하게 묶여 있습니다.
개선점
Delta 형식은 고정 문법입니다. 프롬프트 조정과 RAG를 활용하면 더 안정적인 성능을 뽑아낼 여지가 있다고 봅니다.
모델 배치를 다시 짤 수 있습니다. 최종 검토 로직을 추가하고 검토 모델의 성능만 높이는 대신 전체 모델 수준은 낮추는 방향, 그리고 내용과 문법을 합치는 로직을 수정하면 비교적 안정적인 밸류업이 가능할 것으로 보입니다.
DB 스키마 설계가 남아 있습니다. 시간과 자원의 한계로 문서 저장 관련 스키마를 자세히 설계하지 못했고, 그만큼 프롬프트 의존적인 부분이 있습니다. DB에 저장된 문서를 다시 꺼내 사용하려면 의미 있는 스키마 추가가 필요합니다.
회고
요즘 에이전트 시스템을 이야기하면 Skills, MCP, Plug-in 등 확장 방식이 정말 다양합니다.
그런데 "우리 서비스가 이런 방식으로 수평 확장이 잘 되는가?"라고 물으면, 솔직히 그걸 염두에 두고 설계하지는 않았습니다.
하지만 그래야 한다고 생각합니다. 커스텀에 열린 서비스가 결국 더 열린 기술로 나아갈 수 있다고 보기 때문입니다.
시리즈에서 이어 읽기 · SHOW-GY 트러블슈팅 →
