anthropics/html-effectiveness 딥다이브
— 마크다운 대신 자기완결 HTML 한 장으로 답하는 에이전트 출력 형식론

1프로젝트 한 줄 요약

핵심은 "예쁜 웹페이지 만들기"가 아니다. 출력 형식의 선택이다. 같은 내용을 마크다운으로 주면 스크롤해야 할 텍스트가 되지만, HTML로 주면 한눈에 들어오는 공간 배치가 된다. 이 저장소는 그 차이가 실제로 얼마나 큰지를, 말로 설명하는 대신 열어서 보게 만든다.

2왜 주목받는가

이 저장소가 흥미로운 이유는 규모나 별점이 아니라 관점이다. LLM/에이전트가 보편화되면서 "모델이 무엇을 어떻게 내놓아야 하는가"가 실무 문제가 됐는데, 대부분의 도구는 관성적으로 마크다운을 뱉는다. 이 갤러리는 그 기본값에 정면으로 반문한다.

3기술 스택 전체 지도

대부분의 프론트엔드 프로젝트가 React·번들러·수십 개 의존성으로 시작하는 것과 정반대다. 여기엔 그런 게 하나도 없다. 그리고 그 "없음"이 곧 메시지다.

4아키텍처 심화 분석

모든 예제가 공유하는 아키텍처는 두 문장으로 요약된다: ① 구조·스타일·행동·데이터를 한 파일에 인라인해 자기완결로 만든다. ② 편집형 예제는 반드시 export로 끝나 산출물을 다음 프롬프트로 왕복시킨다.

핵심 설계 ① — 자기완결이 주는 세 가지 공짜 이득

이식성(어느 기기·브라우저에서나 동일), 수명(의존성이 썩지 않으니 오래 열림), 왕복 가능성(파일 하나라 통째로 다음 프롬프트에 붙여넣기 쉬움). 번들러를 버린 대가로 이 셋을 얻는다. 에이전트 산출물에서 이 셋은 특히 값지다 — 산출물이 대화 밖으로 나가도 혼자 살아남기 때문이다.

핵심 설계 ② — 점진적 공개(progressive disclosure)

리서치·설명 예제는 <details> 접이식 섹션, 탭 전환 코드 샘플, 여백의 용어집으로 정보를 층으로 감춘다. 같은 단어를 선형으로 쏟아붓는 것과, "TL;DR 먼저 → 펼치면 단계별 상세 → 옆에 hover 용어집"으로 주는 것은 읽는 경험이 전혀 다르다. HTML만이 이 탐색 가능한 골격을 만든다.

핵심 설계 ③ — 인라인 SVG = 에이전트의 진짜 펜

다이어그램 예제는 이미지 파일을 부르지 않고 <svg>를 소스에 직접 그린다. 그래서 산출물이 손으로 좌표 몇 개만 고쳐도 되는 벡터가 되고, 최종 문서에 그대로 복사돼 들어간다. "AI가 그림을 그린다"가 픽셀 생성이 아니라 편집 가능한 벡터 소스 생성일 수 있음을 보여준다.

핵심 설계 ④ — 사람을 루프에 남기는 export

편집 UI 3종(트리아지 보드·기능 플래그·프롬프트 튜너)의 진짜 주인공은 UI가 아니라 마지막의 export다. 드래그로 만든 상태를 텍스트로 뱉지 못하면 그 UI는 막다른 길이다. export가 있어야 "에이전트가 UI를 만들고 → 사람이 UI에서 결정하고 → 결정이 텍스트로 돌아가 에이전트가 이어받는" 순환이 닫힌다.

5디렉토리 구조 해부

구조가 말하는 것: 계층이 없다는 게 의도다. 빌드 폴더도, src/도, 설정 파일도 없다. 각 .html은 이웃과 무관하게 혼자 완결돼 있고, index.html은 그저 이들을 일의 종류로 묶어 보여주는 안내판일 뿐이다 — 그 index 자신도 물론 자기완결 HTML 한 장이다.

6학습 포인트

실습 아이디어 (짧게)

예제 하나(15-research-concept-explainer.html 추천)를 브라우저로 열어 보고, 곧바로 소스를 열어 같은 파일 안에 구조·스타일·상호작용이 어떻게 다 들어 있는지 눈으로 확인하라. "라이브 링을 돌리는 JS가 고작 몇십 줄"이라는 사실이 자기완결의 힘을 각인시킨다.

7시스템 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크