🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

저자는 장문의 에이전트 실행 결과를 채팅에 Markdown으로 쏟아내는 방식 대신, Markdown은 소스·HTML은 인간 검토용 리포트·채팅은 짧은 알림으로 분리하자고 주장한다.

📌 핵심 요약

• 저자는 원래 Markdown이 단순하고 검색·diff·에이전트 간 전달에 유리하다고 보고 HTML 전환을 취향 문제로 여겼다.
• 하지만 X Manager의 여러 cron 작업 결과를 Telegram에 긴 Markdown 형태로 받으면서, 실제 병목은 형식 자체보다 “검토 표면”이라는 점을 깨달았다.
• 새 구조에서는 각 실행 결과가 Telegram 5줄 요약, 영속 Markdown 파일, HTML 리포트라는 세 가지 산출물로 나뉜다.
• 저자가 측정한 추가 렌더링 비용은 실행당 약 51ms였고, 장시간 실행되는 에이전트 작업에서는 무시할 만한 수준이라고 본다.
• 단순히 예쁜 HTML을 만드는 것만으로는 부족하며, 소스 체인·사용자 지시·현재 상태·리스크·도구 사용·승인 필요 여부·다음 행동을 포함하는 “artifact contract”가 필요하다고 강조한다.
• 저자는 이 방식을 Claude Code, Codex, subagent 등 1~2분 이상 걸리는 장기 작업 전반에 적용할 수 있는 규칙으로 일반화한다.

🧩 주요 포인트

1. 문제의 핵심은 Markdown이 아니라, 긴 Markdown 리포트를 채팅 앱에서 읽게 만든 검토 환경이었다.
2. Telegram은 짧은 알림에는 적합하지만, 2,000단어짜리 기술 리포트를 읽고 판단하기 위한 표면은 아니었다.
3. Markdown은 에이전트가 읽고, 검색하고, 버전 관리하는 소스 오브 트루스로 유지된다.
4. HTML은 사람이 읽고, 훑고, 전달하고, 다음 결정을 확인하는 검토용 산출물로 쓰인다.
5. 채팅은 전체 보고서가 아니라 판단·상태·다음 행동만 담은 짧은 알림으로 축소된다.
6. 중요한 것은 HTML 렌더링 자체가 아니라, 장기 실행 에이전트의 산출물을 일관된 계약 구조로 남기는 것이다.

🧠 상세 정리

1. 저자의 출발점: Markdown은 여전히 좋은 소스 형식이다

저자는 처음부터 HTML 우선 접근에 동의했던 것은 아니다. Thariq의 “Using Claude Code: The Unreasonable Effectiveness of HTML”이라는 글이 큰 반응을 얻었고, 그 핵심 주장은 에이전트 출력에서 Markdown이 병목이 되었으며 HTML로 거의 전환했다는 것이었다. 하지만 저자는 당시 이를 취향의 문제로 받아들였다. Markdown은 단순하고, diff가 쉽고, grep으로 검색 가능하며, 토큰 비용도 낮고, 에이전트 간 전달에도 편하기 때문이다. 이 지점에서 저자의 핵심 가정은 “Markdown은 기계와 작업 흐름에 적합한 원천 형식”이라는 것이다. 글은 Markdown을 폐기하자는 주장이 아니다. 오히려 Markdown은 계속 소스 역할을 해야 한다고 본다. 문제는 Markdown을 어디에 쓰느냐였다. 저자가 나중에 발견한 전환점은 “Markdown is the draft, HTML is what humans read”라는 문장이었고, 이 문장은 Markdown과 HTML의 역할 분리를 다시 생각하게 만들었다.

2. 실제 병목: 긴 리포트를 채팅에서 읽는 구조

