AI에게 「적당히 고쳐줘」라고 부탁하는 것을 그만두고, GitHub Issue를 작업의 정본(正本)으로 삼았다

이 기사는 개인 개발 과정에서 깨달은 점들을 AI에게 정리하게 하며 작성하고 있습니다. 이 기사에서는 실체험, 가설, 미검증 구성안을 나누어 남깁니다. 실체험으로서의 내용은 「AI에게 구현을 맡길 때, 대충 부탁하는 것보다 Issue를 작성하는 것이 더 효과적이었다」는 부분입니다.

• Codex / Claude Code / GitHub Copilot coding agent 등에 구현을 맡기고 있는 사람

• AI에게 「적당히 고쳐줘」라고 부탁했다가, 차분(diff)이 너무 커져 버린 적이 있는 사람

• GitHub Issue를 AI 개발의 작업 단위로 사용하고 싶은 사람

• 리뷰하기 쉬운 AI PR을 만들고 싶은 사람

• 검증 명령어와 완료 조건을 Issue에 어떻게 적어야 할지 고민 중인 사람

• AI에게 전달하기 쉬운 GitHub Issue의 최소 포맷

• 설계 메모와 GitHub Issue의 차이

• Goal / Scope / Done / Out of scope 사용법

• 검증 명령어를 Issue에 고정하는 이유

• AI가 너무 많이 건드리는 것을 줄이기 위한 작성법

• 자신의 개인 개발 repo에서 최근 20개의 PR을 보았을 때의 운영 규모

AI에게 구현을 맡길 때, 프롬프트(Prompt)를 열심히 노력하기보다 먼저 GitHub Issue를 작업의 정본(正本)으로 만드는 것이 더 효과적인 상황이 있다는 것을 깨달았다.

처음에는 설계 메모를 작성한 뒤 AI에게 자세히 설명하면 잘 작동할 것이라고 생각했다.

하지만 실제로는 설계 메모만으로는 작업 상태가 흘러가 버리기 쉬웠다. 배경, 목적, 건드려도 되는 범위, 건드려서는 안 되는 범위, 완료 조건, 검증 명령어가 GitHub Issue에 남아 있지 않으면, AI도 인간도 「이 PR은 무엇을 종결하는 것인가」를 나중에 추적하기 어렵다.

또 하나 컸던 점은 GitHub Issue가 개발 플로우(Flow)에 편입시키기 더 쉬웠다는 것이다.

ChatGPT로 상담하여 나온 구현안을 그대로 Issue 후보로 정형화하여 GitHub Issue로 생성할 수 있다. 거기서부터 Codex나 다른 AI 에이전트(Agent)에게 전달하여 PR, CI, 리뷰로 연결할 수 있다.

즉, 나에게 있어 GitHub Issue는 단순한 태스크 관리(Task Management)가 아니라, ChatGPT로 생각한 것을 개발 플로우로 흘려보내는 입구가 되었다.

대략적인 체감으로는, ChatGPT로 상담한 내용에서 Issue화하는 것은 하루에 5~10건 정도 있다.

물론 모든 것이 그대로 구현되는 것은 아니다. 조사에서 멈추는 것, 보류하는 것, 나중에 정리하는 것도 있다.

그럼에도 ChatGPT 상에서 흘러가는 상담을 Issue 후보로 변환할 수 있게 되자, 아이디어가 개발 플로우에 올라탈 확률이 상당히 높아졌다.

나에게 있어 컸던 점은, 이전에는 상담이나 설계까지는 진행되어도 마지막까지 도달하지 못하는 경우가 많았다는 점이다.

대화 중에는 「이것은 괜찮아 보이네」라고 생각한다. 설계 메모도 쓸 수 있다. 하지만 다음에 무엇을 구현할지, 어떤 PR로 종결할지, 어떤 검증으로 완료할지가 모호한 상태라면 도중에 다른 화제로 흘러가 버린다.

GitHub Issue로 만들면 적어도 「이 작업은 아직 open 상태인가」, 「어떤 PR로 종결하는가」, 「Done은 무엇인가」가 남는다.

그로 인해 상담으로 끝났던 것을 완료까지 운반하기 쉬워졌다.

현재 나의 개인 개발에서는 Issue에 다음 4가지를 적으면 다루기 쉽다.

