정의
Code Explainer Docs as Understanding Harness는 AI agent가 작성한 diff를 raw patch가 아니라 인간이 이해 가능한 산문형 문서, quiz, micro-world로 변환해 코드 이해를 보조하는 방법론이다. Geoffrey Litt는 이를 literate diff에 가깝게 설명하며, 배경 지식과 직관을 먼저 제공한 뒤 코드 스니펫을 논리적 순서로 배치하는 방식을 제안한다.
핵심 속성
- 배경 지식 우선: 독자가 diff를 이해하기 전에 알아야 할 개념, 기존 구조, 설계 맥락을 먼저 가르친다.
- 직관 우선, 세부 코드 나중: 세부 구현을 바로 던지지 않고 변화의 의도와 작동 직관을 먼저 만든다.
- Literate diff: raw diff 순서가 아니라 설명하기 좋은 순서로 산문과 코드 스니펫을 배치한다.
- Quiz 포함: explainer 끝에 질문을 넣어 실제 이해 여부를 확인한다. “통과하지 못하면 공유하지 않는다”는 규칙은 인간 이해 속도를 보호한다.
- Micro-world 생성: agent에게 작은 디버거, 시뮬레이션, command center 같은 이해용 도구를 만들게 하여 사람이 코드를 직접 조작하며 배운다.
- 공유 공간 축적: Notion/HTML/Markdown 같은 공간에 explainer와 토론을 남겨 팀 전체가 같은 mental model을 갖게 한다.
관계
- 20260704-understand-to-participate-in-agentic-coding — 구현: 이해를 통한 참여를 가능하게 하는 구체적 도구 묶음.
- 20260612-ai-agent-work-harness — 확장: 테스트·감사 중심 하네스에 설명·학습 하네스를 추가한다.
인용
그냥 diff가 아니라 산문 형태로 논리적 순서에 따라 설명 + 코드 스니펫.
에이전트가 코드를 짜는 것뿐만 아니라, 인간이 그 코드를 이해할 수 있게 돕는 도구까지 만들 수 있다.
출처
클리핑 · x.com · Geoffrey Litt