From bc37ae633441a596c39ddbe795ef9664b6e80a14 Mon Sep 17 00:00:00 2001
From: learncold <learncold8154@gmail.com>
Date: Thu, 2 Apr 2026 17:40:01 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20epic=20sub-issue=20=EC=97=B0=EA=B2=B0?=
 =?UTF-8?q?=20=EA=B7=9C=EC=B9=99=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/ISSUE_TEMPLATE/lightweight-task.yml | 3 ++-
 .github/ISSUE_TEMPLATE/task.yml             | 3 ++-
 AGENTS.md                                   | 2 ++
 CONTRIBUTING.md                             | 6 +++++-
 docs/GitHub Project.md                      | 2 ++
 5 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/lightweight-task.yml b/.github/ISSUE_TEMPLATE/lightweight-task.yml
index 1e52993..c778a6d 100644
--- a/.github/ISSUE_TEMPLATE/lightweight-task.yml
+++ b/.github/ISSUE_TEMPLATE/lightweight-task.yml
@@ -9,6 +9,7 @@ body:
 
         GitHub assigns the numeric issue number automatically. Enter only the short title after `Task-`.
         Keep the issue focused enough that it can usually map to one PR.
+        If this task belongs under an existing Epic, add the Epic in `Parent Issue` and then link the issue as a native GitHub `sub-issue` so it appears in the Project view.
   - type: textarea
     id: summary
     attributes:
@@ -21,7 +22,7 @@ body:
     id: parent-issue
     attributes:
       label: Parent Issue
-      description: Link the parent epic when this task belongs under one.
+      description: If this task belongs under an existing Epic, enter that Epic here and then add the native `sub-issue` link after issue creation.
       placeholder: "#1"
   - type: dropdown
     id: area
diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml
index 95c538e..65c8f45 100644
--- a/.github/ISSUE_TEMPLATE/task.yml
+++ b/.github/ISSUE_TEMPLATE/task.yml
@@ -9,6 +9,7 @@ body:
 
         GitHub assigns the numeric issue number automatically. Enter only the short title after `Task-`.
         Prefer one task per PR, and keep the task scoped tightly enough that it can be reviewed and merged independently.
+        If this task belongs under an existing Epic, add the Epic in `Parent Issue` and then link the issue as a native GitHub `sub-issue` so it appears in the Project view.
   - type: textarea
     id: summary
     attributes:
@@ -21,7 +22,7 @@ body:
     id: parent-issue
     attributes:
       label: Parent Issue
-      description: Link the parent epic when this task belongs under one.
+      description: If this task belongs under an existing Epic, enter that Epic here and then add the native `sub-issue` link after issue creation.
       placeholder: "#1"
   - type: dropdown
     id: area
diff --git a/AGENTS.md b/AGENTS.md
index 3225272..26a4214 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -61,6 +61,8 @@
 - Use GitHub issue forms for new work items; blank issues are disabled.
 - Before starting work, check whether a related GitHub issue already exists.
 - If no related issue exists and the current policy does not exempt the work from issue creation, open a new issue in Korean first and then start the implementation.
+- When a new task clearly belongs under an existing Epic, add it under that Epic as a native GitHub `sub-issue`.
+- After linking the task under its Epic, make sure the relationship is visible from the Project view via `Parent issue` / `Sub-issues progress`.
 - If the work falls under the existing docs/policy-only exception, it may proceed without opening a separate issue.
 - Issue types currently supported:
   - `Epic` for larger parent work
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f74660a..cf49625 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,6 +8,8 @@ PR은 작은 단위로 나누고, 기본적으로 어떤 issue를 해결하는
 - 기본 작업 흐름은 `issue -> branch -> PR -> merge`입니다.
 - 작업을 시작하기 전에 먼저 관련 GitHub issue가 이미 있는지 확인합니다.
 - 관련 issue가 없고 현재 정책상 issue 생성을 생략할 수 없는 작업이면, 새 issue를 한글로 등록한 뒤 작업을 시작합니다.
+- 새 task가 기존 Epic 아래에 들어가야 하는 범위라면, issue를 만든 뒤 GitHub native `sub-issue`로 연결합니다.
+- 연결 후에는 Project view의 `Parent issue`, `Sub-issues progress`에서 보이는지 확인합니다.
 - 다만 `docs/`, `uml/`, `CONTRIBUTING.md`, PR/issue template, PR 정책 워크플로처럼 문서 또는 기여 정책만 다루는 변경은 별도 issue 없이 진행할 수 있습니다.
 - 위 예외에 해당하는 변경이 해당 경로에만 한정된다면 유지보수자는 `main`에 직접 commit/push할 수 있습니다.
 - 문서/정책 변경과 코드/빌드 변경이 섞이면 예외를 쓰지 않고 일반 PR 흐름으로 진행합니다.
@@ -24,7 +26,9 @@ PR은 작은 단위로 나누고, 기본적으로 어떤 issue를 해결하는
 - `Lightweight Task`는 `Docs`, `Chore`, `Analysis` 같은 작은 작업에 사용합니다.
 - 제목은 저장소 관례에 맞춰 `EPIC- short title` 또는 `Task-short title` 형식을 유지합니다.
 - GitHub issue 번호(`#12` 같은 값)는 생성 후 자동으로 붙습니다. 제목에는 숫자를 직접 적지 않습니다.
-- 가능하면 task는 parent epic을 함께 적고, Sprint와 Area를 바로 정합니다.
+- task가 기존 Epic 범위에 속하면 parent epic을 적고 native `sub-issue` 관계까지 연결합니다.
+- parent/sub-issue 관계를 연결한 뒤 Project view의 `Parent issue`, `Sub-issues progress`에서 바로 보이는지 확인합니다.
+- Sprint와 Area는 issue 생성 시 바로 정합니다.
 - issue form의 `Area`와 GitHub Project의 `Area` 옵션이 일시적으로 다를 수 있습니다. 현재 Project 보드에 `Build` 옵션이 없으면 issue 자체에는 `Build`를 유지하고, 보드에는 가장 가까운 기존 영역으로 배치한 뒤 본문에 의도를 남깁니다.
 - 구조나 의존성에 영향을 주는 issue는 본문에 계층 영향과 검증 계획을 남깁니다.
 
diff --git a/docs/GitHub Project.md b/docs/GitHub Project.md
index acf9ddf..b98c4f9 100644
--- a/docs/GitHub Project.md	
+++ b/docs/GitHub Project.md	
@@ -61,6 +61,8 @@
 ## 메모
 - 작업을 시작하기 전에 먼저 관련 issue가 이미 있는지 확인한다.
 - 관련 issue가 없고 docs/policy-only 예외가 아닌 작업이면, 적절한 issue form으로 한국어 issue를 먼저 만든 뒤 branch 작업으로 들어간다.
+- 새 task가 기존 Epic 범위에 속하면 issue를 만든 뒤 GitHub native `sub-issue`로 연결한다.
+- Project view에서 `Parent issue`, `Sub-issues progress` 컬럼으로 연결 결과가 보이는지 확인한다.
 - `Docs`, `Chore`, `Analysis`는 `Lightweight Task` form으로 가볍게 등록한다.
 - `Engine`, `Domain`, `Application`, `Build`는 `Implementation Task` form으로 범위와 검증 계획까지 남긴다.
 - 현재 Project 보드의 `Area` 필드에는 `Build` 옵션이 없으므로, Build 성격 task는 issue form과 본문에는 `Build`로 남기고 보드에서는 임시로 가장 가까운 기존 영역에 배치한다.