팀원이 바로 시작할 수 있는 Issue 만들기

01 · 셋이 맡았는데

일은 나눴습니다. 그런데 두 사람은 기다립니다.

사내 장비 대여 서비스를 만드는 팀입니다. 한 사람은 승인, 다른 사람은 반납, 또 다른 사람은 이력을 맡았습니다.

승인 담당자는 대여 기록을 만드는 중입니다. 반납 담당자가 묻습니다. ‘누가 뭘 빌렸는지 어디서 가져오죠?’ 이력 담당자도 묻습니다. ‘반납 결과가 있어야 이력을 확인할 텐데요.’ 담당자는 셋이지만, 필요한 기록이 없어 실제 흐름을 확인하지 못합니다.

GitHub의 Issue는 할 일과 논의를 남기는 작업 기록입니다. 7주차에는 브랜치라는 별도 작업 공간에서 개발하고, PR이라는 검토 요청으로 변경을 합치는 흐름을 배웠습니다. 이번에는 그 전에 무엇을 나눠 맡길지 정합니다.

강의를 듣지 않았어도 시작할 수 있습니다. 여기서는 장비 목록과 내 신청 목록이 이미 있고 신청에 반납 예정일이 있다고 가정합니다. 코드가 없다면 노트북 1번·모니터 1번의 가상 목록을 종이나 문서에 적고 아래 예시를 따라가세요. 문서로 예상한 결과와 실제 서비스를 실행한 결과는 구분합니다.

02 · 왜 기다릴까요?

반납을 끝내려면 먼저 빌린 기록이 필요합니다.

반납 화면을 미리 그리는 것과 실제로 빌린 장비를 반납하는 것은 다릅니다.

승인 기능이 ‘김민수가 노트북 1번을 빌렸다’는 기록을 만든다고 합시다. 반납 기능은 바로 그 대여를 찾아 끝내야 합니다. 다른 작업의 결과가 있어야 내 일을 진행하거나 끝낼 수 있는 관계를 의존성이라고 부릅니다.

실습 저장소 kch의 #7 반납 Issue는 #6 승인을 먼저 필요한 작업으로 연결합니다. 2026-10-28에 Issue 본문과 실제 Blocked by 관계를 확인했습니다. 이 연결은 이유가 있으므로 단순히 지워서는 해결되지 않습니다. 수업 때는 최신 상태를 다시 확인합니다.

계획을 나눌 때는 ‘누가 무엇을 먼저 끝내야 이 사람이 시작하거나 확인할 수 있을까?’를 묻습니다. 먼저 끝내야 할 일을 선행 작업이라고 합니다. 지금 할 수 있는 준비와 나중에 연결해야 하는 부분을 구분하면, 꼭 필요한 순서를 지키면서도 기다리는 시간을 줄일 여지가 생깁니다.

03 · 각자 만들었더니

코드는 합쳐졌는데 화면의 말이 다릅니다.

반납 화면에는 ‘완료’, 이력 화면에는 ‘관리자 확인 대기’가 표시됩니다.

반납 담당자는 직원이 버튼을 누르면 끝난다고 생각했습니다. 이력 담당자는 관리자가 실물을 확인해야 끝난다고 생각했습니다. 둘 다 자기 화면은 만들었지만 ‘완료’의 기준이 달라 함께 사용할 수 없습니다.

이때 코드가 충돌 없이 합쳐졌다는 것은 같은 줄을 다르게 고친 문제가 없다는 뜻일 수 있습니다. 업무가 맞게 동작한다는 뜻까지 보장하지는 않습니다. 파일이 달라도 같은 장비 상태를 쓰면 서로 영향을 받습니다.

그대로 각자 더 개발하면 잘못된 기준을 따르는 화면과 확인 방법도 늘어날 수 있습니다. 먼저 뜻을 맞추면 이미 만든 것을 다시 고치는 일을 줄일 수 있습니다. 작은 기능을 따로 끝낼 수 있게 나누면 동료가 먼저 써 보고 문제를 알려줄 수도 있습니다. 다만 사람이 늘었다고 항상 빨라지는 것은 아니며 합의와 연결 확인에 필요한 시간도 생각해야 합니다.

04 · 무엇부터 맞출까요?

장비는 아직 직원 책상에 있습니다.

직원은 ‘반납 요청은 했어요. 장비는 오후에 가져갈게요’라고 말합니다. 지금 다른 직원에게 빌려 줘도 될까요?

