9th November 2026
요즘 제가 프로젝트에 적용하는 변경 사항 대부분은 Claude Code나 Codex가 열어준 Pull Request(PR) 형태로 들어옵니다. PR이 저의 작업 단위입니다. 저는 이를 사용해 커밋들을 하나로 묶고, 기능이 완성될 때까지 반복적으로 개선하며, 결정된 내용을 문서화한 후 최종 결과를 병합합니다. 오늘날의 코딩 에이전트들은 PR 설명을 작성하는 데 매우 능숙합니다.
너무 잘 설명해서 문제예요
문제는 그들이 너무 잘한다는 것입니다. 에이전트가 작성한 PR 설명은 정확하고 포괄적입니다. 이 설명에는 문제점, 상세 해결책, 그리고 검증을 위해 취해진 단계까지 모두 기술되어 있습니다. 이는 흡수하기에 너무 많은 정보량입니다.
꼭 '장황하다(slop)'고 할 수는 없지만, 읽는 느낌은 장황합니다!
AI가 작성한 PR은 쉽게 눈치챌 수 있으며, 다른 AI 작문물과 마찬가지로 저의 즉각적인 반응은 “이걸 전부 다 읽을 시간이 없어”라는 것으로 요약됩니다. 정보가 아무리 정확하거나 유용하더라도, 제가 직접 쓰기보다 읽는 데 더 오랜 시간이 걸릴 것이라는 생각에 순식간에 흥미를 잃게 됩니다... 심지어 그 작성자가 저 자신일 때조차도 말입니다!
저는 인간의 편집적 판단이 필요합니다. PR을 충분히 고민하여, 이 PR이 무엇을 위한 것인지 그리고 제 주의가 더 필요한 가치가 있는지 높은 수준에서 이해할 수 있도록 도와주는 '인간 승인(human-approved)' 소개글이 필요합니다.
제가 적절하다고 느끼는 저노력(low-effort) 방식이 있다고 생각했습니다.
대부분을 details/summary 안에 숨기기
HTML의 <details><summary> 요소는 접힌 제목(요약, summary) 형태로 렌더링되며, 클릭하면 더 큰 본문 내용을 볼 수 있게 확장됩니다. 코드는 다음과 같습니다:
<details>
<summary>Claude Opus 5.5</summary>
<h2 >The hook</h2>
...
실제 렌더링된 모습은 이렇습니다:
Screenshot of a GitHub PR. The text "Claude Opus 5.5" sits next to a little black arrow. Clicking on that text expands a full description inside the PR body.
결정적으로, <details><summary>는 GitHub Markdown에서 지원됩니다. 해당 태그들을 이슈 댓글이나 PR 설명에 바로 넣으면, GitHub가 세부 내용은 숨기고 요약과 확장 화살표만 표시해 줍니다.
저는 이것을 AI가 생성한 풀 리퀘스트(pull request)에 사용하기 시작했습니다.
제 PR의 도입 단락은 무슨 일이 일어나고 있는지에 대한 높은 수준의 설명을 제공하도록 신중하게 선택됩니다. 이는 사람이 읽을 수 있는 가장 짧은 텍스트로, 독자가 상황을 빠르게 파악하는 데 도움을 줄 것입니다.
이미지가 종종 새로운 기능을 빠르게 설명하는 가장 좋은 방법이기 때문에 때로는 스크린샷도 첨부합니다.
전체 에이전트가 작성한 설명은 그 뒤에 <details><summary> 태그 안에 따릅니다. 저는 무슨 일이 일어나고 있는지 명확하게 하기 위해 모델 이름과 종종 노력 수준(effort level)을 요약으로 사용합니다. 예를 들어, “Claude Opus 5.5 Medium”과 같은 방식입니다.
이제 제 PR은 예전만큼 지저분해 보이지 않습니다! 모든 정보는 여전히 존재하지만, 독자는 에이전트가 작성한 여러 단락의 세부 사항에 눈이 피로해지기 전에 훑어보고 가장 중요한 인간이 선별한 정보를 얻을 수 있습니다.
제가 항상 도입부를 직접 작성하는 것은 아닙니다. 때로는 에이전트가 이미 다른 텍스트의 홍수 속에 숨겨진, 제가 필요로 하는 것을 제공해 주기도 합니다. 독자에게 드리는 제 약속은 이 짧은 시작 부분이 그들의 시간을 들일 가치가 있는 것이 무엇인지에 대한 저의 인간적인 판단을 대표할 것이라는 것입니다.
제가 이 패턴을 사용한 최근 몇 가지 예시를 소개합니다. 여기에는 제가 사용했던 도입부도 포함됩니다:
- datasette PR #3052: 행 페이지를 필드의 수직 목록으로 재설계—"행 페이지는 단일 행을 한 줄짜리 테이블로 표시했습니다. 46개 열과 같은 넓은 테이블의 경우, 그 테이블이 오른쪽으로 너무 멀리 스크롤되어 대부분의 페이지가 비어 있었습니다." (스크린샷 첨부) - datasette PR #3043: 현재 페이지에 어떤 행들이 있는지 보여주는 페이지네이션 바—“여러 페이지에 걸쳐 있는 테이블 페이지는 이제 사용자가 어디에 있는지 명확하게 알려주며, 페이지 상단과 하단 모두에서 탐색 기능을 제공합니다.” (스크린샷 첨부)
- datasette PR #3042: 작은 로더를 통해 edit-tools.js를 온디맨드(on demand)로 로드—"
edit-tools.js
(~220KB)가 편집할 수 없는 사용자에게도 모든 테이블, 행 및 데이터베이스 페이지에 로드되었습니다. 이제는 사용자가 편집 기능과 처음 상호작용할 때(편집 링크 위에 마우스를 올리는 경우 포함)만 해당 사용자에게 로드합니다.
- datasette-agent PR #51: register_agent_reference_types 플러그인 훅—새로운
register_agent_reference_types(datasette) 플러그인 훅을 사용하여 플러그인이 채팅 컴포저의 # 태그에 자체 종류의 항목을 추가할 수 있게 합니다. (위 그림 참조)
- llm PR #1838: llm openai 엔드포인트 add/list/remove/path 명령어 추가—
extra-openai-models.yaml에 있는 레코드를 관리하는 명령어를 추가하여, OpenAI와 호환되는 엔드포인트를 YAML을 수동으로 편집하는 대신 명령줄에서 저장할 수 있게 합니다.—그리고 help 출력을 복사합니다.
암기법 (The mnemonic)
저는 예전에 태그의 순서를 기억하는 데 어려움을 겪었습니다. <details><summary>가 맞는지 아니면 <summary><details>가 맞을까요?
저에게 도움이 되었던 두 가지 요령이 있습니다.
첫째, 그리고 가장 명백한 것은, <summary>는 세부 정보를 요약하는 부분이 분명하다는 것입니다. 즉, 클릭하여 확장할 수 있는 텍스트 줄에 대한 태그이며, <details> 요소가 나머지 모든 것을 감싸야 합니다.
훨씬 더 좋은 요령은 이 두 태그를 항상 “details-summary”라고 부르는 것입니다.
“details-summary”는 두 음절 다음에 세 음절이 이어집니다. 이는 “summary-details”의 세-두 박자보다 입에 훨씬 잘 붙습니다.
“details-summary”를 몇 번 소리 내어 말해보면, 태그 순서를 절대 잊지 않을 것입니다.
(저는 여전히 GitHub가 이 기능을 위한 버튼을 마크다운 편집기에 추가해주기를 바랍니다. 부분적으로는 모바일 키보드로 힘들게 타이핑하는 수고를 덜기 위해서이고, 부분적으로는 이 기능이 존재한다는 것을 더 많은 GitHub 사용자들에게 알리는 데 도움이 되도록 하기 위함입니다.)
최신 기사들
- Qwen 3.8 27B가 내 노트북에서 모델 가중치(model weights)를 해석할 수 있다 - 2026년 11월 3일
- 미국 인구조사국(U.S. Census Bureau)과 '초지능(Super Intelligence)' - 2026년 11월 2일
- 바이브 게임 개발을 위한 10월의 변곡점(inflection point) - 2026년 10월 28일
- 배틀 드론(Battle Drones) - 오디오 기반 멀티플레이가 가능한 바이브 코딩된 실시간 전략 게임(RTS) - 2026년 10월 20일
