Claude Code 팀의 Thariq Shihipar가 8월 21일 짧은 게시물 하나를 올렸다. 앤트로픽 사람들이 최근 자주 쓰는 스킬이라며 ELI5를 소개했다. 사용법과 지시문은 각각 한 줄이었다.
/eli5 <설명받고 싶은 것>
이 주제를 전혀 모르는 사람에게 설명하듯,
큰 그림과 적은 글로 HTML 자료를 만들어라.함께 올린 영상에는 “Discord 봇은 어떻게 작동하는가”라는 문서가 나온다. 웹사이트, 봇, 데이터베이스, Discord를 상자로 그리고 요청이 오가는 방향을 화살표로 표시한다. 이어서 게임 관리자가 일정을 등록하고, 관리자가 승인하고, 봇이 알맞은 채널에 카드를 올리는 과정을 세 단계로 나눈다. 복잡한 구현을 코드 순서대로 설명하지 않고, 사람과 시스템이 주고받는 일의 순서로 다시 그렸다.
공개 범위는 여기까지다. 앤트로픽이 공식 ELI5 플러그인이나 원본 SKILL.md를 배포한 것은 확인되지 않았다. 따라서 지금 공개된 ELI5는 완성된 도구라기보다 반복해서 쓸 만한 프롬프트를 슬래시 명령으로 묶은 사내 작업 패턴에 가깝다. 그런데 이 짧은 패턴은 코딩 에이전트의 결과를 사람이 검토하는 방법을 꽤 정확하게 짚는다.
HTML로 설명하는 작업의 축약판
ELI5가 갑자기 나온 아이디어는 아니다. Thariq은 지난 5월 The unreasonable effectiveness of HTML에서 Claude Code 팀이 Markdown 대신 HTML을 쓰는 사례를 정리했다.
Markdown은 에이전트가 쓰기 쉽지만 표현 방법이 제한된다. 긴 계획이나 설명은 제목, 문단, 목록이 아래로 계속 이어진다. 구조를 이해하려면 독자가 문장을 읽으며 머릿속에서 모듈과 데이터 흐름을 조립해야 한다. HTML은 같은 정보를 표, 색, 위치, SVG 그림, 탭과 클릭 동작으로 나눌 수 있다. 화면 크기에 따라 배치도 바꿀 수 있고, 파일 하나를 브라우저로 열거나 링크로 공유하기도 쉽다.
Claude Code가 HTML을 만드는 이유도 중요하다. 일반 대화형 모델은 사용자가 붙여 넣은 내용만으로 설명하지만, 코딩 에이전트는 저장소의 파일과 설정, Git 이력, 연결된 업무 도구를 먼저 읽을 수 있다. 실제 코드를 조사한 뒤 그 결과를 사람이 읽기 쉬운 HTML로 바꾸는 흐름이다.
공식 예시 저장소인 anthropics/html-effectiveness에는 이런 결과물 20개가 공개돼 있다. 모듈 지도, 주석이 달린 PR diff, 구현 계획, 장애 타임라인, 기능 설명, 일관 해싱을 직접 조작해 보는 화면까지 범위가 넓다. ELI5는 이 가운데 설명 자료에 필요한 규칙만 남긴 축약판이다. 독자를 초보자로 가정하고, 글보다 그림을 우선하며, 하나의 HTML 문서로 전달한다.
여기서 “한 장”은 한 화면을 뜻하지 않는다. 영상의 결과물도 아래로 스크롤한다. 정확히는 외부 빌드 과정 없이 브라우저에서 열 수 있는 HTML 파일 하나다. 설명의 길이보다 전달 단위가 하나라는 뜻에 가깝다.
구현 전에 이해를 검토하는 단계
코딩 에이전트에게 기능을 맡기면 보통 요청에서 구현으로 바로 넘어간다.
요청 → 코드 조사 → 계획 → 구현 → diff 검토문제는 코드 조사와 계획의 상당 부분이 에이전트의 대화 기록 안에만 남는다는 것이다. 계획이 긴 Markdown 문서로 나오더라도 사람이 모든 호출 관계와 예외 경로를 다시 확인하기는 어렵다. 구현이 끝난 뒤 diff를 보면서 서로 다른 구조를 생각하고 있었다는 사실을 발견하면 수정 범위가 커진다.
ELI5는 코드 조사와 구현 사이에 시각적 검토를 넣는다.
요청 → 코드 조사 → HTML로 구조 설명 → 사람이 확인·수정 → 구현이때 HTML은 초보자용 교육 자료인 동시에 에이전트가 이해한 내용을 보여주는 검토 화면이 된다. 상자 하나가 빠졌거나 화살표 방향이 틀리면 긴 계획서에서 잘못된 문장을 찾는 것보다 빨리 눈에 들어온다. 사람은 “결제 실패는 이 큐를 거치지 않는다”, “이 승인 단계는 관리자가 아니라 자동 작업이 맡는다”처럼 구조를 바로잡을 수 있다. 에이전트는 수정된 지도를 기준으로 구현을 이어간다.
그래서 이름은 ELI5지만, 실제 효용은 설명을 유치하게 만드는 데 있지 않다. 구현 전에 사람과 에이전트가 같은 시스템을 보고 있는지 확인하는 것이 이 패턴의 쓰임이다.
코드 이해, 설계 검토, 장애 분석
가장 단순한 용도는 낯선 모듈을 읽는 일이다.
/eli5 이 저장소에서 사용자가 로그인한 뒤 세션이 만들어지는 과정에이전트는 진입점, 인증 처리, 세션 저장소, 오류 경로를 찾아 하나의 흐름으로 배치할 수 있다. 파일을 하나씩 읽을 때는 놓치기 쉬운 모듈 사이의 관계를 먼저 잡고, 필요한 부분만 코드로 내려갈 수 있다.
설계 검토에서는 선택과 결과를 나란히 놓는 편이 유용하다.
/eli5 이 서비스가 작업 큐를 직접 구현하지 않고 SQS를 선택한 이유와 대안현재 구조, 선택한 방식, 대안, 실패했을 때의 경로를 같은 문서에 그리면 설계 문서의 결론만 읽을 때보다 전제가 잘 보인다. 다만 “왜 선택했는가”는 코드만으로 확정하기 어렵다. ADR, 이슈, PR, 회의 기록처럼 결정 근거가 있는 자료를 함께 읽어야 한다.
장애 분석에서는 시간과 전파 경로를 분리해서 볼 수 있다.
/eli5 이번 장애가 시작된 지점, 영향을 받은 구성요소, 복구된 순서로그와 배포 이력으로 시간표를 만들고, 별도의 그림으로 오류가 어느 서비스까지 번졌는지 표시하면 “먼저 일어난 사건”과 “원인이 된 사건”을 혼동할 가능성이 줄어든다. 확인하지 못한 구간을 빈칸으로 남겨두면 추가 조사 목록으로도 쓸 수 있다.
PR 검토에도 같은 방식이 적용된다. 변경 전후의 데이터 흐름, 새로 생긴 분기, 실패 시 되돌아가는 경로를 먼저 그린 뒤 실제 diff를 연결하면 리뷰어가 어디부터 읽어야 할지 알 수 있다. Thariq이 공개한 HTML 예시에도 주석이 달린 diff와 모듈 지도가 별도 항목으로 들어 있다.
그림이 정확성을 보장하지는 않는다
ELI5의 장점은 동시에 가장 큰 위험이 된다. 잘 정돈된 상자와 화살표는 설명이 정확하다는 인상을 준다. 하지만 그림의 사실성은 에이전트가 어떤 파일과 기록을 읽었는지에 달려 있다. 존재하지 않는 호출 관계를 그리거나, 추측한 설계 의도를 확인된 결정처럼 표시할 수도 있다.
지난 Archify 분석에서 살펴본 것처럼 시각 자료에는 두 종류의 검증이 필요하다. 선이 겹치지 않고 HTML이 제대로 열리는지는 구조와 렌더링 검증이다. 그림이 실제 코드와 일치하는지는 의미 검증이다. ELI5에 공개된 한 줄짜리 지시문에는 어느 쪽의 검증 절차도 포함돼 있지 않다.
사내에서 이 패턴을 쓴다면 지시문에 최소한 다음 조건을 추가할 필요가 있다.
- 설명을 만들기 전에 관련 코드, 설정, 문서와 Git 이력을 조사한다.
- 저장소에 관한 주장에는 파일 경로나 함수·클래스 이름을 표시한다.
- 코드에서 확인한 사실, 기록을 근거로 한 해석, 아직 모르는 내용을 구분한다.
- 장애의 원인과 설계 의도는 근거가 없으면 추측이라고 표시한다.
- HTML을 실제 브라우저에서 열어 잘림, 겹침, 작은 글자를 확인한다.
이 조건을 넣어도 HTML은 보안 검토나 장애 원인 보고서를 대신하지 않는다. 어디를 더 읽어야 하는지 보여주는 첫 지도에 가깝다. 중요한 결론은 원본 코드, 로그, 변경 이력으로 다시 확인해야 한다.
한 줄 프롬프트가 스킬이 되는 이유
Claude Code의 Skills 문서에 따르면 .claude/skills/<이름>/SKILL.md를 만들면 폴더 이름이 슬래시 명령이 된다. 개인 폴더에 두면 모든 프로젝트에서 쓸 수 있고, 저장소에 넣으면 팀이 함께 사용할 수 있다. 스킬은 거대한 확장 프로그램일 필요가 없다. 계속 복사해 쓰는 지시문을 이름 붙여 저장하는 것부터 시작한다.
ELI5는 그 최소 단위를 잘 보여준다. 새로운 모델이나 전용 렌더러를 추가하지 않는다. “전문지식이 없는 독자”, “HTML”, “큰 그림”, “적은 글”이라는 네 가지 제약을 반복 가능한 명령으로 묶었다. 모델은 저장소와 질문에 따라 매번 다른 설명 자료를 만든다.
짧기 때문에 부족한 부분도 분명하다. 출력 경로, 근거 표시, 외부 라이브러리 사용 여부, 브라우저 검토, 실패 보고 규칙은 팀이 정해야 한다. 공개된 문장을 그대로 복사하는 것보다, 자신들의 코드 검토 절차에 맞춰 조사와 검증 조건을 붙이는 편이 낫다.
정리
ELI5를 쉬운 말투를 만드는 프롬프트로만 보면 활용 범위가 좁다. Thariq이 보여준 결과는 코드 설명을 사람이 검토할 수 있는 형태로 바꾸는 방법에 가깝다. 에이전트가 저장소를 읽고, 자신이 파악한 구성요소와 관계를 HTML로 그리며, 사람은 구현이 시작되기 전에 그 이해가 맞는지 확인한다.
공개된 것은 앤트로픽의 공식 플러그인이 아니라 짧은 사내 사용 패턴과 시연이다. 그럼에도 코드 이해, 설계 검토, 장애 분석처럼 먼저 전체 구조를 맞춰야 하는 작업에는 바로 적용할 수 있다. 모델이 더 많은 구현을 맡을수록 사람이 모든 코드를 처음부터 읽기는 어려워진다. 이때 줄여야 할 것은 검토 자체가 아니라, 검토에 들어가기까지 필요한 해석 작업이다.
HTML 설명 자료는 코드를 대신하지 않는다. 코드를 어디부터 어떤 관점으로 읽을지 정해준다. ELI5가 추가하는 단계는 그림을 만드는 시간이 아니라, 잘못 이해한 채 구현을 시작하는 일을 줄이기 위한 확인 시간이다.
참고: Thariq Shihipar의 ELI5 게시물과 첨부 영상(2026-08-21), Using Claude Code: The unreasonable effectiveness of HTML, HTML effectiveness 예시 갤러리, anthropics/html-effectiveness, Claude Code Skills 문서를 2026-08-23 확인했다. ELI5의 사내 사용 범위는 Thariq의 공개 설명에 근거하며, 독립적인 사용 통계나 앤트로픽이 배포한 공식 ELI5 스킬 패키지는 확인되지 않았다.