이 사례에서는 안 됩니다. kch #7의 규칙은 직원의 반납 요청 뒤 관리자가 실제 장비를 확인해야 대여를 끝내도록 합니다. 확인 대기 중에는 아직 대여 중이며 새 대여를 허용하지 않습니다.

‘반납 요청 → 확인 대기 → 관리자 확인 → 반납 완료’를 공통 문서에 적고 반납·이력 Issue에서 연결합니다. 예를 들어 ‘직원이 반납을 요청한 뒤에도 대여 가능 목록에는 나오지 않는다’를 두 기능이 함께 확인할 조건으로 적을 수 있습니다.

자기 프로젝트에서 아직 규칙을 정하지 않았다면 실제 담당자에게 묻습니다. AI가 추천한 절차는 제안입니다. 담당자가 확인하지 않은 것을 회사의 확정 규칙으로 적지 않습니다. 필요한 기록의 이름과 형식도 코드에서 확인해 같은 기준으로 사용합니다.

05 · 그동안 따로 할 일

이미 있는 목록으로 무엇을 끝낼 수 있을까요?

승인과 반납의 순서는 남겨 두고, 기존 장비 목록과 내 신청 목록을 살펴봅니다.

장비 이름을 가져올 수 있다면 ‘장비명 검색’을, 신청의 반납 예정일을 가져올 수 있다면 ‘반납 예정일 순 정렬’을 후보로 삼을 수 있습니다. 검색·정렬은 이번 수업의 제안이며 실제로 구현돼 있거나 요청자가 확정한 요구라는 뜻은 아닙니다.

AI와 코드를 확인합니다. 필요한 장비명·반납 예정일·신청 번호가 있나요? 전체 목록을 가져올 수 있나요? 두 사람이 함께 고칠 코드가 있나요? 서로의 변경을 기다리지 않아도 각자의 결과를 확인할 수 있나요? 필요한 것이 없으면 그 준비 작업의 담당자와 순서를 먼저 정합니다.

이번에는 검색창만 맡기는 대신 ‘노트를 입력하면 노트북이 나오고 상세 화면까지 갈 수 있다’는 작은 기능을 맡깁니다. 입력창만 만들면 실제 검색과 연결하는 일이 남기 때문입니다. 화면·서버처럼 전문 분야로 나눌 수도 있지만 그때는 연결할 순서와 확인할 사람을 정합니다.

작게 나눈다고 필요한 조건까지 빼지는 않습니다. 장비가 100개인데 현재 화면의 20개만 검색되면 전체 검색을 끝낸 것이 아닙니다. 전체에서 찾을 방법을 준비하거나 요청자와 범위를 다시 합의해야 합니다.

06 · 질문이 Issue가 됩니다

‘검색 기능 추가’ 한 줄을 함께 고쳐 봅니다.

동료가 묻습니다. ‘이름으로 찾나요? 일부만 입력해도 되나요? 일치하는 장비가 없으면요?’

처음 요청은 ‘검색 기능 추가. 장비를 쉽게 찾게 해주세요’였습니다. 여기에 답을 붙여 봅니다. ‘장비 이름으로 찾습니다. 노트를 입력해도 노트북이 나옵니다. 없으면 결과 없음이라고 보여줍니다. 지우면 원래 목록으로 돌아갑니다.’

이 답이 만들 범위와 완료 조건이 됩니다. 완료 조건은 무엇을 확인하면 끝났다고 할지를 적은 약속입니다. ‘잘 작동한다’보다 입력과 예상 결과를 적으면 동료와 AI도 같은 결과를 확인할 수 있습니다.

다음은 질문에 답한 뒤의 수업용 초안입니다. A는 연습용 이름이며 실제 GitHub 번호가 아닙니다. 먼저 필요한 조회가 준비돼 있는지는 실제 코드에서 확인하고, 빈칸에는 확인한 내용만 적으세요.

# 장비 이름으로 검색하기

왜 만드나요?
직원이 장비가 많아도 원하는 장비를 이름으로 찾게 합니다.

누가 맡나요?
[담당자]

이번에 무엇을 만드나요?
내가 볼 수 있는 모든 장비에서 장비 이름으로 검색합니다.
검색어를 지우면 원래 목록으로 돌아갑니다.
카테고리·자동완성·새 권한 체계는 이번에 만들지 않습니다.

무엇을 확인하면 끝인가요?
- ‘노트’ 입력 → 이름에 ‘노트’가 포함된 노트북이 나옵니다.
- 없는 장비명 입력 → 결과 없음 안내가 나옵니다.
- 검색어 지우기 → 원래 목록으로 돌아갑니다.
- 다른 페이지에 있던 장비도 검색됩니다.
- 결과의 장비를 누르면 기존 상세 화면으로 이동합니다.
- 볼 권한이 없는 장비는 검색 결과에 나오지 않습니다.

