GitHub 이슈에 계획서가 붙어요: 댓글 사이에서 사라지던 맥락을 남기는 법
버그를 고치는 코드는 PR에 있는데, 왜 그렇게 고쳤는지는 채팅방 한참 위에 남아 있는 일이 있어요. 에이전트가 조사한 원인과 사람이 수정한 계획서까지 서로 다른 곳에 있으면, 다음 사람이 일을 이어받을 때 같은 조사를 반복하기 쉽죠. GitHub가 10월 28일 공개 미리보기로 발표한 Issue artifacts는 이런 자료를 이슈 자체에 붙여 두는 기능이에요.
댓글은 대화, 아티팩트는 계속 다듬는 자료예요
이슈에는 Markdown 문서, 외부 링크, HTML 문서를 아티팩트로 연결할 수 있어요. 구현 계획이나 원인 분석을 문서로 남기고, Slack·Teams의 논의나 프로토타입 주소를 함께 모으는 식이에요. github.com에서는 자료를 만들고 수정하며 이전 버전의 이력도 유지할 수 있어요. 여기서 말하는 아티팩트는 CI 실행에서 내려받는 GitHub Actions 빌드 산출물과는 별개예요.
가령 결제가 두 번 처리되는 가상의 버그를 생각해 볼게요. 댓글에는 “재현했어요” 같은 새 관찰을 남기고, 계획서에는 재시도 때 같은 키를 쓰는지와 아직 확인하지 못한 경우를 정리할 수 있어요. 아래 문서는 이 설명을 위해 직접 만든 예시예요. 관찰한 사실, 추정한 원인, 확인할 실험을 나누면 에이전트가 추정을 확정된 요구사항으로 받아들이는 일을 줄이는 데 도움이 돼요.
파일 한 장을 올리고, 같은 자료를 고쳐 나가요
공식 CLI 문서의 gh issue artifact create는 이슈 번호나 URL 뒤에 파일 또는 링크를 받는 구조예요. 예를 들어 gh issue artifact create 42 retry-plan.md -R OWNER/REPO는 지정한 저장소의 42번 이슈에 파일을 붙이는 명령이에요. OWNER/REPO와 번호는 예시 값이며, 실제 실행하면 해당 이슈에 자료를 만드는 쓰기 작업이 돼요. 이 글에서는 실행하지 않았어요.
파일 이름을 자료 이름으로 쓸 수도 있고 --name으로 지정할 수도 있어요. --body-file은 파일 본문으로 문서 하나를 만들 때 쓰며, --attach로 이미지나 동영상을 연결하는 방식도 제공돼요. 수정할 때는 gh issue artifact edit 42 1 --body-file retry-plan.md -R OWNER/REPO처럼 이슈와 아티팩트 번호를 함께 지정해요. 아래 두 번째 자료는 생성·수정 명령의 문법 예시이며 성공 로그가 아니에요.
최신 문서와 바뀐 이유를 함께 남길 수 있어요
CLI의 edit는 이름을 바꾸거나 본문을 교체할 수 있지만 자료의 유형은 바꾸지 않아요. 이전 버전을 되살리는 --restore-version은 그때의 이름과 본문을 새로운 버전으로 저장하고, view에서 수정 이력을 볼 수 있어요. “옛 결정을 지우고 최신안만 남길까” 대신 최신안과 변경 과정을 함께 남기는 방식으로 활용할 수 있죠.
앞의 결제 예시에서 처음에는 네트워크 타임아웃을 의심했다가 로그를 보고 중복 키 처리로 원인을 좁혔다면, 현재 계획서에는 새 판단을 반영하고 댓글에는 판단이 바뀐 이유를 연결하는 편이 읽기 쉬워요. 이는 기능의 자동 동작을 보장하는 설명이 아니라 자료를 구성하는 한 가지 제안이에요. 첨부 문서가 생겼다고 실제 코드나 재현 결과까지 맞아지는 것은 아니니, 근거 링크를 문장 가까이에 두는 것이 좋아요.
HTML이 보이는 곳과 아직 기다려야 하는 곳이 달라요
발표에 따르면 HTML 문서는 렌더된 미리보기와 소스를 전환해 볼 수 있어요. 다만 GitHub App의 HTML 아티팩트 생성·보기 지원은 발표 당시 앞으로 제공될 기능으로 안내됐어요. GitHub App 세션에서 만든 아티팩트가 이슈에 자동 첨부되는 흐름과, 모든 종류의 HTML 작업이 앱에서 가능하다는 주장은 구분해야 해요. CLI 기능 역시 미리보기라 문법과 동작이 바뀔 수 있어요.
이 변화에서 흥미로운 부분은 문서의 양보다 자료가 붙는 위치예요. 조사 결과가 이슈와 연결되면 사람과 에이전트가 다음 단계로 넘어갈 때 출발점을 찾기 쉬워져요. 처음에는 이미 가지고 있는 계획서 한 장을 연결하고, 다음 수정에서 같은 자료의 이력을 이어 가는 방식으로 효과를 살펴볼 수 있어요. 지원 범위와 명령은 아래 공식 발표와 현재 CLI 문서를 함께 확인해 보세요.