토큰 비용을 더 쓰기로 했다 — 사람을 위한 ADR 뷰 만들기

최근 안드레이 카파시가 "LLM 출력은 Markdown보다 HTML이 사람에게 더 좋을 수 있다"는 취지의 이야기를 한 것을 봤습니다.

반응은 크게 두 갈래로 나뉘었습니다.

하나는 좋은 방향이라는 의견이었습니다. LLM의 출력이 단순한 텍스트를 넘어 사람이 바로 읽고, 이해하고, 조작할 수 있는 UI가 될 수 있다는 관점이었죠.

다른 하나는 토큰 비용에 대한 우려였습니다. HTML은 Markdown보다 태그가 많고, 출력량이 늘어나며, 그만큼 비용과 latency가 증가할 수 있습니다.

처음에는 저도 이 논쟁을 단순히 출력 포맷의 문제로 봤습니다.

Markdown이냐, HTML이냐. 간결함이냐, 가독성이냐. 토큰 효율이냐, 사용자 경험이냐.

그런데 AlgoSu의 ADR 문서를 떠올리면서, 이 문제가 이미 제 프로젝트 안에서도 발생하고 있었다는 걸 깨달았습니다.

ADR은 있었지만, 저는 읽지 않았습니다

AlgoSu에는 ADR이 계속 쌓이고 있습니다.

기능을 만들고, 구조를 바꾸고, 장애를 겪고, 다시 고치는 과정에서 중요한 의사결정을 ADR로 남겨왔습니다.

이 문서들은 처음부터 사람만을 위한 기록은 아니었습니다. 오히려 여러 agent들이 프로젝트의 맥락을 잃지 않도록 하기 위한 목적이 컸습니다.

어떤 결정을 왜 했는지, 어떤 구조를 더 이상 쓰지 않기로 했는지, 어떤 제약을 다음 작업에서 반드시 지켜야 하는지.

이런 정보는 agent들이 다음 작업을 이어갈 때 중요합니다.

그래서 Markdown은 꽤 잘 맞는 선택이었습니다.

• 텍스트 기반이라 Git에서 관리하기 쉽습니다.
• diff가 깔끔합니다.
• agent가 읽기에 불필요한 장식이 적습니다.
• HTML보다 토큰 효율이 좋습니다.
• 구조화된 문서로 유지하기 쉽습니다.

하지만 문제가 있었습니다. 제가 그 문서를 거의 읽지 않게 되었다는 점입니다.

분명 ADR은 쌓이고 있었습니다. 결정의 이유도 남아 있었죠. agent들은 그 문서를 참고할 수 있었습니다.

그런데 정작 운영자인 저는 프로젝트의 흐름을 다시 따라가야 할 때 Markdown ADR을 잘 열어보지 않았습니다.

문서가 없어서가 아니었습니다. 문서가 읽히지 않았기 때문이었습니다.

문서가 존재한다는 것과 읽힌다는 것은 다릅니다

Markdown은 좋은 포맷입니다.

특히 개발자에게 익숙하고, 저장소에 넣기 쉽고, 코드 리뷰 흐름과도 잘 맞습니다. 저 역시 대부분의 기록을 Markdown으로 남겨왔습니다.

하지만 시간이 지나면서 ADR은 점점 길어졌습니다.

스프린트가 쌓이고, 결정이 누적되고, 과거의 맥락이 많아질수록 하나의 Markdown 문서를 열어 흐름을 따라가는 일이 부담스러워졌습니다.

문서는 분명히 존재했지만, 사람 입장에서 다시 읽기 좋은 형태는 아니었습니다.

중요한 결정과 배경, 영향 범위, 후속 작업이 모두 텍스트 안에 섞여 있었습니다. agent에게는 충분히 읽을 수 있는 구조였지만, 사람이 빠르게 훑고 판단하기에는 피로도가 높았습니다.

여기서 한 가지를 인정해야 했습니다.

문서가 저장되어 있다는 것과 사람이 그 문서를 다시 읽을 수 있다는 것은 다른 문제입니다.

ADR은 단순히 "남기는 것"이 목적이 아닙니다. 나중에 다시 읽고, 그 결정의 이유를 복원하고, 현재의 판단에 연결할 수 있어야 합니다.

그렇지 않으면 문서는 저장소에는 남아 있지만, 실제 유지보수에서는 사라진 것과 비슷해집니다.

Agent를 위한 문서와 사람을 위한 문서는 다릅니다

이 문제를 겪고 나니, Markdown과 HTML 중 무엇이 더 좋은가라는 질문이 조금 다르게 보였습니다.

중요한 것은 포맷 자체가 아니었습니다. 문서를 누가 소비하느냐였습니다.

AlgoSu의 ADR은 두 가지 역할을 동시에 하고 있었습니다.

첫 번째는 agent memory입니다. 여러 agent가 이전 결정과 제약을 참고하고, 같은 실수를 반복하지 않도록 돕는 기억 장치입니다.

두 번째는 human review surface입니다. 운영자인 제가 프로젝트의 흐름을 다시 읽고, 지금의 구조가 왜 이렇게 되었는지 이해하기 위한 검토 화면입니다.

문제는 이 두 소비자가 원하는 문서 형태가 다르다는 점입니다.

Agent에게는 Markdown이 좋습니다.

• 간결합니다.
• 토큰 비용이 낮습니다.
• 파싱하기 쉽습니다.
• Git 기반 워크플로우와 잘 맞습니다.
• diff를 통해 변화 추적이 쉽습니다.