먼저 필요한 일은 무엇인가요?
- 전체 장비에서 검색할 방법이 있는지 확인: [코드 위치·확인 결과]
- 없다면 조회 기능을 먼저 준비: [담당·Issue·완료 조건]
- 정렬 작업과 함께 고치는 코드가 있는지 확인: [내용·담당·순서]

확인한 결과
[실제 입력·결과·PR 링크·남은 일]
가상 목록만 확인했다면 실제 서비스 확인은 남았다고 적습니다.

07 · 정렬에도 적용해 봅시다

‘날짜순’만 적으면 어떤 질문이 돌아올까요?

신청일과 반납 예정일은 다른 날짜입니다. 같은 반납 예정일의 신청이 두 개 있을 수도 있습니다.

이번 목적은 먼저 반납할 장비를 찾는 것입니다. 따라서 반납 예정일이 빠른 신청부터 보여줍니다. 수업에서는 같은 날짜라면 신청 번호가 작은 것부터 보여주기로 정합니다. 이 기준은 수업용 합의이므로 실제 회사의 요구에 맞춰 확인합니다.

가상 목록으로 먼저 생각해 보세요. #18은 10월 30일, #14와 #12는 10월 28일이 반납 예정일이라면 순서는 #12, #14, #18입니다. 날짜를 바르게 정렬해도 기존 취소 버튼이 안 되거나 다른 직원의 신청이 보이면 완료가 아닙니다.

날짜가 빠진 신청이 있는지도 시작 전에 확인합니다. 있다면 맨 뒤에 둘지, 별도 표시할지 요청자와 정해 Issue에 추가합니다. 아래 예시는 반납 예정일이 있는 자료를 전제로 합니다. 확인하지 못한 규칙을 각자 추측해 채우지 않습니다.

# 내 신청을 반납 예정일 순으로 보여주기

왜 만드나요?
직원이 먼저 반납할 신청부터 확인하게 합니다.

누가 맡나요?
[담당자]

이번에 무엇을 만드나요?
내 신청 목록의 순서를 바꿉니다.
연체 계산·알림·전체 직원 조회는 이번에 만들지 않습니다.

무엇을 확인하면 끝인가요?
- 반납 예정일이 빠른 신청부터 나옵니다.
- 같은 반납 예정일이면 신청 번호가 작은 것부터 나옵니다.
- #18(10/30), #14(10/28), #12(10/28) → #12, #14, #18 순서입니다.
- 신청이 없으면 빈 목록 안내를 보여줍니다.
- 기존 신청 취소가 계속 됩니다.
- 다른 직원의 신청은 보이지 않습니다.
- 여러 페이지라면 전체 신청을 기준으로 순서를 맞춥니다.

먼저 필요한 일은 무엇인가요?
- 반납 예정일·신청 번호를 가져올 코드 확인: [위치·결과]
- 날짜가 없는 신청 유무와 처리 규칙: [확인·결정할 사람]
- 전체 순서를 맞출 방법과 함께 고칠 코드: [내용·담당·순서]
준비가 안 됐다면 먼저 필요한 Issue를 연결합니다.

확인한 결과
[실제 입력·결과·PR 링크·남은 일]

08 · 기다리는 동안의 준비

반납 화면을 미리 만들면 어디까지 끝난 걸까요?

승인 기능은 아직 없지만, 팀은 주고받을 대여 기록의 내용을 합의했습니다.

먼저 승인·반납 담당자가 빌린 사람, 장비, 반납 예정일과 상태의 뜻을 맞춥니다. 실제 코드의 이름과 형식을 확인하고, 기록을 만들 담당자와 그 결과를 확인할 방법을 정합니다.

그 약속에 맞춰 ‘김민수 · 노트북 1번 · 10월 30일 반납’이라는 가상 기록을 넣으면 반납 화면과 버튼을 미리 만들 수 있습니다. ‘예시 기록으로 화면은 확인했습니다. 실제 승인·저장·권한 확인은 남았습니다’라고 적습니다.

승인 기능이 준비되면 실제로 신청하고 승인한 장비로 반납을 해 봅니다. 반납 요청만 했을 때는 다시 빌릴 수 없는지, 관리자 확인 뒤 기록이 끝나는지, 이력도 맞는지 확인합니다. 가상 기록으로 성공한 것만으로 실제 연결까지 완료됐다고 할 수는 없습니다.

09 · GitHub에 남기기

