엉성한 PR 설명은 <details><summary> 뒤에 숨기세요

문제는 설명을 너무 잘 쓴다는 점입니다

문제는 에이전트가 너무 잘 쓴다는 것입니다. 에이전트가 쓴 PR 설명은 정확하고 빠짐이 없습니다. 문제 상황, 해결 방법의 세부 내용, 검증 과정까지 모두 담겨 있죠. 그만큼 소화해야 할 정보가 많습니다.

꼭 엉성한 글은 아니지만, 엉성한 글처럼 읽힙니다.

AI가 쓴 PR은 한눈에 알아볼 수 있습니다. 다른 AI 글을 볼 때와 마찬가지로, 제 반응은 한마디로 "이걸 다 읽고 싶지는 않다"입니다. 정보가 아무리 정확하고 유용해도 상관없습니다. 읽는 데 드는 시간이 글을 쓴 쪽, 즉 AI에게 지시를 내린 사람이 쓴 시간보다 길 것 같다고 생각하면 바로 거부감이 듭니다. 그 사람이 저 자신이어도 마찬가지입니다!

저는 사람의 편집 판단을 원합니다. 누군가 PR을 두고 딱 필요한 만큼만 고민해서, 이 PR이 무엇을 위한 것인지, 더 들여다볼 가치가 있는지를 큰 틀에서 파악하게 해 주는 사람 손을 거친 소개글이 있었으면 합니다.

품이 적게 들면서도 괜찮다 싶은 방법을 찾았습니다.

대부분을 details/summary 안에 숨기세요

HTML <details><summary> 요소는 접힌 제목(summary)으로 표시되며, 클릭하면 펼쳐서 긴 본문을 볼 수 있습니다. 코드는 다음과 같습니다.

<details>
  <summary>Claude Opus 5.5</summary>
  <h2>The hook</h2>
  Plugins implement <code>register_agent_reference_types(datasette)</code>...
</details>

렌더링하면 이렇게 보입니다.

중요한 점은 <details><summary>이 GitHub Markdown에서 지원된다는 것입니다. 이슈 댓글이나 PR 설명에 이 태그를 그대로 넣으면 GitHub이 세부 내용을 숨기고, summary와 펼침 화살표만 보여 줍니다.

저는 AI가 만든 풀 리퀘스트에 이 방식을 쓰기 시작했습니다.

PR의 첫 문단은 상황을 큰 틀에서 설명하도록 신중하게 골라 둡니다. 사람이 읽고 빠르게 맥락을 파악할 수 있는 가장 짧은 글을 목표로 합니다.

새 기능을 빠르게 보여 주는 데는 이미지가 가장 좋을 때가 많아서, 스크린샷을 함께 넣기도 합니다.

에이전트가 쓴 전체 글은 그 아래 <details><summary> 안에 넣습니다. summary에는 모델명과 (대개) 노력 수준을 적어서 무엇인지 분명히 드러냅니다. 예를 들면 "Claude Opus 5.5 Medium"처럼요.

이제 제 PR은 훨씬 덜 엉성해 보입니다! 정보는 그대로 있지만, 읽는 사람은 에이전트가 쓴 긴 문단들에 눈이 풀리지 않고도 사람이 추려 낸 핵심만 훑어볼 수 있습니다.

소개글을 항상 직접 쓰지는 않습니다. 에이전트가 쓴 방대한 글 속에 필요한 내용이 이미 들어 있을 때도 있거든요. 다만 독자에게 하는 약속은 같습니다. 짧은 첫 문단은 "이것만큼은 시간을 들일 가치가 있다"는 제 판단을 담고 있다는 것입니다.

이 패턴을 쓴 최근 사례를 첫 문단과 함께 소개합니다.

• datasette PR #3052: 행 페이지를 필드의 세로 목록으로 재설계 - "행 페이지는 행 하나를 한 줄짜리 테이블로 보여 주었습니다. 46개 열짜리 GitHub repos 테이블처럼 폭이 넓은 테이블은 화면이 오른쪽으로 한참 넘어가고, 페이지 대부분이 빈 채로 남았습니다." (이어서 스크린샷)
• datasette PR #3043: 현재 페이지에 어떤 행이 있는지 보여 주는 페이지네이션 바 - "두 페이지 이상인 테이블 페이지에서 현재 위치를 바로 알 수 있고, 페이지 아래뿐 아니라 위에서도 이동할 수 있습니다." (스크린샷 포함)
• datasette PR #3042: 작은 로더로 edit-tools.js를 필요할 때 불러오기 - "edit-tools.js(약 220KB)가 편집 권한이 없는 사용자에게까지 모든 테이블, 행, 데이터베이스 페이지에서 로드되었습니다. 이제 편집 권한이 있는 사용자가 편집 기능을 처음 사용할 때(편집 링크에 마우스를 올릴 때 포함)에만 로드합니다."
• datasette-agent PR #51: register_agent_reference_types 플러그인 훅 - "새 register_agent_reference_types(datasette) 플러그인 훅으로, 플러그인이 채팅 입력창의 # 태깅에 자체 항목 유형을 추가할 수 있습니다." - 위 이미지 참고.
• llm PR #1838: llm openai endpoint add/list/remove/path 명령 추가 - "extra-openai-models.yaml의 레코드를 관리하는 명령을 추가했습니다. 이제 OpenAI 호환 엔드포인트를 YAML 파일을 직접 고치지 않고 커맨드 라인에서 저장할 수 있습니다." - 이어서 복사해 온 --help 출력.

외우는 요령

예전에는 태그 순서가 자꾸 헷갈렸습니다. <details><summary>이 먼저인지, <summary><details>이 먼저인지 말이죠.

도움이 된 요령이 두 가지 있습니다.

첫 번째는 가장 직관적인 방법입니다. <summary>는 세부 내용을 요약하는 부분입니다. 클릭해서 펼치는 한 줄 텍스트에 쓰는 태그이니, <details> 요소가 나머지 전체를 감싸야 합니다.

더 좋은 요령은 이 두 태그를 항상 "details-summary"라고 부르는 것입니다.

"details-summary"는 2음절 다음에 3음절이 이어지는 구조입니다. 3음절 다음에 2음절이 오는 "summary-details"보다 입에 더 매끄럽게 붙습니다.

"details-summary"를 소리 내어 몇 번만 말해 보면 태그 순서를 다시는 잊어버리지 않을 겁니다.

(GitHub이 Markdown 에디터에 이 기능용 버튼을 추가해 주면 좋겠습니다. 모바일 키보드로 일일이 입력하는 수고도 덜고, 이런 기능이 있다는 사실을 더 많은 GitHub 사용자에게 알리는 데도 도움이 될 테니까요.)

지금 보시는 것은 제 블로그의 장문 글뿐입니다. 모든 글을 받아 보려면 /atom/everything/을 구독하시거나, 다른 구독 방법을 확인해 보세요.