Goal
Scope
Done
...

이 기사는 「Issue 주도 개발(Issue-Driven Development)은 이래야 한다」는 이야기가 아니다. AI에게 작업을 맡길 때 왜 설계 메모뿐만 아니라 GitHub Issue로 옮기는지, Issue를 어떻게 작성하면 PR 리뷰를 하기 쉬워지는지를 정리한 메모이다.

이 기사를 쓰는 시점에서 나의 개인 개발 repo의 최근 20건의 PR과 Issue를 살펴보았다.

이것은 엄밀한 효과 측정은 아니다. Issue 템플릿을 넣기 전후를 비교한 것도 아니고, Scope 외 변경을 하나씩 분류한 것도 아니다.

다만 AI에게 작업을 맡길 때 어느 정도 양의 Issue/PR이 흐르고 있는지를 보여주는 자료는 된다.

2026-05-19 시점에서 GitHub 상의 최근 20건을 보면 다음과 같은 상태였다.

대상	확인한 건수	결과
PR	20건	19건 merged, 1건 closed
...

이 숫자에서 말할 수 있는 것은 「Issue를 쓰면 반드시 잘 된다」는 것이 아니다.

오히려 나의 개인 개발에서는 짧은 기간에 작은 규모의 PR이 여러 개 흐르는 상태가 되어 있었다. 이렇게 되면 채팅 안에서만 의뢰를 관리하는 것은 힘들다.

PR이 늘어날수록 다음 내용을 나중에 추적할 수 있는 것이 중요해진다.

• 무엇을 수정하는 Issue였는지
• 어떤 PR에서 닫았는지
• 어떤 검증 명령어 (verification command)를 통과했는지
• 무엇을 Scope 외로 설정했는지
• 도중에 close한 PR은 왜 닫았는지

그래서 나에게 GitHub Issue는 「AI에게 전달할 프롬프트 (prompt)」가 아니라, 작업 상태를 남기기 위한 정본 (source of truth)에 가까워졌다.

참고로, 이번 수치는 다음과 같은 관점에서 확인했다.

gh pr list --state all --limit 20
gh issue list --state all --limit 20

다음에 제대로 측정하려면, PR마다 「Scope 외 변경이 있었는가」, 「Done의 검증 명령어가 PR 본문이나 코멘트에 남아 있는가」를 세고 싶다.

A: AI에게 부탁할 거라면, 채팅으로 자세히 설명하면 되지 않나요?

B: 처음에는 그렇게 생각했다. 하지만 채팅만으로는 작업 단위가 흘러가 버리기 쉽다.

A: Issue를 쓰는 건 번거롭지 않나요?

B: 번거롭다. 하지만 나중에 PR을 읽을 때, Issue가 있는 편이 「무엇을 고치려 했었는지」 확인하기 쉽다.

A: AI라면 넓게 읽고, ついで (덤으로) 고쳐주는 편이 더 좋지 않나요?

B: 작은 수정이라면 오히려 곤란할 때가 있다. 덤으로 하는 수정이 늘어나면, 리뷰 (review)가 무거워진다.

AI 코딩을 사용하면 구현 그 자체는 빨라진다.

다만, 내가 겪은 문제는 AI가 너무 빨라서가 아니라, 작업의 경계가 모호해지는 것이었다.

예를 들어, 다음과 같은 의뢰를 하면 위험하다.

이 주변을 적당히 잘 고쳐주세요.

사람 사이라면 암묵적인 문맥으로 전달되는 경우가 있다.

하지만 AI에게 전달하면, 어디까지 읽어도 되는지, 어디까지 고쳐도 되는지, 어떤 검증을 통과해야 완료인지가 모호해진다.

그 결과, 다음과 같은 일이 일어나기 쉽다.

• 변경 범위가 넓어진다
• 관련 없는 리팩토링 (refactoring)이 섞인다
• 테스트 (test)나 workflow까지 건드린다
• 완료 조건(Definition of Done)을 알 수 없다
• 리뷰 시에 「이것이 필요했던 것인가」를 판단하기 어렵다

나도 처음에는 「덤으로 고쳐준다면 도움이 된다」고 생각했다.