같은 목표로 묶는 것과 순서를 정하는 것은 다릅니다.

작업 내용을 정했다면 누가 무엇을 기다리는지도 다른 사람이 볼 수 있게 남깁니다.

‘장비관리 개선’ 아래 검색·정렬을 묶는 것은 하위 Issue, 즉 sub-issue입니다. 같은 목표의 진행을 모아 보는 관계입니다. 검색이 끝나야 정렬을 시작한다는 뜻은 아닙니다.

반납이 승인을 기다린다는 표시는 Blocked by입니다. 반납 Issue에서 승인 Issue를 선택합니다. 반대쪽에서는 Blocking 또는 Is blocking으로 보입니다. 아래는 실제 kch #7의 관계 영역입니다. 본문에 링크를 쓰는 것만으로 이 관계가 자동 등록되지는 않습니다.

이 표시는 기다리는 관계를 보여줍니다. CI처럼 PR 병합을 자동으로 막아 주지는 않습니다. 먼저 필요한 작업이 실제로 끝났는지와 합친 뒤 확인 결과를 검토해야 합니다. 관계 설정에는 triage 이상의 저장소 권한이 필요합니다.

1. 01

   같은 목표 아래 묶기

   왜 하나요? 어떤 결과를 함께 만드는 일인지 보여줍니다.

   할 일 큰 목표의 Issue 아래 Create sub-issue로 새 작업을 만들거나, 옆 메뉴의 Add existing issue로 기존 작업을 연결합니다.

   정상이라면 검색·정렬이 같은 큰 목표 아래 보입니다. 이것만으로 작업 순서가 정해지지는 않습니다.

2. 02

   기다리는 관계 표시하기

   왜 하나요? 무엇 때문에 기다리고 있는지 팀이 알 수 있게 합니다.

   할 일 뒤 작업인 반납 Issue를 엽니다. 오른쪽 Relationships → Mark as blocked by에서 승인 Issue를 선택합니다. 이미 연결돼 있다면 Change blocked by로 확인·변경합니다.

   정상이라면 반납 쪽에는 Blocked by, 승인 쪽에는 뒤따르는 작업이 보입니다. 필요한 이유도 본문에 적습니다.

   TIP · 권한이 없다면 실제 저장소를 바꾸려 하지 말고 본문에 필요한 작업·이유·담당자를 적은 뒤 권한 있는 동료에게 연결을 요청합니다.

10 · AI에게 맡기기 전에

‘동시에 가능’이라는 결론의 근거를 묻습니다.

AI가 검색·정렬 Issue를 나누고 ‘서로 독립적입니다’라고 답했습니다. 코드를 보고 판단했는지부터 확인합니다.

이름과 반납 예정일을 실제로 가져오는 코드가 있는지, 두 작업이 같은 코드를 바꾸는지 찾아 달라고 합니다. ‘있을 것이다’라는 추측과 코드에서 확인한 내용을 나눠 읽습니다.

예를 들어 ‘현재 페이지의 20개만 검색할 수 있습니다’라는 답이 나오면 전체 장비에서 찾을 방법을 먼저 준비해야 합니다. ‘권한 체계도 새로 만들자’는 제안이 나오면 왜 필요한지 확인하고 요청자와 이번 범위를 정합니다.

AI가 초안을 쓰더라도 무엇을 만들고 무엇으로 완료를 확인할지는 팀이 읽고 판단합니다. 의존성이 없다고 보이게 하려고 필요한 조건을 빼거나, 모르는 업무 규칙을 마음대로 채워 넣지는 않았는지 확인하세요.

1. 01

   초안을 요청하고 근거 확인하기

   왜 하나요? 동료가 시작할 수 있는 작업인지 판단합니다.

   할 일 아래 요청을 자신의 프로젝트와 두 기능 이름에 맞춰 사용합니다.

   복사해서 써도 되는 요청

   현재 코드와 Issue를 읽어줘. 장비명 검색과 내 신청의 반납 예정일 순 정렬을 나눠 맡으려고 해. 필요한 정보가 있는지, 같은 코드를 고치는지, 서로 기다릴 일이 있는지 코드 위치와 함께 알려줘. 확인한 내용과 모르는 내용을 나눠줘. 각 Issue에 만들 것·이번에 만들지 않을 것·먼저 필요한 일과 담당·무엇을 확인하면 끝인지를 적어줘. 아직 GitHub에 발행하지 말고 초안부터 보여줘.

   정상이라면 각 Issue를 지금 시작할 수 있는 이유 또는 먼저 필요한 작업을 설명할 수 있습니다.

