🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

저자는 장문의 에이전트 실행 결과를 채팅에 그대로 넣는 대신, Markdown은 원본으로 남기고 HTML은 사람이 읽는 보고서로 분리했더니 거의 추가 비용 없이 검토 품질과 피로도가 크게 개선됐다고 주장한다.

📌 핵심 요약

• 저자는 처음에는 Markdown이 단순하고 검색·버전관리·에이전트 간 전달에 유리하다고 보고 HTML 전환을 취향 문제로 여겼다.
• 하지만 X Manager의 크론 작업 결과가 Telegram에 2,000단어짜리 긴 Markdown으로 쌓이면서, 내용은 맞아도 사람이 읽기 어려운 문제가 반복됐다.
• 새 방식은 Telegram에는 5줄 요약만 보내고, Markdown은 content/memory/daily/에 원본으로 저장하며, HTML은 사람이 검토할 보고서로 제공하는 구조다.
• 실제 벤치마크에서 22.4KB Markdown을 HTML로 렌더링하는 추가 비용은 약 51ms였고, 저자는 이를 장시간 실행되는 에이전트 작업에서는 무시 가능한 수준으로 본다.
• 핵심은 “예쁜 HTML”이 아니라 출처, 사용자 지시, 상태, 위험, 도구 사용, 승인 필요 여부, 다음 행동을 포함하는 artifact contract를 갖추는 것이다.
• 저자는 이 원칙을 Claude Code, Codex, 장기 실행 subagent 등 1~2분 이상 걸리는 에이전트 작업 전반에 적용할 수 있다고 본다.

🧩 주요 포인트

1. Markdown 자체가 문제가 아니라, Markdown을 사람이 최종 검토하는 화면으로 사용한 것이 병목이었다.
2. Telegram 같은 메신저는 5줄 알림에는 적합하지만 2,000단어 기술 보고서를 읽는 공간으로는 부적합하다는 것이 저자의 판단이다.
3. 새 전달 구조는 Source = Markdown, Report = HTML, Summary = chat이라는 역할 분리를 따른다.
4. HTML 렌더링 비용은 저자가 측정한 사례에서 51ms 수준이었고, 실제 부담은 렌더링이 아니라 사람이 긴 텍스트를 읽는 인지 비용이었다.
5. 장기 실행 에이전트의 결과물은 단순 출력이 아니라 사람이 판단하고 승인할 수 있는 artifact contract로 설계되어야 한다.
6. 특히 공개 게시처럼 사용자 승인이 필요한 작업에서는 “확인 필요 여부”가 보고서의 핵심 필드가 된다.

🧠 상세 정리

1. 문제는 Markdown이 아니라 검토 표면이었다

저자는 Thariq의 “Using Claude Code: The Unreasonable Effectiveness of HTML”을 처음 읽었을 때 Markdown을 HTML로 대체해야 한다는 주장에 크게 동의하지 않았다. Markdown은 단순하고, diff가 쉽고, grep이 가능하며, 토큰 비용이 낮고, 에이전트 간 전달에도 적합하기 때문이다. 따라서 저자는 HTML 전환을 구조적 개선보다는 취향의 문제로 보았다. 하지만 html-anything 저장소의 “Markdown is the draft, HTML is what humans read”라는 문구를 보고 관점을 바꿨다. 원문에서 저자가 발견한 핵심은 Markdown이 나쁘다는 뜻이 아니라, Markdown을 사람이 장문의 보고서로 읽는 최종 화면으로 쓰는 것이 문제였다는 점이다. 즉, Markdown은 원본과 작업물의 중간 형식으로는 적합하지만, 사람이 매일 판단을 내려야 하는 리뷰 표면으로는 한계가 있었다.

2. 기존 방식의 병목은 채팅에 쌓이는 긴 보고서였다

저자가 운영하는 X Manager는 타임라인 스캔, 멘션 확인, 주요 계정 집계, 초안 묶음 생성, 의사결정 표면화 등 하루에 여러 단계를 수행한다. 각 단계가 끝날 때마다 에이전트는 소스 데이터, 크론 실행 기록, 위험 요소, 다음 행동을 포함한 약 2,000단어 분량의 내용을 Telegram에 한꺼번에 보냈다. 내용 자체는 맞았지만 문제는 읽을 수 없다는 데 있었다. 채팅창은 긴 벽처럼 변했고, 중요한 상태는 묻혔으며, 다음 단계는 이전 단계의 핵심을 정확히 파악하기 어려웠다. 저자는 처음에는 요약 제약을 강화하면 해결될 문제라고 생각했지만, 이후 길이보다 더 근본적인 문제가 있음을 깨달았다. Telegram은 5줄 알림에는 적합하지만, 2,000단어짜리 기술 보고서를 검토하는 공간으로 설계된 도구가 아니라는 것이다.

3. 새 전달 계약: Markdown, HTML, chat의 역할 분리

저자는 에이전트 크론 작업의 출력 계약을 바꿨다. 각 실행은 이제 세 가지 결과물을 남긴다. 첫째, Telegram에는 판정, 단계 상태, 다음 행동만 담은 5줄 요약을 보낸다. 둘째, content/memory/daily/ 아래에는 다음 에이전트가 읽을 수 있는 지속적인 Markdown 파일을 저장한다. 셋째, gateway의 outbound directory에는 사람이 읽기 위한 HTML 보고서를 생성한다. 이 구조에서 Markdown은 여전히 source of truth다. 다음 에이전트가 읽고, 검색하고, 인덱싱하고, 버전관리할 수 있는 원본이다. HTML은 사람이 열어보고, 훑어보고, 전달하고, 다음 단계를 확인하기 위한 handoff 형식이다. Telegram은 더 이상 보고서 저장소나 리뷰 화면이 아니라 알림 채널로 축소된다. 저자의 thesis는 Markdown을 버리자는 것이 아니라, 각 형식이 맡아야 할 일을 분리하자는 데 있다.