하지만 작은 수정일 생각이었는데, 주변 정리나 다른 검증까지 들어가기 시작하면 PR을 보는 쪽의 부하가 올라간다. AI가 나쁘다기보다, 전달 방식이 모호했던 것이다.

여기서 Issue를 단순한 태스크 메모가 아니라, AI에게 전달하는 작업 계약 (work contract)으로서 작성하는 것이 좋겠다고 느꼈다.

A: 그렇다면 설계 메모를 미리 작성하면 충분하지 않나요?

B: 설계 메모도 필요하다고 생각한다. 다만, AI에게 구현을 맡기는 작업 단위로서는 GitHub Issue가 다루기 쉬웠다.

설계한 뒤에 구현하는 것 자체는 중요하다.

다만, 내가 Issue에 집중하고 싶다고 생각한 이유는 설계 내용 그 자체가 아니라, 작업 상태가 GitHub 상에 남는다는 점이었다.

설계 메모와 GitHub Issue는 역할이 조금 다르다.

관점	설계 메모	GitHub Issue
목적	생각을 심화함	작업 단위를 고정함
연결		Closes #123으로 연결됨
코멘트	문서에 추가되는 경향이 있음	작업 로그, 질문, 판단이 시계열로 남음
CI와의 관계	직접적으로 연결되지 않음	PR, checks, review와 함께 추적 가능
검색성	Vault나 로컬 검색에 의존함	GitHub 상에서 Issue/PR 횡단 검색 가능

내 안에서 설계 메모는 「생각하는 장소」, GitHub Issue는 「작업을 발행하는 장소」에 가깝다.

AI에게 맡길 때 원하는 것은 깔끔한 설계 문서만이 아니었다.

원했던 것은 다음 내용이 한 곳에 모여 있는 것이었다.

• 이 작업은 무엇을 닫는가 (closes)
• 누가, 언제, 무엇을 판단했는가
• 어떤 PR로 이어졌는가
• 어떤 CI가 통과했는가
• 리뷰에서 무엇을 지적받았는가
• 마지막에 close 되었는가

이것은 설계 메모만으로는 부족하다.

GitHub Issue로 해두면 PR 본문에 Closes #123을 쓸 수 있다. 코멘트로 질문도 남길 수 있다. 라벨 (label)로 bug, enhancement, codex-ready와 같이 상태도 나눌 수 있다. 나중에 같은 실수를 찾을 때도 Issue와 PR을 묶어서 추적하기 쉽다.

나아가, ChatGPT와 상담한 내용을 Issue화할 수 있는 것도 크다.

예를 들어, ChatGPT와의 대화에서 다음과 같은 내용이 나온다.

• 배경
• 문제
• 구현 방침
• 반대 의견
• 검증 명령어
• 하지 않을 것

이것을 그대로 기사나 설계 메모로 끝내버리면, 나중에 개발로 돌아왔을 때 다시 한번 정리가 필요하게 된다.

하지만, Goal / Scope / Done / Out of scope로 압축하여 GitHub Issue에 작성하면, 이를 그대로 AI 구현 플로우 (AI implementation flow)로 넘길 수 있다.

따라서 나에게 있어 Issue 주도 (Issue-driven) 방식이란, "설계한 뒤에 한다"의 다른 말이 아니라, 설계한 작업을 GitHub 상의 추적 가능한 단위로 변환하는 것이었다.

조금 더 정확히 말하자면, ChatGPT로 생각한 내용을 GitHub Issue라는 실행 가능한 작업 단위로 변환하는 것이었다.

이 형식을 갖춘 이후로, Scope 외 변경은 확실히 줄어들었다고 느끼고 있다.

다만, 이는 아직 체감일 뿐이다. 도입 전후의 PR 차분(diff) 행수나 Scope 외 변경 건수를 집계한 것은 아니므로, 이 글에서는 "줄었다"라고 너무 단정 짓지 않고, 다음에 측정할 대상으로 남겨두겠다.

A: 구체적으로 무엇이 다른 거야?

B: AI에게 부탁하는 것이 아니라, GitHub 상에서 추적할 수 있는 작업 단위로 만든다는 점이 달라.

대충 던지는 의뢰:

이 에러를 고쳐주세요.

Issue 주도의 의뢰:

## Goal
`npm run typecheck`의 실패를 고친다.
## Scope
...

