yasukei/agent-skills

GitHub 이슈 생성

사용자가 정한 형식으로 이슈를 작성하기 위한 스킬입니다. 목표는 "매번 같은 구성으로, 읽으면 바로 착수·완료 판단할 수 있는 이슈"를 만드는 것입니다. 특히 Acceptance criteria는 나중에 issue-to-pr 등에서 구현·리뷰할 때 완료 조건으로 그대로 사용되므로, 검증 가능한 형태로 작성합니다.

1. 리포지토리의 템플릿을 먼저 확인한다

리포지토리 측에 템플릿이 있으면, 해당 리포지토리의 규칙으로서 이 스킬의 템플릿보다 우선합니다. 확인할 위치:

• .github/ISSUE_TEMPLATE/ 아래의 *.md와 *.yml / *.yaml (config.yml은 설정 파일이며 템플릿이 아닙니다)
• .github/ISSUE_TEMPLATE.md, 루트의 ISSUE_TEMPLATE.md, docs/ISSUE_TEMPLATE.md
• 위 중 아무것도 없으면, 오너의 조직 공통 리포지토리 <owner>/.github의 같은 위치

로컬에 클론이 있으면 파일을 직접 봅니다. 없으면 gh api repos/<owner>/<repo>/contents/.github/ISSUE_TEMPLATE 등으로 가져옵니다.

템플릿을 찾았으면:

• 만들려는 이슈의 종류(작업 / 버그)에 맞는 것을 파일 이름·name·about·labels에서 선택합니다.
• 제목 구성은 템플릿을 따르고, 이 스킬의 제목은 섞지 않습니다. 의존성 등 쓸 곳이 없는 중요한 정보만 끝에 짧게 덧붙입니다.
• YAML 이슈 폼인 경우, GitHub은 폼 전송 내용을 각 항목의 attributes.label을 ### <label> 제목으로 한 본문으로 저장합니다. 같은 형태로 본문을 조립하고, required: true인 항목은 반드시 채웁니다.
• 템플릿의 frontmatter / 폼 정의에 있는 title(접두사), labels, assignees를 반영합니다.

종류에 맞는 템플릿이 없는 경우(예: bug 템플릿은 있지만 작업용이 없는 경우)는, 해당 종류만 아래 템플릿을 사용합니다.

2. 종류를 결정한다

• 작업: 새 기능, 개선, 리팩터, 문서, CI, 조사 등 "할 일". → 작업 템플릿
• 버그: 기대한 대로 동작하지 않는 것의 수정. → 버그 템플릿

고민되면 "현재 동작이 사양에 반하는가"로 판단합니다. 반하면 버그입니다.

3. 작업 템플릿

## Goal

<무엇을 달성할지 1~2문장. 왜 필요한지도 한마디 덧붙임>

## Scope

- <할 일. 묶음이 여러 개면 **굵은 소제목**으로 그룹화>

## Out of scope

- <하지 않을 일. 오해받기 쉬운 인접 영역을 명시>

## Acceptance criteria

- <완료 판단 가능한 조건. 테스트·CI·명령어 결과 등 관측 가능한 형태로>

## Depends on

- #<번호>

Part of #<부모 이슈 번호>.

작성 포인트:

• Goal은 "무엇을"뿐 아니라 "왜"를 한마디 넣습니다. 나중에 읽는 사람이 우선순위나 판단 근거를 추적할 수 있도록 하기 위해서입니다.
• Scope는 구현자가 헤매지 않을粒度로, 타입명·명령어명·파일명 등 구체적으로 씁니다. 이전 리뷰에서 넘어온 사항 등은, 그걸 알 수 있는 소제목으로 구분합니다.
• Out of scope는 "이번에는 넣지 않는다"를 명시하여 스코프 팽창을 막습니다. 정말 없으면 - None이라고 쓰고, 섹션 자체는 남깁니다(쓰기 잊은 것이 아니라 "없다"는 것을 알 수 있도록).
• Acceptance criteria는 "~가 구현되었다"가 아니라 "~의 테스트가 있고 통과한다" "CI에서 ~가 실행되어 성공한다"처럼, 제삼자가 확인할 수 있는 형태로 합니다.
• Depends on은 먼저 끝나야 하는 이슈를 - #번호로 나열합니다(GitHub이 제목과 함께 표시합니다). 없으면 - None.
• 부모 이슈에서 분할한 작업이면 끝에 Part of #<번호>.를 씁니다.
• 배경 자료·참고 링크·미결정 사항이 있을 때만, Acceptance criteria 뒤에 ## Notes를 추가합니다. 억지로 만들지 않습니다.