4. 51ms 비용보다 컸던 것은 인지 비용이었다

저자는 12:30 단계에서 벤치마크를 수행했다. 22.4KB의 source Markdown을 로컬에서 읽는 데 0.000016초가 걸렸고, Markdown을 HTML로 렌더링하는 데 0.0508초가 걸렸다. 즉, 실행당 추가 렌더링 비용은 약 51ms였다. 몇 분 동안 실행되는 에이전트 작업에서 이 정도 오버헤드는 저자 기준으로 사실상 잡음 수준이다. 저자가 예상한 비용은 렌더링 스캐폴딩, 저장 경로 연결, downstream review flow 재구성 같은 구현 부담이었다. 그러나 실제 작업은 크론 출력 함수 변경, HTML 템플릿 추가, artifact를 outbound directory에 쓰는 세 단계에 가까웠다. 반대로 실제로 부담이 되었던 것은 매일 Telegram을 열어 긴 텍스트 벽을 읽어야 하는 인지 비용이었다. 이 지점에서 “왜 중요한가”가 드러난다. 에이전트가 일을 잘해도 사람이 결과를 읽고 승인할 수 없다면, 자동화의 마지막 단계가 병목이 된다.

5. 예쁜 HTML만으로는 부족하고 artifact contract가 필요하다

저자는 단순히 HTML로 렌더링하는 것만으로는 충분하지 않다고 강조한다. 사용 가능한 에이전트 보고서가 되려면 이전 단계가 본 것과 사용한 소스를 담은 source chain, 그날 사용자의 최신 지시, 현재 단계 상태, 위험과 사실적 가드레일, 예산과 사용 도구, 공개 행동에 사용자 확인이 필요한지 여부, 다음 행동이 포함되어야 한다. 이것이 저자가 말하는 artifact contract다. HTML이 보기 좋더라도 이러한 필드가 없으면, 그것은 잘 포맷된 낭비 문서에 가깝다. 특히 저자는 X에 게시하는 행동에는 수동 승인이 필요하다고 밝히며, public action confirmation 여부를 중요한 필드로 본다. 이는 장기 실행 에이전트의 출력물이 단순한 로그가 아니라, 사람이 책임 있게 다음 결정을 내리기 위한 검토 단위여야 한다는 관점이다.

6. 장기 실행 에이전트 전반에 적용되는 원칙

저자는 이 규칙을 X Manager에만 한정하지 않는다. Claude Code의 긴 작업, Codex의 batch refactor, 여러 단계를 거치는 subagent 작업처럼 1~2분 이상 걸리는 실행이라면, 결과가 채팅창의 긴 텍스트 벽으로 끝나서는 안 된다고 본다. 대신 Source = Markdown, Report = HTML, Summary = chat이라는 세 조각의 artifact contract로 마무리되어야 한다는 주장이다. 이 주장의 기존 방식과의 차이는 “에이전트가 무엇을 출력하느냐”보다 “사람과 다음 에이전트가 각각 어디에서 무엇을 읽느냐”에 초점을 둔다는 점이다. 기존 방식은 하나의 채팅 출력에 로그, 보고서, 다음 행동, 판단 근거를 모두 넣었다. 저자의 새 방식은 기계가 읽을 원본, 사람이 검토할 보고서, 즉시 확인할 알림을 분리한다. 그 결과 저자는 하루 중 가장 성가셨던 부분이 사라졌고, 다시 돌아갈 생각이 없다고 결론 내린다.

🧾 핵심 주장 / 시사점

• Markdown은 에이전트와 시스템을 위한 원본 형식으로 유용하지만, 사람이 장문의 결과물을 검토하는 최종 표면으로는 적합하지 않을 수 있다.
• 장기 실행 에이전트의 산출물은 채팅 메시지가 아니라, 원본·보고서·알림이 분리된 artifact contract로 설계해야 한다.
• HTML 전환의 기술적 비용은 사례에 따라 작을 수 있으며, 실제 병목은 렌더링 비용보다 사람의 읽기 피로와 의사결정 비용일 수 있다.
• 공개 게시나 외부 액션이 포함된 자동화에서는 “사용자 확인 필요 여부”를 보고서의 명시 필드로 포함하는 것이 중요하다.
• 좋은 에이전트 운영 경험은 모델 성능뿐 아니라, 결과를 사람이 어떻게 읽고 승인하는지에 의해 크게 좌우된다.

✅ 액션 아이템

• X Manager와 유사한 scheduled agent 출력에서 Telegram에 들어가는 내용을 5줄 요약 수준으로 제한할 수 있는지 점검한다.
• content/memory/daily/처럼 다음 에이전트가 읽을 Markdown source of truth 저장 위치를 명확히 분리한다.
• gateway outbound directory에 HTML report를 생성하는 템플릿과 저장 경로를 설계한다.
• HTML 보고서에 source chain, latest user direction, stage state, risks, tools/budget, public action confirmation, next action 필드를 포함한다.

❓ 열린 질문

• 저자의 51ms 렌더링 비용은 22.4KB Markdown 기준인데, 더 큰 보고서나 복잡한 HTML 템플릿에서도 같은 수준의 부담으로 유지될까?
• Markdown source와 HTML report가 동시에 생성될 때, 두 산출물 사이의 불일치나 오래된 보고서를 어떻게 감지하고 관리해야 할까?
• Telegram을 알림 전용으로 축소했을 때, 사용자가 실제 HTML 보고서를 꾸준히 열어보게 만드는 운영 흐름은 어떻게 설계하는 것이 좋을까?