저자의 X Manager cron은 하루에 10개가 넘는 단계를 실행한다. 타임라인 스캔, 멘션 확인, 주요 계정 집계, 초안 묶음 생성, 의사결정 후보 제시 같은 작업들이 이어지고, 각 단계가 끝날 때마다 에이전트는 소스 데이터, cron 이력, 리스크, 다음 행동을 포함한 약 2,000단어의 내용을 Telegram에 한꺼번에 덤프했다. 저자는 콘텐츠 자체가 틀렸다고 말하지 않는다. 문제는 읽을 수 없었다는 점이다. 채팅은 긴 벽처럼 변했고, 중요한 상태 정보는 묻혔으며, 다음 단계는 이전 단계가 실제로 무엇을 말했는지 추측해야 했다. 처음에는 요약 제약을 더 엄격하게 걸어야 하는 길이 문제라고 생각했지만, 나중에는 길이보다 “채팅 표면이 이 일을 하도록 설계되지 않았다”는 점이 본질이라고 판단했다. Telegram은 5줄짜리 알림에는 적합하지만, 2,000단어짜리 기술 보고서를 검토하는 도구는 아니었다.

3. 새 delivery contract: 소스, 리포트, 알림의 분리

저자는 X Manager의 cron 작업 출력 계약을 바꿨다. 이제 각 실제 실행은 세 가지 산출물을 만든다. 첫째, Telegram에는 판단, 단계 상태, 다음 행동만 담은 5줄 요약이 간다. 둘째, 다음 에이전트가 읽을 수 있는 영속 Markdown 파일이 content/memory/daily/ 아래에 저장된다. 셋째, 사람이 읽을 HTML 리포트가 gateway의 outbound 디렉터리에 생성된다. 이 구조의 핵심은 역할 분리다. Markdown은 소스다. 다음 에이전트가 읽고, grep하고, 인덱싱하고, 버전 관리하는 대상이다. HTML은 사람을 위한 handoff다. 사람은 HTML을 열고, 훑고, 전달하고, 다음 단계를 확인한다. Telegram은 더 이상 긴 보고서가 아니라 알림 채널로만 쓰인다. 기존 방식과의 차이는 단순히 출력 포맷을 Markdown에서 HTML로 바꾼 것이 아니라, 각 매체가 맡아야 할 책임을 다시 정의했다는 데 있다.

4. 51ms의 비용과 실제로 줄어든 인지 비용

저자는 12:30 단계에서 벤치마크를 실행했다. 소스 Markdown은 22.4KB였고, 로컬 읽기는 0.000016초, Markdown-to-HTML 렌더링은 0.0508초가 걸렸다. 실행당 약 51ms의 추가 렌더링 시간이다. 저자는 몇 분 동안 돌아가는 에이전트 작업에서 이 정도 오버헤드는 사실상 노이즈 수준이라고 본다. 중요한 비교 대상은 컴퓨팅 비용이 아니라 인지 비용이다. 저자는 처음에는 렌더링이 부담스러울 것이라고 예상했다. 새 렌더링 구조, 저장 경로 연결, downstream review flow 재구성이 필요할 수 있다고 생각했다. 하지만 실제 변경은 cron 출력 함수 수정, HTML 템플릿 추가, outbound 디렉터리에 artifact 기록이라는 세 단계로 끝났다. 반대로 매일 Telegram을 열어 긴 텍스트 벽을 읽는 일은 하루가 끝날 무렵 머리가 흐려질 정도로 에너지를 소모했다. 저자의 thesis에서 “왜 중요한가”는 바로 여기에 있다. 장기 실행 에이전트의 가치는 결과를 사람이 실제로 읽고 결정할 수 있을 때 실현된다.

5. 예쁜 HTML이 아니라 artifact contract가 필요하다

