회고AI용 Markdown 결정 기록과 사람용 HTML 버전 분리
· 알고수
- #agentic-system
- #adr
- #context-engineering
- #documentation
- #llm
최근 안드레이 카파시(OpenAI 공동 창립자, 전 테슬라 AI 디렉터)가 "LLM의 출력은 Markdown보다 HTML이 사람에게 더 좋을 수 있다"는 취지의 이야기를 한 것을 봤습니다.
반응은 크게 두 갈래였습니다.
하나는 좋은 방향이라는 의견이었습니다. LLM의 출력이 단순한 텍스트를 넘어, 사람이 바로 읽고 이해하고 조작할 수 있는 화면이 될 수 있다는 관점이었죠.
다른 하나는 토큰 비용에 대한 우려였습니다. HTML은 Markdown보다 태그가 많아 출력량이 늘고, 그만큼 비용과 응답 시간도 늘 수 있습니다.
처음에는 저도 이 논쟁을 출력 포맷의 문제로만 봤습니다. Markdown이냐 HTML이냐, 간결함이냐 가독성이냐, 토큰 효율이냐 사용자 경험이냐.
그런데 알고수의 결정 기록을 떠올리면서, 같은 문제가 이미 제 프로젝트 안에서도 일어나고 있었다는 걸 깨달았습니다.
읽지 않던 ADR
알고수에는 결정 기록(ADR: Architecture Decision Record, 무엇을 왜 그렇게 정했는지 남기는 문서)이 계속 쌓이고 있습니다.
기능을 만들고, 구조를 바꾸고, 장애를 겪고, 다시 고치는 과정에서 중요한 결정을 ADR로 남겨 왔습니다.
이 문서들은 처음부터 사람만을 위한 기록은 아니었습니다. 오히려 여러 AI 에이전트가 프로젝트의 맥락을 잃지 않게 하려는 목적이 컸습니다. 에이전트는 세션이 바뀌면 이전 대화를 기억하지 못하니까요.
어떤 결정을 왜 했는지, 어떤 구조를 더는 쓰지 않기로 했는지, 다음 작업에서 반드시 지켜야 할 제약은 무엇인지. 이런 정보는 에이전트가 다음 작업을 이어갈 때 중요합니다.
그래서 Markdown은 꽤 잘 맞는 선택이었습니다.
- 텍스트 기반이라 Git에서 관리하기 쉽습니다.
- diff가 깔끔합니다.
- 에이전트가 읽기에 불필요한 장식이 적습니다.
- HTML보다 토큰 효율이 좋습니다.
- 구조화된 문서로 유지하기 쉽습니다.
하지만 문제가 있었습니다. 제가 그 문서를 거의 읽지 않게 되었다는 점입니다.
ADR은 분명 쌓이고 있었고, 결정의 이유도 남아 있었습니다. 에이전트들은 그 문서를 참고할 수 있었죠.
그런데 정작 운영자인 저는 프로젝트의 흐름을 다시 따라가야 할 때 Markdown ADR을 잘 열어 보지 않았습니다.
문서가 없어서가 아니었습니다. 문서가 읽히지 않았기 때문입니다.
있는 문서와 읽히는 문서
Markdown은 좋은 포맷입니다. 개발자에게 익숙하고, 저장소에 넣기 쉽고, 코드 리뷰 흐름과도 잘 맞습니다. 저도 대부분의 기록을 Markdown으로 남겨 왔습니다.
하지만 시간이 지나면서 ADR은 점점 길어졌습니다.
스프린트가 쌓이고 결정이 누적되면서, Markdown 문서 하나를 열어 흐름을 따라가는 일이 부담스러워졌습니다.
중요한 결정과 배경, 영향 범위, 후속 작업이 모두 텍스트 안에 섞여 있었습니다. 에이전트는 충분히 읽을 수 있는 구조였지만, 사람이 빠르게 훑고 판단하기에는 피로했습니다.
여기서 한 가지를 인정해야 했습니다.
문서가 저장되어 있다는 것과 사람이 그 문서를 다시 읽을 수 있다는 것은 다른 문제입니다.
ADR의 목적은 "남기는 것"에서 끝나지 않습니다. 나중에 다시 읽고, 그 결정의 이유를 되살리고, 지금의 판단에 연결할 수 있어야 합니다.
그렇지 않으면 문서는 저장소에는 남아 있어도, 실제 유지보수에서는 사라진 것과 비슷해집니다.
에이전트용 문서와 사람용 문서
이 문제를 겪고 나니, Markdown과 HTML 중 무엇이 더 좋으냐는 질문이 다르게 보였습니다.
중요한 건 포맷 자체가 아니라, 문서를 누가 읽느냐였습니다.
알고수의 ADR은 두 가지 역할을 동시에 하고 있었습니다.
첫째는 에이전트의 기억입니다. 여러 에이전트가 이전 결정과 제약을 참고해 같은 실수를 반복하지 않게 돕는 장치입니다.
둘째는 사람의 검토 화면입니다. 운영자인 제가 프로젝트의 흐름을 다시 읽고, 지금 구조가 왜 이렇게 되었는지 이해하기 위한 화면입니다.
문제는 두 독자가 원하는 문서 형태가 다르다는 점입니다.
에이전트에게 Markdown
- 간결합니다.
- 토큰 비용이 낮습니다.
- 파싱하기 쉽습니다.
- Git 기반 워크플로와 잘 맞습니다.
- diff로 변화를 추적하기 쉽습니다.
사람에게 Markdown만으로는
- 긴 문서의 시각적 계층이 약합니다.
- 중요한 결정이 한눈에 들어오지 않습니다.
- 여러 ADR에 걸친 흐름을 따라가기 어렵습니다.
- "읽어야 하지만 읽지 않는 문서"가 되기 쉽습니다.
그래서 결론은 Markdown을 버리고 HTML로 갈아타는 게 아니었습니다. 문서의 독자를 나눠야 했습니다.
두 형태로 나눈 ADR
알고수의 ADR을 HTML로 완전히 바꾸지 않았습니다. 대신 결정 기록을 쓰는 에이전트가 Markdown과 함께 사람을 위한 HTML 버전도 새로 만들도록 고쳤습니다. 같은 결정 기록이 두 가지 형태로 남는 셈입니다.
하나의 기록, 두 가지 형태
Markdown ADR은 계속 에이전트의 기억으로 둡니다.
에이전트가 이전 결정, 제약, 회귀를 막는 규칙, 후속 작업을 읽고 다음 작업을 이어가게 하기 위해서입니다. 여기서는 여전히 간결함과 토큰 효율이 중요합니다.
반면 HTML ADR은 사람이 읽는 검토 화면으로 둡니다.
긴 ADR을 카드, 섹션, 강조, 시각적 계층으로 나눠 다시 읽기 쉽게 만듭니다. 중요한 결정, 배경, 영향, 후속 작업이 한눈에 들어오게 합니다.
즉, 하나의 기록을 두 가지 화면으로 나눈 것입니다.
늘어나는 토큰 비용
물론 이 방식에는 비용이 듭니다.
Markdown만 만들 때보다 출력량이 늘어납니다. HTML 태그와 구조까지 생성해야 하니 토큰도 더 씁니다.
LLM 기반 시스템에서 토큰은 곧 비용입니다. 출력 토큰이 늘면 비용이 늘고, 경우에 따라 응답 시간도 길어집니다.
이 우려는 타당합니다. 저도 이 변경이 전보다 토큰을 더 쓸 거라는 걸 알고 있었습니다.
그래도 이 방식을 골랐습니다. 이 비용은 낭비가 아니라 유지보수를 위한 투자라고 판단했기 때문입니다.
좋지 않은 토큰 절약
LLM 시스템을 만들다 보면 토큰을 줄이는 일이 중요해집니다.
불필요한 컨텍스트를 줄이고, 반복되는 출력을 없애고, 에이전트가 읽어야 할 정보만 남기고, 비용과 응답 시간을 관리해야 합니다.
하지만 모든 토큰 절약이 좋은 최적화는 아닙니다.
사람이 ADR을 읽지 않게 되면, 문서는 있어도 프로젝트의 맥락은 사라집니다.
왜 이 구조를 골랐는지, 왜 저 접근을 버렸는지, 어떤 장애를 막으려고 이 제약을 넣었는지, 어떤 결정이 이후 구조에 영향을 주었는지.
이런 맥락을 사람이 되살리지 못하면, 이후의 디버깅, 리팩토링, 기능 변경은 더 비싸집니다.
토큰은 아꼈지만 사람이 시스템의 기억을 잃는다면, 그건 진짜 최적화가 아닐 수 있습니다.
제가 HTML ADR을 추가한 이유는 보기 좋은 문서를 만들기 위해서가 아닙니다. 유지보수할 수 있는 기억의 화면을 만들기 위해서입니다.
인터페이스로서의 문서
이번 변경을 하면서 문서를 다시 생각하게 되었습니다.
문서는 단순한 저장소가 아닙니다. 특히 AI 에이전트와 함께 일하는 시스템에서 문서는 사람과 에이전트 사이에 프로젝트의 기억을 전달하는 인터페이스에 가깝습니다.
에이전트는 문서로 이전 맥락을 읽고, 사람은 문서로 시스템의 흐름을 되살립니다.
그렇다면 두 독자에게 같은 형태의 문서를 강요할 필요는 없습니다. 에이전트에게는 효율적인 문서가, 사람에게는 읽을 수 있는 문서가 필요합니다.
Markdown과 HTML은 경쟁 관계가 아니라, 서로 다른 독자를 위한 두 가지 형태일 수 있습니다.
결론
처음에는 Markdown과 HTML 중 무엇이 더 좋으냐의 문제처럼 보였습니다.
하지만 알고수의 ADR을 다시 보면서, 제게 더 중요한 질문은 따로 있었습니다.
이 문서는 누구를 위해 존재하는가?
에이전트를 위한 문서는 간결하고 효율적이어야 합니다. 사람을 위한 문서는 다시 읽을 수 있어야 합니다.
그래서 Markdown을 버리지 않았습니다. 대신 HTML을 더했습니다. Markdown은 에이전트의 기억으로 남기고, HTML은 사람의 검토 화면으로 둡니다.
토큰 비용은 늘어납니다. 하지만 사람이 시스템의 기억을 다시 읽을 수 있다면, 그 비용은 유지보수를 위한 투자라고 생각합니다.