반면 사람에게는 Markdown만으로 부족할 때가 있습니다.

• 긴 문서의 시각적 계층이 약합니다.
• 중요한 결정이 한눈에 들어오지 않습니다.
• 여러 ADR의 흐름을 따라가기 어렵습니다.
• "읽어야 하지만 읽지 않는 문서"가 되기 쉽습니다.

그래서 결론은 Markdown을 버리고 HTML로 완전히 갈아타는 것이 아니었습니다. 문서의 소비자를 분리해야 했습니다.

그래서 ADR을 두 개의 표면으로 나눴습니다

저는 AlgoSu의 ADR을 HTML로 완전히 전환하지 않았습니다.

대신 같은 의사결정 기록을 두 가지 형태로 생성하도록 수정했습니다.

• agent를 위한 Markdown ADR
• 사람을 위한 HTML ADR

Markdown ADR은 계속 agent memory로 남깁니다.

agent들이 이전 의사결정, 제약, 회귀 방지 규칙, 후속 작업을 읽고 다음 작업을 이어갈 수 있도록 하기 위해서입니다. 이 영역에서는 여전히 간결함과 토큰 효율이 중요합니다.

반면 HTML ADR은 사람이 읽기 위한 review surface로 둡니다.

긴 ADR을 카드, 섹션, 강조, 시각적 계층으로 나누어 다시 읽기 쉽게 만듭니다. 중요한 결정, 배경, 영향, 후속 작업을 한눈에 파악할 수 있도록 합니다.

즉, 하나의 기록을 두 개의 view로 나눈 것입니다.

Markdown은 agent에게 남기고, HTML은 사람에게 제공합니다.

이 변경은 HTML로 갈아탄 것이 아닙니다. 문서의 소비자를 분리한 것입니다.

토큰 비용은 증가합니다

물론 이 방식에는 비용이 듭니다.

Markdown만 생성할 때보다 출력량이 늘어납니다. HTML 태그와 구조를 함께 생성해야 하므로 토큰도 더 많이 사용합니다.

LLM 기반 시스템에서 토큰은 곧 비용입니다. 출력 토큰이 늘어나면 비용이 증가하고, 경우에 따라 응답 시간도 길어질 수 있습니다.

이 우려는 타당합니다. 저도 이 변경이 기존보다 더 많은 토큰을 사용할 것이라는 점을 알고 있었습니다.

그럼에도 이 방식을 선택했습니다.

왜냐하면 이 비용은 단순한 낭비가 아니라 유지보수를 위한 투자라고 판단했기 때문입니다.

모든 토큰 절약이 좋은 최적화는 아닙니다

LLM 시스템을 만들다 보면 토큰을 줄이는 일이 중요해집니다.

불필요한 컨텍스트를 줄이고, 반복되는 출력을 제거하고, agent가 읽어야 할 정보만 남기고, 비용과 latency를 관리해야 합니다.

하지만 모든 토큰 절약이 항상 좋은 최적화는 아닙니다.

사람이 ADR을 읽지 않게 되면, 문서는 있어도 프로젝트의 맥락은 사라집니다.

왜 이 구조를 선택했는지, 왜 이 접근을 버렸는지, 어떤 장애를 막기 위해 이 제약을 추가했는지, 어떤 결정이 이후 구조에 영향을 주었는지.

이런 맥락을 사람이 복원하지 못하면 이후의 디버깅, 리팩토링, 기능 변경은 더 비싸집니다.

토큰은 아꼈지만 사람이 시스템의 기억을 잃는다면, 그건 진짜 최적화가 아닐 수 있습니다.

제가 HTML ADR을 추가한 이유는 보기 좋은 문서를 만들기 위해서가 아닙니다. 유지보수 가능한 기억의 표면을 만들기 위해서입니다.

문서는 저장소가 아니라 인터페이스입니다

이번 변경을 하면서 문서를 다시 생각하게 되었습니다.

문서는 단순한 저장소가 아닙니다.

특히 agentic system에서 문서는 사람과 agent 사이에서 프로젝트의 기억을 전달하는 인터페이스에 가깝습니다.

agent는 문서를 통해 이전 맥락을 읽고, 사람은 문서를 통해 시스템의 흐름을 복원합니다.

그렇다면 두 소비자에게 같은 형태의 문서를 강요할 필요는 없습니다.

agent에게는 효율적인 문서가 필요합니다. 사람에게는 읽을 수 있는 문서가 필요합니다.

Markdown과 HTML은 경쟁 관계가 아니라 서로 다른 표면일 수 있습니다.

결론

처음에는 Markdown과 HTML 중 무엇이 더 좋은가의 문제처럼 보였습니다.

하지만 AlgoSu의 ADR을 다시 보면서, 제게 더 중요한 질문은 달랐습니다.

이 문서는 누구를 위해 존재하는가?

Agent를 위한 문서는 간결하고 효율적이어야 합니다. 사람을 위한 문서는 다시 읽을 수 있어야 합니다.

그래서 저는 Markdown을 버리지 않았습니다. 대신 HTML을 추가했습니다.

Markdown은 agent의 기억으로 남기고, HTML은 사람의 검토 화면으로 제공합니다.

토큰 비용은 늘어납니다. 하지만 사람이 시스템의 기억을 다시 읽을 수 있다면, 그 비용은 유지보수를 위한 투자라고 생각합니다.