11 · 여섯 명이 함께 개발하기

하나의 저장소에서 여섯 기능을 PR로 합칩니다.

앞의 두 Issue 작성 연습을 실제 협업으로 이어갑니다. 강사 1명과 교육생 5명이 기능 하나씩 맡고 강사가 main 통합을 담당합니다. 전체 안내는 https://github.com/Mrbaeksang/kch/issues/20 입니다.

강사는 #21 장비 상태별 수량 요약, 교육생은 #15 장비 조건 필터, #16 내 신청 정렬, #17 반납일 빠른 선택, #18 장비 정보 복사, #19 관리자 전체 장비 CSV를 맡습니다. 6개 기능은 이번 수업에서 추가한 요구입니다. 기존 #6 승인·#7 반납·#8 이력·#9 수리·#10 운영 연결은 후속 제품 작업으로 남습니다.

공개 저장소라고 누구나 원본에 push할 수 있는 것은 아닙니다. 강사가 GitHub 사용자명으로 Collaborator를 초대하고 교육생이 수락합니다. 그 뒤 원본 저장소를 clone합니다. clone은 코드를 내 컴퓨터로 가져오는 일입니다. 이미 코드를 받은 사람은 로컬 변경을 보존하고 최신 main을 가져옵니다. 실행 방법은 kch의 README를 따르고 개발 테스트 계정과 가상 자료를 사용합니다.

브랜치는 각자 변경을 쌓는 작업 공간입니다. 최신 main에서 feature/asset-filters처럼 Issue에 적힌 이름으로 만듭니다. 먼저 5분 동안 Issue를 서로 읽고 입력·결과·공통 변경을 질문합니다. 각자 기능과 관련 검사를 마친 뒤 원본 저장소의 자기 브랜치에 push합니다. push는 로컬 커밋을 GitHub에 올리는 일입니다. 로컬 파일만으로는 PR을 제출할 수 없습니다.

PR은 내 브랜치의 변경을 main에 합쳐 달라는 요청입니다. 예를 들어 #15 담당자는 feature/asset-filters에서 main으로 PR을 열고 본문에 Closes #15, 바뀐 화면, 실제 검사 결과, 남은 일을 적습니다. Closes 문구는 해당 PR이 기본 브랜치에 병합되면 Issue를 닫도록 연결합니다. 아직 구현 중이면 Draft PR로 공유합니다.

6개 기능은 이미 있는 장비·신청 데이터로 시작하므로 승인·반납 구현을 기다리지 않습니다. 다만 요약·필터·복사·CSV는 Assets.tsx의 연결 부분을 함께 고칩니다. 기능 본체·테스트는 각자의 새 파일에 두고 연결을 작게 합니다. 다른 사람이 먼저 병합하면 최신 main을 내 작업 브랜치에 merge하고 충돌이 난 부분을 두 기능이 모두 남도록 고칩니다. 모든 작업이 같은 파일을 피해야 한다는 뜻은 아닙니다.

강사는 PR의 범위·화면·검사 결과를 검토합니다. Backend build and test와 Frontend build and test가 통과하고 최신 main을 반영했는지 확인한 뒤 Squash 병합합니다. Squash는 PR 안의 커밋들을 main에 하나의 커밋으로 남기는 방식입니다. 한 PR이 합쳐지면 다음 PR도 main을 반영하고 CI를 다시 확인합니다. 강사 자신의 #21 PR도 같은 CI와 main 보호를 따릅니다.

main은 관리자 역할만 PR을 통해 갱신하도록 제한했습니다. 일반 협업자는 작업 브랜치를 올리고 PR을 제출합니다. 관리자 계정을 추가하면 그 사람도 병합할 수 있으므로 교육생을 관리자로 지정하지 않습니다. 2026년 10월 28일 설정 조회 기준이며 실제 수강생 계정의 차단 동작은 수업 전에 별도로 확인합니다.

합친 뒤 새 기능들뿐 아니라 기존 장비 등록·검색·상세·직원 신청·취소를 확인합니다. 강사도 기능을 사전 개발하지 않고 교육생과 같은 시점에 시작합니다. 강사 요약과 CSV는 전체 장비 기준이고, 필터는 목록에 보이는 장비만 좁힙니다. 필터를 적용해도 요약 수량이 바뀌지 않는지 함께 확인합니다. 수업 종료 때 못 끝낸 것은 초안 PR과 남은 검사·다음 담당을 기록합니다. CI 통과와 main 병합은 실제 Google 로그인·운영 배포 완료를 뜻하지 않습니다.