코딩 에이전트가 구조화된 질문에 답하지 못하는 이유: 지식 베이스의 구조화 부재

저는 코딩 에이전트에게 마크다운 파일 폴더에 대한 접근 권한을 주어 장기 기억으로 활용하고 있습니다. "왜 DynamoDB 대신 Postgres를 선택했지?" 혹은 "auth 재작성 뒤에 숨겨진 맥락은 뭐야?" 같은 개방형 질문에는 놀라울 정도로 잘 작동합니다. 에이전트는 올바른 문서를 찾아 읽고 확실한 답변을 내놓죠.

그런데 팀원이 이렇게 물었습니다: "우리 API 결정 사항 중 아직 초안(draft) 상태인 게 뭐야?"

에이전트는 모든 결정 문서를 읽었습니다. 40초나 걸렸죠. 본문에 "draft"라는 단어가 없어서 두 개를 놓쳤습니다. 제가 아직 작성을 끝내지 않았던 것들이었거든요. 반면 다른 맥락에서 "이 접근 방식은 아직 초안 아이디어입니다"라고 적힌 문서를 보고는 "초안"이라고 환각을 일으키기도 했습니다.

실패 원인은 분명했습니다. 비구조화된 데이터에 구조화된 질문을 던지고 있었던 거죠. 에이전트는 본질적으로 데이터베이스 쿼리여야 할 것을 자연어 처리를 통해 추출해야 했습니다. 당연히 틀릴 수밖에요.

해결책은 모든 문서에 YAML 프론트매터를 추가하는 것이었습니다:

---
title: "Use Postgres for the event store"
type: decision
status: accepted
domain: infrastructure
created: 2026-01-15
---

이제 모든 문서는 기계가 읽을 수 있는 필드로 자체 메타데이터를 가집니다. 에이전트가 추측할 필요 없이 상태, 유형, 도메인, 날짜, 관계 등을 모두 쿼리할 수 있게 된 거죠.

이전에는 40초가 걸리고 틀리기까지 했던 쿼리가 이제는 이렇게 바뀝니다:

iwe find --filter 'status: draft' --project title,domain,created -f json

즉각적이고, 정확하며, 토큰 비용도 들지 않습니다.

이런 방식으로 메타데이터를 모델링하기 시작하자, 예전에는 에이전트가 "생각"해야 했던 질문들이 사소한 조회 작업으로 바뀌었습니다:

iwe find --filter '{type: decision, domain: infrastructure}' --project title,status -f json

iwe count --filter 'status: draft'

iwe find --filter '{status: published, created: { $gte: "2026-04-01" }}' \
  --sort created:-1 --project title,domain -f json

여기서 패턴이 하나 도출되었습니다. 지식 베이스에 던지는 질문은 두 가지 종류가 있습니다.

탐색형 질문 — "X에 대해 알려줘" — 에이전트가 문서를 읽고 답변을 종합하길 원할 때입니다. 전체 텍스트 검색이 잘 작동합니다. 내용이 중요하죠.

구조화된 질문 — "상태 Y인 X가 몇 개야" — 답변이 필터링, 카운트, 정렬인 경우입니다. 이런 질문은 LLM에 절대 닿아서는 안 됩니다. 데이터베이스 쿼리니까요. 지식 베이스가 모든 문서를 읽지 않고도 답할 수 없다면, 한 계층이 빠진 겁니다.

프론트매터가 바로 그 계층입니다. 각 문서를 타입이 지정된 열을 가진 행으로 바꾸면서, 본문은 탐색형 질문을 위한 자유 형식의 산문으로 남겨두는 거죠. 에이전트는 구조화된 질문에는 CLI 쿼리를 사용하고, 나머지는 문서 검색을 사용합니다.

트레이드오프는 다음과 같습니다:

• 스키마를 정의하고 유지 관리해야 합니다. 프론트매터를 채우는 데 소홀하면 쿼리 결과는 쓰레기가 됩니다. 쓰레기가 들어가면 쓰레기가 나옵니다.
• 기존 문서를 수정하는 초기 작업이 필요합니다. 하지만 여기서 빠르고 저렴한 모델이 빛을 발합니다. 저는 각 문서에 간단한 프롬프트를 던졌습니다: "이 문서를 읽고 type, status, domain, created date 필드를 추출해서 YAML로 반환해." 문서당 비용은 거의 들지 않고 정확도도 놀라울 정도입니다. 전체 지식 베이스를 1분도 안 되어 몇 센트의 비용으로 처리했습니다. 빠른 모델들은 전체 지식 베이스를 추론하는 데는 능숙하지 않지만, 문서 하나를 읽고 메타데이터를 뽑아내는 데는 완벽합니다. 10% 정도를 검수하고 몇 개의 오류만 수정했습니다. 손으로 직접 태깅하는 것보다 훨씬 빠릅니다.