Quick Comparison
GFM task list는 - [ ]와 - [x]로 미완료·완료를 표시하지만, 체크박스 렌더링과 상태 변경은 GitHub 등 지원 환경에서만 보장됩니다.
- [ ] 로그인 화면 구현
- [x] API 응답 형식 정리
- [ ] 문서 업데이트
## 릴리스 준비
- [x] 버전 태그 정리
- [ ] 변경 로그 작성
- [ ] 배포 후 smoke test- [ ]와 - [x]는 GFM task-list 문법이고, GitHub의 comment와 issue·PR 본문에서는 권한에 따라 상태를 바꿀 수 있습니다. Markdown 체크박스와 작업 추적 기능을 혼동하지 말고, retired tasklist block은 새로 쓰지 않으며 issue 간 진행 추적은 GitHub sub-issues나 Projects 같은 현재 기능을 선택합니다.
문법
task list는 GFM 확장이라 GitHub 이외 환경에서는 체크박스가 렌더링되지 않을 수 있다
- [ ], - [x] 형태의 task list는 GitHub Flavored Markdown 확장 문법이다. GitHub는 task marker를 checkbox로 렌더링하고, comment에서는 체크 상태를 바꾸는 제품 상호작용도 제공한다. 반면 CommonMark 표준 파서, 일부 정적 사이트 빌더, Markdown 뷰어에서는 - [ ] 텍스트가 일반 bullet 목록으로 처리되거나 대괄호가 그대로 노출될 수 있다. 이식성이 필요한 문서라면 renderer 지원 여부를 먼저 확인해야 한다.
- [x] 완료된 작업 (GitHub에서 체크 표시)
- [ ] 미완료 작업 (GitHub에서 빈 체크박스)
<!-- CommonMark만 지원하는 환경에서는 일반 목록으로 보일 수 있음 -->GitHub comment와 이슈·PR에서는 권한이 있는 사용자가 체크 상태를 바꿀 수 있다
GitHub comment와 이슈·PR 본문에 task list를 작성하면, 해당 권한을 가진 사용자가 체크박스를 클릭해 완료 상태를 바꿀 수 있다. README처럼 정적 문서에 렌더링된 task list의 상호작용 방식은 표준이 정하지 않으므로, 상태를 운영해야 하면 이슈나 PR 같은 GitHub 협업 표면을 기준으로 확인한다. 예전에 GitHub가 제공하던 tasklist block은 retired되었으므로, issue 간 진행 추적은 sub-issues나 Projects를 사용한다.
<!-- 이슈/PR 본문: 클릭 가능한 체크박스 -->
- [ ] 코드 리뷰
- [x] 테스트 작성
- [ ] 문서 업데이트task list 항목은 실행 가능한 단위로 쪼개야 체크 여부가 의미를 갖는다
task list는 작업의 실행 상태를 드러내는 도구다. 항목이 "백엔드 개발 완료"처럼 모호하고 크면 체크 여부만으로 실제 진행 상황을 알기 어렵고, 협업자가 무엇이 완료됐는지 판단할 수 없다. 릴리스 체크리스트, PR 머지 전 점검, 온보딩 단계처럼 항목이 명확하고 독립적으로 완료 가능한 상황에서 task list가 가장 효과적이다. 항목이 너무 크다면 이슈를 분리하거나 sub-task로 쪼개는 것을 먼저 고려해야 한다.
<!-- 나쁜 예: 항목이 모호하고 큼 -->
- [ ] 백엔드 개발
- [ ] 프론트엔드 작업
<!-- 좋은 예: 독립적으로 완료 가능한 단위 -->
- [x] API 엔드포인트 /users GET 구현
- [x] 응답 스키마 문서화
- [ ] 에러 핸들링 추가
- [ ] 통합 테스트 작성중첩 task list는 문법보다 진행 구조를 먼저 점검한다
GFM은 들여쓰기로 중첩 task list를 표현할 수 있다. checkbox의 상호작용과 진행 요약은 renderer 제품 기능이므로, 단순 중첩 문법만으로 상위 진행 상태가 자동 집계된다고 가정하지 않는다. 하위 작업이 많다면 task list 중첩보다 별도 이슈를 만들어 상위 이슈에 참조하는 방식이 GitHub 협업 도구와 더 잘 맞는다.
또한 README의 task list는 "보여 주기용"인지 "실제 진행 추적용"인지 먼저 구분해야 한다. 정적 문서의 checkbox 상호작용은 renderer 구현에 따라 다르므로, 상태를 운영하려면 이슈·PR·comment 같은 협업 표면을 기준으로 확인한다.
선택 기준
| 상황 | 적합한 선택 |
|---|---|
| PR 머지 전 점검 목록 | PR 본문의 task list |
| 릴리스 체크리스트 | 이슈·PR의 task list |
| README 진행 상황 시각화 | task list (상호작용은 renderer에 따라 확인) |
| CommonMark 환경의 체크리스트 | 지원 여부 확인 후 사용 |
| 항목이 크고 모호한 경우 | 이슈 분리 후 task list 항목 구체화 |
| 실제 진행 상태를 클릭으로 관리해야 할 때 | README보다 GitHub comment·이슈·PR 우선 |
주의할 점
task list는 GFM 확장이라 CommonMark 표준 환경에서는 체크박스가 렌더링되지 않을 수 있습니다. 체크리스트는 실행 상태를 드러내는 도구이지 설계를 대신하지는 않습니다. 항목이 너무 크면 체크 여부만으로 실제 진행 상황을 알기 어려우므로 독립적으로 완료 가능한 단위로 쪼개는 것이 중요합니다.
- [ ] 서비스 안정화이런 항목은 체크돼도 무엇이 끝났는지 알기 어렵습니다. task list는 "완료 정의가 짧게 말해지는 단위"일 때만 효과가 큽니다.
참고 링크
2 sources