유행하는 Issue 기반 개발(Issue-driven development) 이해하기

여러분, 엔지니어링을 즐기고 계신가요?

최근 'Issue 기반 개발(Issue駆動開発)'이라는 단어를 자주 접하게 되었습니다.

AI 에이전트에게 Issue를 전달하여 PR까지 생성하도록 사용하는 방식이 늘어났기 때문이라고 생각합니다.

저는 실무에서 Issue를 많이 사용해 본 경험이 없습니다. AI에 맡긴다고 하더라도, 어떤 Issue를 작성해야 할지, 그리고 나온 PR의 어느 부분을 봐야 하는지 모르면 활용하기 어렵습니다. 그래서 AI에게 의존하기 전에 Issue 기반 개발의 흐름을 이해하고 싶었습니다.

이 글은 제가 개인적으로 진행하는 프로젝트(Go로 만든 재고 관리 API)에서 Issue 기반 개발을 시작하면서 조사한 내용과 정립한 규칙들을 정리한 학습 메모입니다.

흐름은 Enchan1207님의 gist 'Issue 기반 개발이란'을 참고했습니다.

Issue 기반 개발은 기능 추가나 버그 수정 등을 먼저 Issue로 등록하고 시작하는 진행 방식입니다. 과제 기반 개발(課題駆動開発)이나 티켓 기반 개발(チケット駆動開発)이라고도 불립니다.

Issue는 GitHub 리포지토리별로 만들 수 있는 티켓과 같은 것입니다. 백로그(Backlog)나 Jira의 티켓을 리포지토리 내에서 관리하는 이미지를 생각하시면 됩니다.

제목과 본문이 있으며, 생성하면 #12와 같은 번호가 부여됩니다.

흐름은 간단합니다. 하나의 Issue에 대해 하나의 브랜치를 분기하고, 작업 완료 후 PR을 올려 병합(merge)합니다. 커밋이나 PR에 Issue 번호를 기재해 두면 나중에 '이 코드를 무엇을 위해 작성했는지'를 Issue까지 추적할 수 있습니다.

역할 분배 측면에서는 Issue에는 '무엇을, 왜 할 것인지'를 쓰고, PR에는 '어떻게 했는지'를 씁니다. AI 에이전트에게 Issue를 전달하는 방식에서는 Issue 자체가 곧 'AI에 대한 지시서'가 됩니다.

GitHub 공식 블로그에서도 Issue에는 문제 설명이나 재현 절차, 시도한 내용을 작성하도록 권장하고 있으며, 'Issue가 명확할수록 PR의 품질도 높아진다'고 언급되어 있습니다. 즉, AI에게 맡길수록 인간의 업무는 'Issue를 작성하는 것'과 '나온 PR을 읽는 것'에 집중됩니다.

여기서부터는 절차입니다.

예시로, 재고 관리 API에서 '동시에 주문이 들어올 경우 재고가 마이너스가 되는 버그(재고 수량 1개가 -1개)'를 수정하는 상황을 가정해 보겠습니다. gh와 git 명령어를 사용합니다.

gh issue create --title 

코드를 읽으면 '무엇을 했는지'는 알 수 있지만, '왜 이렇게 작성했는지'는 남지 않습니다.

6개월 후의 나 자신이나 포트폴리오를 봐줄 사람에게 판단의 이유를 남기고 싶습니다.

gh pr merge --rebase --delete-branch
git switch main
git pull

`--rebase`는 브랜치의 커밋을 `main`의 맨 앞에 하나씩 쌓아 다시 병합(merge)합니다.

병합 커밋이 생성되지 않기 때문에, `main`의 이력이 일직선으로 남게 됩니다.

`--delete-branch`를 붙이면, 병합한 후에 로컬과 GitHub 양쪽의 브랜치를 모두 삭제해 줍니다.

병합되면, `Closes #12`에 의해 Issue도 닫히면서 하나의 작업이 완료됩니다.

개인 개발을 진행하면서 규칙은 다음 5가지로 정했습니다.

- 하나의 Issue당 브랜치와 PR을 각각 하나씩 사용한다.
- main에는 직접 push하지 않는다.
- 병합은 rebase로 진행한다.
- PR 본문에 왜 그렇게 구현했는지 작성한다.

혼자 개발하고 있어서, PR을 내도 리뷰해 줄 사람이 없습니다.

그럼에도 불구하고 PR을 통과시키는 것은 변경의 이유를 남길 장소가 필요하다고 생각했기 때문입니다.

반대로, 라벨(label), GitHub Projects, 브랜치 보호 설정(branch protection setting), Issue 템플릿은 지금은 넣지 않았습니다.

조사해 보면 여러 가지가 나오지만, 혼자 Issue를 몇 개 돌리는 정도라면 없어도 곤란하지 않아서, 이것저것 익숙해지면 추가할 생각입니다.

Issue 기반 개발(Issue-driven development)은 Issue를 생성하고 브랜치를 분기한 다음, PR로 Issue를 닫는 과정 자체는 간단했습니다. 

중요한 것은 Issue에 '무엇을 왜 할 것인지'를, PR에 '왜 그렇게 했는지'를 작성하는 것이라고 생각합니다.

이것은 AI에게 Issue를 전달할 때도 그대로 필요한 부분입니다.

앞으로 개인 개발로 실제로 진행해 보고, 알게 된 점이 있다면 다시 글로 올리겠습니다.