이 차이는 크다.

Issue 주도로 하면, AI에게도 인간에게도 다음 사항이 명확해진다.

• 무엇을 달성할 것인가
• 어디를 건드려도 되는가
• 어디를 건드리면 안 되는가
• 무엇이 통과되면 완료인가
• 이번에 하지 않을 일은 무엇인가

현재로서는 이 정도가 최소한으로 적당하다고 느끼고 있다.

## Goal
무엇을 달성할지를 한 문장으로 작성한다.
## Background
...

매번 모든 항목을 채울 필요는 없다.

다만, Goal, Scope, Done, Out of scope는 가급적 포함하고 싶다.

A: Scope를 작성하면 AI의 장점을 제한하게 되지 않을까?

B: 규모가 큰 조사에서는 너무 제한하지 않는 것이 좋다. 하지만 작은 수정에서는 Scope가 없는 편이 더 위험해.

AI에게 맡길 때, 자유도가 높을수록 좋은 것은 아니다.

특히 작은 PR에서는 변경 범위를 좁게 유지하는 것이 리뷰하기 쉽다.

예를 들어, TypeScript의 타입 에러 (type error)를 고치고 싶을 뿐인데, workflow나 package manager까지 바뀌면 곤란하다.

Issue에 이렇게 적어두는 것만으로도, AI와 인간 모두에게 경계가 보인다.

## Scope
- 변경해도 좋은 곳: `src/**/*.ts`
- 변경하지 않는 곳: `.github/workflows/**`, `package.json`, `pnpm-lock.yaml`

물론, AI가 작업 중에 "Scope 외를 건드리지 않으면 고쳐지지 않는다"라고 판단할 수도 있다.

그럴 경우에는 멋대로 범위를 넓히는 것이 아니라, 코멘트나 메모를 남기고 멈추는 편이 다루기 쉽다.

Issue 주도 방식에서 가장 효과가 좋았던 것은, Done에 검증 명령어 (verification command)를 적는 것이었다.

## Done
- `./scripts/verify.sh fast`가 통과한다

이것만으로도 AI에게 전달하는 지시 사항이 상당히 달라진다.

대충 던지는 지시:

고쳐주세요.

검증 조건이 포함된 지시:

이 Issue에서는 `./scripts/verify.sh fast`가 통과할 때까지 고쳐주세요.

AI는 "무엇을 기준으로 완료인가"를 알 수 있게 된다.

인간도 PR을 확인할 때 동일한 명령어로 확인할 수 있다.

A: 하지 않을 일까지 적을 필요가 있어?

B: AI에게 맡길 때일수록, 하지 않을 일을 적는 것이 좋았어.

AI는 친절해 보이는 수정을 덧붙이는 경향이 있다.

물론 그것이 도움이 되는 상황도 있다.

다만, Issue 단위로 작게 진행하고 싶을 때는, 친절한 추가 수정이 리뷰 부하 (review load)가 된다.

예를 들어, 이번 Issue에서는 E2E까지 보지 않는다면 처음부터 적어둔다.

## Out of scope
- E2E 수정
- package build 개선
...

이것은 AI를 구속한다기보다, 이번 PR을 작게 유지하기 위한 경계선이다.

나라면 AI에게 넘기기 전에 이것을 확인한다.

[ ] Goal이 한 문장으로 작성되었는가
[ ] 변경해도 좋은 파일이 작성되었는가
[ ] 변경하지 않는 파일이 작성되었는가
...

CI가 실패하고 있는 Issue라면, 실패의 종류도 구분한다.

분류	예시	AI에게 맡길 것인가
code failure	test, typecheck, lint	맡기기 쉬움
...

이 분류를 하지 않으면, AI에게 코드를 고치게 해도 해결되지 않는 실패를 계속 코드 측면에서 추적하게 된다.

처음부터 Issue 운영을 완벽하게 할 필요는 없다.

우선은 다음 순서로 진행하면 좋다고 생각한다.

• 최근에 AI에게 맡기고 싶은 작은 수정 사항을 하나 고른다.
• 그 수정을 Goal / Scope / Done / Out of scope로 나눈다.
• Done에 검증 명령어를 하나 작성한다.
• GitHub Issue로 만든다.
• AI에게 Issue URL 또는 Issue 번호를 전달한다.
• PR 본문에 Closes #issue_number를 넣는다.
• PR 차분(diff)이 Scope 내에 들어와 있는지 확인한다.
• 검증 명령어가 통과했는지 확인한다.
• Scope 외의 변경 사항이 나오면, Issue 템플릿을 수정한다.