4. 버그 템플릿

## Summary

<무슨 일이 일어나고 있는지 1~2문장>

## Steps to reproduce

1. <절차>
2. <절차>

## Expected behavior

<원래 어떻게 되어야 하는지>

## Actual behavior

<실제로 어떻게 되는지. 에러 메시지나 로그는 코드 블록으로 첨부>

## Environment

- Version / commit: <버전 또는 커밋 해시>
- <OS / 브라우저 / Node 등 관련된 것>

## Acceptance criteria

- 위 절차에서 Expected behavior와 같이 된다
- 이 버그를 재현하는 회귀 테스트가 추가되고 통과한다

## Notes

<원인 추정, 관련 이슈/PR, 회피 방법 등. 없으면 이 섹션은 생략>

작성 포인트:

• 절차·환경·로그는, 사용자에게 들은 것 또는 스스로 확인한 것만 씁니다. 모르는 항목은 추측으로 채우지 말고 Unknown이라고 쓰거나 사용자에게 묻습니다. 지어낸 재현 절차는 조사를 잘못된 방향으로 이끕니다.
• 원인 추정은 사실(Actual behavior)과 분리하여 Notes에 씁니다. 증상과 가설이 섞이면, 가설이 빗나갔을 때 이슈가 읽기 어려워집니다.
• 수정 방침이 이미 정해진 경우도 Notes에 씁니다.

5. 제목·라벨·메타데이터

• 제목은 <area>: <내용> 형태로 합니다(예: core: data types, tree IR, and UI–runtime protocol). area는 대응하는 area:* 라벨 등 리포지토리의 기존 구분에 맞춥니다. 버그는 수정 내용이 아니라 증상을 씁니다(예: runtime: TON timer does not fire after coldReset).
• 라벨은 gh label list로 기존 것 중에서 선택합니다. area계열에 더해, 버그라면 bug가 있으면 붙입니다. 존재하지 않는 라벨은 함부로 만들지 않습니다.
• 마일스톤이나 부모 이슈를 알 수 있다면 설정합니다.
• 제목과 본문의 언어는 해당 리포지토리의 기존 이슈와 PR에 맞춥니다(gh issue list --state all --limit 10와 gh pr list --state all --limit 10로 확인). 기존 이슈도 PR도 없으면 일본어로 씁니다.
• 섹션명(Goal, Scope, Summary, Steps to reproduce 등)은 본문이 일본어여도 영어 그대로 사용합니다. 단, 리포지토리의 템플릿을 사용하는 경우는 해당 템플릿의 제목을 그대로 사용합니다.

6. 생성한다

본문을 임시 파일에 쓰고, --body-file로 전달합니다(쉘의 따옴표로 본문이 깨지는 것을 피하기 위해).

gh issue create --repo <owner>/<repo> \
  --title "<title>" --body-file /tmp/issue-body.md \
  --label "<label>" --milestone "<milestone>"

• 사용자가 "만들어"라고 명확히 말하면 그대로 생성합니다. 초안만 부탁받았을 때나, 내용의 대부분을 추측으로 보충했을 때는 본문을 보여주고 확인한 후 만듭니다.
• 부모 이슈가 있으면, 본문의 Part of #N.에 더해 GitHub의 sub-issue로도 연결합니다(gh api로 POST /repos/<owner>/<repo>/issues/<부모번호>/sub_issues, sub_issue_id에는 자식 이슈 번호가 아니라 id를 전달). API를 사용할 수 없으면 본문의 기술로 충분합니다.
• 여러 이슈로 분할하여 만들 때는, 의존되는 쪽부터 순서대로 만들고 Depends on에 실제 번호가 들어가도록 합니다.
• 생성 후에는 이슈의 URL을 알려줍니다.