저자는 단순히 HTML로 예쁘게 렌더링하는 것만으로는 충분하지 않다고 선을 긋는다. 사용할 수 있는 에이전트 리포트에는 반드시 보존되어야 할 필드가 있다. 이전 단계가 무엇을 보았고 어떤 소스를 사용했는지 보여주는 source chain, 그날 사용자의 최신 지시, 현재 단계 상태, 리스크와 사실 관련 가드레일, 예산과 사용한 도구, 공개 행동에 확인이 필요한지 여부, 그리고 다음 행동이 포함되어야 한다. 특히 공개 행동의 수동 승인 여부는 저자에게 중요하다. X에 게시하는 행동은 사용자의 승인 없이 진행되면 안 되기 때문이다. 따라서 HTML은 단지 보기 좋은 결과물이 아니라, 사람이 안전하게 검토하고 승인할 수 있도록 필요한 맥락을 담아야 한다. 저자는 이 구조를 “artifact contract”라고 부른다. 계약이 없으면 예쁘게 포맷된 폐지에 불과하다는 표현은, 형식 개선보다 산출물의 책임 구조가 더 중요하다는 뜻으로 읽힌다.

6. 장기 실행 에이전트 전반으로 확장되는 규칙

저자는 이 규칙을 자신이 운영하는 모든 scheduled agent에 적용했다고 말한다. Claude Code의 긴 작업, Codex의 batch refactor, multi-step reasoning을 수행하는 subagent 등 1~2분 이상 걸리는 작업이라면 채팅 박스에 긴 텍스트 벽을 남기는 방식으로 끝나서는 안 된다는 주장이다. 저자가 도달한 일반 규칙은 간단하다. Source는 Markdown, Report는 HTML, Summary는 chat이다. 이 구조는 에이전트가 남기는 결과를 기계용 원천 자료와 인간용 검토물로 동시에 보존한다. 반론 가능성도 있다. 짧은 작업이나 단순 알림에는 HTML 리포트가 과할 수 있고, 이미 별도 대시보드나 문서 시스템을 운영하는 환경에서는 같은 방식이 그대로 필요하지 않을 수 있다. 그러나 원문이 다루는 조건, 즉 반복 실행되고 단계가 많으며 사람이 최종 결정을 해야 하는 장기 에이전트 흐름에서는 출력 표면의 재설계가 생산성에 직접 연결된다는 것이 저자의 결론이다.

🧾 핵심 주장 / 시사점

• Markdown을 버리자는 주장이 아니라, Markdown을 소스 형식으로 유지하고 인간 검토 표면은 HTML로 분리하자는 주장이다.
• 장기 실행 에이전트의 병목은 모델 성능이나 출력 길이만이 아니라, 사람이 결과를 읽고 판단하는 인터페이스일 수 있다.
• 채팅 앱은 알림 채널로 제한하고, 긴 보고서와 의사결정 맥락은 별도 artifact로 남기는 편이 더 적합하다.
• HTML 리포트의 가치는 보기 좋은 디자인보다 source chain, 리스크, 승인 필요 여부, 다음 행동 같은 검토 계약을 담는 데 있다.
• 에이전트 워크플로가 길어질수록 “무엇을 생성할 것인가”만큼 “어떤 표면에 어떤 책임으로 전달할 것인가”가 중요해진다.

✅ 액션 아이템

• X Manager cron 출력 구조를 Telegram 5줄 요약 + content/memory/daily/ Markdown + outbound HTML report 형태로 점검한다.
• HTML report 템플릿에 source chain, 최신 사용자 지시, stage state, risks, budget/tools, confirmation required, next action 필드를 포함한다.
• 12:30 stage처럼 대표 cron 단계에서 Markdown-to-HTML 렌더링 시간을 측정해 실제 오버헤드를 확인한다.
• X 게시처럼 공개 행동이 포함된 단계에는 수동 승인 여부가 HTML report에 명확히 표시되는지 확인한다.

❓ 열린 질문

• 저자의 구조에서 HTML report가 누적될 경우, 오래된 report의 검색·보관·삭제 정책은 어떻게 설계해야 할까?
• Telegram 5줄 요약에는 어떤 정보까지 포함해야 하고, 어떤 정보부터는 반드시 HTML report로 넘겨야 할까?
• “artifact contract”의 필수 필드는 X Manager 외의 Claude Code, Codex, subagent 작업에서도 동일하게 적용될 수 있을까?