첫 번째 목적은 자동화가 아니라, 리뷰하기 쉬운 작업 단위를 만드는 것이다.

GitHub Issue로 만드는 의미는 여기서 나온다.

채팅이나 설계 메모만 있으면, 작업이 끝난 뒤에 "어떤 요청으로부터 시작된 PR인가"를 추적하기 어렵다. Issue로 만들어 두면 Issue, PR, CI, 리뷰, close가 연결된다.

마지막으로, 실제로 사용한다면 이 정도의 짧은 길이로도 충분하다고 생각한다.

## Goal
<!-- 무엇을 달성할 것인지 한 문장으로 작성 -->
## Scope
...

AI에게 전달할 때는 이 Issue 본문을 정본(正本)으로 삼고, 채팅 측에서는 보충 정보만 전달한다.

작업하면서 위험하다고 느꼈던 Issue는 다음과 같은 것들이었다.

• Goal이 여러 개 있다
• Scope가 없다
• Done이 "적당히 되어 있음"으로 되어 있다
• Out of scope가 없다
• 조사, 설계, 구현, 검증이 하나의 Issue에 섞여 있다
• 실패 로그가 없어 AI가 재현할 수 없다
• 1개의 PR로 끝나지 않는다

다만, 나의 경우에는 "AI가 이상한 코드를 작성한다"는 단계 이전에서 멈추는 경우가 많았다.

즉, 상담, 설계, 조사까지는 진행되지만, 구현, PR, 검증, close까지 도달하지 못한다.

이는 Issue의 내용이 나쁘다기보다, 작업 단위가 GitHub 상에 발행되지 않았던 점이 컸다. Issue가 없으면 ChatGPT로 생각한 내용이 대화 로그나 메모 속에 남을 뿐, 개발 흐름(flow)에 올라타지 못한다.

GitHub Issue로 바꾼 이후에는 적어도 다음 상태들을 추적할 수 있게 되었다.

• open 상태로 남아 있음
• PR에 연결됨
• CI에서 실패함
• 리뷰 대기 중임
• close됨

"끝까지 도달하지 못하는 경우"를 줄이려면, Issue 본문을 깔끔하게 만드는 것뿐만 아니라, Issue로서 발행하여 상태를 갖게 하는 것이 효과적이었다.

특히, 조사도 하고, 설계도 하고, 구현도 하고, 필요하면 테스트도 수정해줘와 같은 Issue는 비대해지기 쉽다.

AI에게 맡길 때는 다음과 같이 나누는 것이 다루기 쉽다.

Issue 1: 원인을 조사한다
Issue 2: 수정 방침을 결정한다
Issue 3: 최소한의 수정을 적용한다
...

AI에게 구현을 맡길 때, 프롬프트(Prompt)를 잘 쓰는 것도 중요하다고 생각한다.

하지만 나의 개인 개발에서는 그 이상으로 GitHub Issue를 작업의 정본으로 삼는 것이 효과적이었다.

설계 메모는 생각하는 장소로서 필요하다.

반면, AI에게 맡기는 작업은 GitHub Issue로 만드는 편이 추적하기 쉽다.

이유는 Issue가 PR, CI, 리뷰, 코멘트, close 상태와 연결되기 때문이다.

현재로서는 Issue에 다음 내용을 적는 것이 다루기 편하다.

• Goal
• Scope
• Done
• Out of scope
• 필요하다면 Background와 Notes

AI에게 "적당히 고쳐줘"라고 부탁하기보다, Issue에 작업 경계와 검증 조건을 작성한다.

그것만으로도 PR이 작아지고, 리뷰하기 쉬워지며, 실패했을 때 되돌리기도 쉬워진다.

AI가 코드를 작성하는 시대에는, 인간의 업무가 프롬프트를 쓰는 것뿐만 아니라, AI가 헤매지 않고 인간이 나중에 추적할 수 있는 GitHub Issue를 작성하는 쪽으로도 나아갈지도 모르겠다.