First Contribution Ko

---
name: first-contribution-ko
metadata:
  version: "1.10.6"
description: "개발자가 오픈소스에 첫(혹은 다음) 기여를 하도록 처음부터 끝까지 돕습니다 — 초보자 친화적인 레포를 고르고, 진짜로 열려있는 good first issue를 찾아내고(연결된 PR, 담당자, 코멘트를 확인해서 이미 죽은 이슈는 걸러냄), AI 코딩 에디터로 실제 수정 작업을 진행합니다. 사용자가 오픈소스 기여를 시작하고 싶어하거나, 이슈 추천을 요청하거나, 이 레포가 초보자한테 괜찮은지 물어보거나, 깃허브 컨트리뷰션을 쌓고 싶다고 하거나, 어떤 프로젝트에 기여할지 모르겠다고 할 때, 언어나 프레임워크나 관심 분야만 언급해도(러스트 관련된 거 기여하고 싶다는 식으로) 이 스킬을 사용하세요. 사용자와의 대화는 한국어로 진행합니다."
---

# First Contribution (한국어 버전)

사용자가 "오픈소스에 기여하고 싶다"에서 실제 PR 제출(혹은 최소한 제출 직전)까지 가도록 돕는 스킬입니다. 총 4단계 + 부가 단계로 구성되어 있어요. 순서대로 진행하되, 사용자가 이미 끝낸 단계는 건너뛰세요 — 예를 들어 이미 특정 레포를 정했다면 바로 Phase 2로 갑니다.

**이 스킬을 사용하는 동안 사용자와의 모든 대화는 한국어로 진행하세요.** 코드, 커밋 메시지, PR 제목처럼 프로젝트 관례상 영어가 필요한 부분은 예외입니다.

## 이 스킬이 존재하는 이유

`good first issue` 라벨은 생각보다 자주 거짓말을 합니다. 인기 있는 레포일수록 라벨이 붙은 지 오래된 이슈는 이미 누군가 PR을 올렸거나, 다른 커밋으로 우연히 고쳐졌거나, 그냥 더 이상 유효하지 않은 경우가 많아요. 검증 없이 이슈를 추천하는 게 이 스킬에서 가장 흔히 발생하는 실패 케이스입니다 — 사용자의 시간을 낭비하게 하고, 이미 죽은 이슈에 찾아가게 만들어 신뢰를 깎습니다. **Phase 3의 검증 없이는 절대 특정 이슈를 추천하지 마세요.**

---

## Phase 1 — 사용자가 원하는 걸 정확히 파악하기

"오픈소스 기여할 만한 프로젝트 찾아줘" 같은 막연한 요청에 바로 레포 검색부터 들어가지 마세요. 뒤 단계의 정밀도가 여기서 결정됩니다.

대화에서 이미 답이 나오지 않았다면 `ask_user_input_v0` 같은 버튼형 선택 도구로 좁혀나가세요 — 타이핑보다 빠르고, 막연한 질문 하나로 퉁치지 않고 실제로 좁히게 강제하는 효과가 있습니다. 이미 나온 답은 다시 묻지 말고 그대로 이어받으세요.

1. **관심 도메인** (단일 선택) — 선택지는 `references/domain-categories.md`. 가장 중요한 질문입니다 — 본인이 실제로 쓸 만한 것에 기여할 때 꾸준히 이어갈 확률이 높아요.
2. **세부 영역** (단일 선택, 동적) — 고른 도메인에 맞는 목록을 `references/subcategory-map.md`에서 불러오세요.
3. **언어 / 스택** (단일 또는 다중 선택) — 그 세부 영역에서 흔히 쓰이는 스택들과 "상관없음"을 함께 제시하세요.
4. **경험 수준** (단일 선택) — 첫 PR / 몇 번 해봤고 좀 더 큰 걸 원함 / 능숙하고 의미 있는 이슈를 원함.
5. **기여 유형** (다중 선택) — 문서·README, 타입 힌트·코드 정리, 버그 수정, 작은 기능 추가.

다섯 개를 기계적인 인터뷰처럼 다 돌리지는 마세요. 이미 답한 건 건너뛰고, 사용자가 이미 특정 레포를 정해서 왔다면 그 레포를 후보로 두고 바로 Phase 2로 가세요.

**대부분의 버튼형 선택 도구는 질문당 선택지가 4개까지입니다.** 그런데 `domain-categories.md`에는 8개가 있습니다. 4개를 조용히 버리지 말고, 1번 질문에서는 4개의 묶음으로 그룹핑하세요(예: "AI / RAG · 벡터 DB", "백엔드 · 데이터베이스", "인프라 / DevOps · 보안", "프론트엔드 · 모바일 · 게임"). 그 다음 2번 질문이 묶음 안에서 좁히는 역할을 합니다. 묶어서 보여준다는 걸 말해주세요 — 빠진 선택지가 사용자에 대한 판단이 아니라는 걸 알 수 있게요.

## Phase 2 — 후보 레포 평가

`bash_tool`로 GitHub REST API에 `curl`을 날려 실제 수치를 확보하세요(`api.github.com`은 네트워크 허용 목록에 있습니다). 사용자가 특정 레포를 언급하지 않았다면 `web_search`로 관심 도메인 내 후보를 찾으세요.

각 후보 레포마다 이걸 확인하세요:

```bash
curl -s "https://api.github.com/repos/{owner}/{repo}"
# -> stargazers_count, open_issues_count, pushed_at(최근 활동), archived(반드시 false여야 함)

curl -s "https://api.github.com/search/issues?q=repo:{owner}/{repo}+label:%22good+first+issue%22+state:open"
# -> 현재 열려있는 good-first-issue 총 개수
```

Rate limit 참고: 인증 없는 GitHub API 호출은 시간당 60회로 제한됩니다. (Prerequisites가 이미 요구하는) `gh`로 인증하면 5000회/시간으로 올라가지만, **검색 API**에는 어떻게 인증하든 빠른 쿼리 몇 번이면 걸리는 *secondary* 제한이 별도로 존재합니다. 검색 호출은 5~8초 간격을 두고, 같은 질문에 답할 수 있는 일반 REST 엔드포인트(`/pulls`, `/issues`, `/issues/{n}/timeline`)를 우선 쓰세요. "secondary rate limit"이 적힌 403이 뜨면 즉시 재시도가 아니라 1~2분 백오프가 필요합니다. 그래도 막히면 `web_search`/`web_fetch`로 대체하고, 수치가 덜 정확할 수 있다는 걸 사용자에게 짧게 알려주세요.

`references/repo-evaluation-criteria.md`를 먼저 읽고(기억에 의존해서 대충 점수 매기지 마세요) 후보를 채점하세요. 한눈에 볼 핵심 신호는 다음과 같습니다:

| 신호 | 좋은 신호 | 경고 신호 |
|---|---|---|
| 오픈 이슈 수 | 수십~수천 개 | 거의 0개(할 게 없음) 또는 수만 개(감당 불가) |
| `good first issue` 개수 | 현재 5개 이상 열려있음 | 0개, 혹은 전부 몇 년 전 것 |
| 마지막 푸시 | 며칠 전 | 몇 달 이상 전 |
| 기여자 구성 | 최근 PR 작성자에 외부/개인 다수 포함 | 거의 전부 한 회사 직원 |
| 기능 상태 | 기능 활발히 추가 중 | README에 "유지보수 모드"/"기능 동결" 명시 |

**게이트에 비용을 쓰기 전에 가용성부터 거르세요.** 지금 열려있는 미할당 기여 라벨 이슈가 0건인 레포는 게이트 수치가 아무리 좋아도 오늘 기여를 만들어낼 수 없습니다. 가용성은 라벨당 REST 호출 한 번이면 되지만, 게이트는 여러 호출에 secondary rate limit에 걸리는 검색 쿼리까지 필요합니다. 싼 것부터 확인하고 살아남은 곳만 게이트에 넣으세요.

```bash
curl -s "https://api.github.com/repos/{owner}/{repo}/issues?state=open&labels=good%20first%20issue&per_page=100" \
  | jq '[.[] | select(.pull_request == null) | select(.assignee == null)] | length'
```

`help wanted`와 프로젝트별 라벨(`Contributions wanted!`, `by-<조직>` 등)에도 같은 걸 돌리세요. 후보 레포들에 일괄로 돌려서 0이 아닌 곳만 남기면 됩니다.

이 순서가 같은 날 두 번의 실행을 갈랐습니다. AI/RAG 레포 5곳을 게이트부터 돌렸을 때 `deepset-ai/haystack`과 `run-llama/llama_index`가 깔끔하게 통과했는데, 정작 Phase 3에서 둘 다 잡을 이슈가 하나도 없어서 그 바퀴를 통째로 날렸습니다. 인프라 레포에서 순서를 뒤집으니 싼 스윕 한 번으로 후보 14곳을 걸러 가용성 있는 10곳을 남겼고, 그 다음에야 게이트를 돌렸습니다 — 실제 PR로 이어진 건 이쪽 실행입니다.

가용성은 **지금 어디에 힘을 쓸지의 문제이지 영구 탈락 판정이 아닙니다.** 건강한데 라벨이 빈 레포는 "나중에 다시 오라"는 뜻이므로(체크리스트 Step 8의 빈 라벨 vs 썩은 라벨 참고) 조용히 버리지 말고 그렇게 말해주세요.

**그 다음, 살아남은 레포에 대해 PR 머지 현실 체크를 돌리세요**(`references/repo-evaluation-criteria.md` §3): 90일 이상 방치된 열린 PR 비율과 최근 머지 PR의 외부인 비율. 위 표의 신호들은 프로젝트가 *활발한지*를 재지만, 이 두 개는 외부인의 PR이 실제로 들어가는지를 잽니다 — 다른 질문이고, Phase 3을 돌릴 가치가 있는지를 결정하는 건 이쪽입니다. 매일 푸시하고 분기당 수백 개를 머지하면서도 핵심 팀 바깥 PR은 거의 안 받는 레포가 존재합니다.

두 수치가 모두 경고 구간이면 **실제 수치를 사용자에게 보여주고 이 레포로 계속할지, 대안을 볼지 물어보세요**. 사용자가 결정할 몫입니다 — 임의로 탈락시키지도 말고, 수치가 괜찮은 것처럼 넘어가지도 마세요. 이 체크를 건너뛰면 표면 지표만 멀쩡한 레포가 Phase 2를 통과해버리고, Phase 3을 통째로 소모한 뒤에야 정체가 드러납니다.

3~6개 후보를 표로 비교해서 보여주고, 데이터만 나열하지 말고 명확한 추천을 함께 제시하세요 — 사용자는 결정을 원하지 스프레드시트를 원하는 게 아닙니다.

## Phase 3 — 진짜로 열려있는 이슈 찾기 (다들 여기서 실수함)

레포가 정해지면:

1. good-first-issue 라벨이 붙은 이슈를 **최신순으로, 담당자 없는 것만** 뽑으세요:
   ```
   https://github.com/{owner}/{repo}/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+sort%3Acreated-desc+no%3Aassignee
   ```
   (`web_fetch`로 가져오거나, 검색 API 쿼리에 `+no:assignee+-linked:pr`를 붙이세요 —
   `-linked:pr`가 타임라인 조회를 한 건씩 하기 전에 "이미 선점된" 경우를 1차로 걸러줍니다.
   체크리스트 Step 0 참고)

2. 추천하기 전에 모든 후보 이슈에 대해 `references/issue-triage-checklist.md`의 전체 체크리스트를 따르세요. 요약하면: **본문 전체**를 읽어 내부 전용 공지가 있는지 확인, **Development 섹션**에서 연결된 PR 확인, **Assignees** 확인, 최근 코멘트 2~3개를 읽어 이미 해결됐거나 작업 중이라는 신호가 있는지 확인합니다. 실제 이슈 URL을 `web_fetch`로 열어서 확인하세요 — `updated_at` 타임스탬프만 보고 최신성을 판단하지 마세요. 최근 업데이트가 오히려 "방금 종료 처리됐다"는 신호인 경우가 흔합니다(실제로 사용자가 이걸로 두 번 당했습니다 — 가장 최근 코멘트가 "이거 해결된 것 같아요, PR 곧 닫을게요"였습니다).

   본문 확인은 선택이 아닙니다. 어떤 프로젝트는 큐레이션되지 않은 모든 이슈에 "이 이슈는 내부에서 처리하며 외부 기여를 받지 않는다"는 문구를 자동으로 붙이는데, 검색 결과에는 전혀 보이지 않습니다 — `deepset-ai/haystack`에서 다른 검증을 전부 통과한 이슈 3건이 모두 이 푸터를 달고 있었습니다.

   그리고 살아남은 후보에 대해 **버그가 현재 코드에 아직 있는지 확인하세요**(체크리스트 Step 7). 나머지 검증은 전부 사회적 신호라 버그의 존재를 증명하지 못합니다 — `argoproj/argo-cd#29051`은 8일 전 생성, 미할당, 연결 PR 0건, `severity:critical`이었는데 이미 릴리스로 고쳐진 상태였고 아무도 이슈를 닫지 않았을 뿐이었습니다. 현재 기본 브랜치의 파일을 직접 읽고, 산출물이 구조화된 형식이면 grep 대신 진짜 파서를 쓰세요.

3. 모든 검증을 통과한 이슈만 추천하세요. 아무것도 남지 않았다면 **우회하기 전에 원인부터 진단**하세요 — 기여 라벨을 `state=open`과 `state=all` 양쪽으로 세어봅니다:
   - **썩은 라벨**(열린 게 많고 전부 오래됐고 닫히는 게 없음) + 머지 게이트 실패 → 솔직히 말하고 다른 레포를 추천하세요. 절대 머지되지 않는 백로그 안에서 더 신중히 고르는 건 시간 낭비입니다.
   - **빈 라벨**(열린 건 거의 없는데 닫힌 건 많음) → 레포가 건강하고 이슈가 빨리 처리된다는 뜻입니다. *지금* 비어있을 뿐이에요. 기다릴 가치가 있다고 말하고 라벨을 지켜봐 주겠다고 제안하세요.
   - 어느 쪽이든 README에 링크된 Discord/Slack `#contributing` 채널에 물어볼 만하고, 최근 등록된 자체 완결형 버그 리포트도 확인할 만합니다 — 단 이것들엔 내부 전용 확인을 반드시 다시 돌리세요. 그 공지가 붙는 곳이 정확히 무라벨 이슈들입니다.

4. 살아남은 후보를 스코프가 작고 명확한 순서로 정렬하고, 무엇인지뿐 아니라 왜 시작하기 적당한지도 설명하세요.

## Phase 3.5 — 커뮤니티 아웃리치 & 메시지 초안

이슈 이름만 알려주고 끝내지 마세요 — 사용자가 그대로 복사해서 보낼 수 있는 실제 메시지 초안까지 써주세요.

**커뮤니티 채널 찾기.** `README.md`와 `CONTRIBUTING.md`를 직접 가져와서(예: `raw.githubusercontent.com/{owner}/{repo}/main/README.md`) Discord/Slack 초대 링크, 메일링 리스트, "도움 받는 방법" 섹션이 있는지 확인하세요. 찾은 건 전부 보여주세요 — 활발한 프로젝트 대부분엔 하나씩 있습니다.

**선택한 이슈에 대한 클레임 코멘트 작성.** Phase 3 검증을 통과한 이슈에 대해, 작업 시작 전 의사를 표시하는 짧은 코멘트를 1~2가지 버전으로 작성하세요("캐주얼" vs "계획을 조금 더 구체적으로"). 진짜 짧게 — 한 문단 이내로 유지하세요. 너무 길거나 의욕을 과하게 어필하는 코멘트는 오히려 미숙해 보입니다 — 메인테이너는 이슈가 클레임됐다는 것과 대략 어떻게 할 건지만 알면 됩니다.

**필요할 때 메인테이너/Discord 아웃리치 메시지 작성.** 두 경우에 해당합니다: (a) 검증을 통과한 이슈가 하나도 없을 때(Phase 3의 3번) — 라벨이 썩었든 그냥 비었든, (b) 사용자가 라벨에 없는, 더 크거나 구체적인 이슈를 원할 때. `#contributing` 채널이나 이슈 코멘트용으로 짧고 구체적인 메시지를 쓰세요 — 유용한 답을 받을 만큼 구체적이되(관련 경험/스택 언급, 현재 열려있는 이슈 추천 요청) 장문은 피하세요. "안녕하세요 기여하고 싶은데 뭘 해야 하나요?" 같은 뻔한 문구는 피하세요 — 메인테이너들이 이런 메시지를 너무 많이 봐서 눈에 띄지도, 우선순위가 되지도 않습니다.

**제출 시점의 PR 설명**도 함께 작성하세요 (Phase 4의 5번에서 다시 다룸) — 원칙은 동일합니다: 프로젝트 톤에 맞추고, 실제로 바뀐 것에만 스코프를 맞추세요.

각 메시지 유형의 톤/구조 가이드는 `references/message-templates.md`를 참고하세요.

## Phase 4 — 기여 진행 가이드

사용자가 이슈를 골랐다면 GitHub CLI(`gh`) 기반 워크플로로 안내하세요. `gh`를 쓰면 개인 액세스 토큰(PAT)을 직접 만들 필요도, `git remote`를 손으로 맞출 필요도 없습니다.

1. **인증 확인:** 사용자에게 `gh auth status`를 실행하게 하세요. 로그인이 안 돼 있거나 스코프가 부족하면 `gh auth login --scopes workflow`를 실행하고 안내를 따르게 하세요(웹 브라우저 옵션이 가장 쉽습니다). 클론 중 SSH 호스트 키 오류가 나면 `gh config set git_protocol https`를 알려주세요.
2. **포크 & 클론 자동화:** 수동 클론 대신 `gh repo fork {owner}/{repo} --clone`을 실행하게 하세요. 이 한 줄로 포크 생성, 로컬 클론, `origin`/`upstream` 리모트 설정이 한 번에 끝납니다.

   클론 단계가 SSH 호스트 키 오류로 실패하면(그리고 `gh config set git_protocol https`도 설정 파일을 못 쓴다면) 포크는 이미 생성돼 있습니다 — 포크를 HTTPS로 명시적으로 클론해서 복구하세요: `git clone https://github.com/{user}/{repo}.git` 후 `git remote add upstream https://github.com/{owner}/{repo}.git`.

   **먼저 `df -h`로 확인하세요.** Grafana 같은 모노레포는 클론과 설치에 수 GB가 필요하고, 사용자의 디스크를 채우는 건 어떤 체크리스트 항목보다 나쁩니다. 공간이나 시간이 안 되고 변경이 작다면 클론을 아예 건너뛸 수 있습니다: `raw.githubusercontent.com`에서 해당 파일만 받아 로컬에서 수정하고 API로 커밋하세요 — 단 REST Contents API가 아니라 GraphQL `createCommitOnBranch`를 쓰세요. 일부 레포가 요구하는 `Verified` 커밋은 후자로만 만들어집니다. `references/pr-acceptance-checklist.md` §4b를 참고하고, 돌리지 못한 테스트는 PR에 분명히 밝히세요.
3. `CONTRIBUTING.md`와 `README.md`를 먼저 읽으세요 — 프로젝트마다 브랜치 명명 규칙, 커밋 메시지 포맷, 필수 테스트, DCO/CLA 서명 등 관례가 조금씩 다릅니다. **`CONTRIBUTING.md`가 껍데기면 링크를 따라가세요.** Directus의 것은 문서 사이트를 가리키는 3줄이고, 구속력 있는 내용(CLA 방식, 필수 changeset, 과거형 설명 규칙)은 레포가 아니라 그쪽에 있습니다.
4. 이슈와 직접 관련된 파일만 정확히 찾으세요 — 코드베이스 전체를 설명하려 하지 말고 필요한 범위로 좁히세요.
5. 수정안을 작성한 뒤, **diff를 한 줄씩 사용자에게 설명**하세요 — 둘 다 완전히 이해하지 못한 걸 그냥 제출하게 하지 마세요. 리뷰어는 티가 나고, 다음 기여에 대한 신뢰에도 영향을 줍니다.
6. PR을 제안하기 전에 프로젝트의 실제 테스트 스위트를 로컬에서 돌리세요(`CONTRIBUTING.md` 기준 — pytest, jest, cargo test 등 프로젝트마다 다름).
7. 변경사항을 커밋하고 포크 브랜치에 푸시하세요.

## Phase 4.5 — PR 제출 전 품질 점검

`gh pr create`를 실행하기 전에 **반드시** `references/pr-acceptance-checklist.md`를 읽고 그대로 적용하세요.

1. **할당 확인 (필수):** `gh issue view <이슈번호>`로 사용자가 공식 할당됐는지 확인하세요. 할당되지 않았다면 PR을 만들지 마세요 — 봇이 자동으로 닫아버립니다.
2. **테스트 & 린트:** 로컬 테스트와 린터(`CONTRIBUTING.md` 기준)를 모두 실행해 통과했는지 확인하세요.
3. **커밋 관례:** 레포의 기존 히스토리와 다르면 커밋 메시지를 다시 쓰고(예: Conventional Commits), DCO가 필요하면 서명(`git commit -s`)하세요.
4. **PR 템플릿:** `.github/PULL_REQUEST_TEMPLATE.md`가 있으면 PR 본문에 그 템플릿을 그대로 사용하세요.

## Phase 5 — PR 제출과 후속 대응

1. **PR 생성:** 프로젝트 스타일에 맞춰 작성한 제목과 설명으로 `gh pr create --title "..." --body "..."`를 실행하게 하세요. 제출 전 사용자가 직접 최종 검토하게 하세요 — 최종 작성자는 AI가 아니라 사용자입니다.

   어떤 유명 레포는 신규 계정의 PR을 조용히 차단합니다(안티스팸): 포크와 브랜치가 존재하는데도 `gh pr create`가 권한 오류를 내고 REST 엔드포인트는 404를 반환합니다. 이슈 작성자도 "차단됐다"고 언급했다면 우회하려 하지 말고 다른 레포를 고르세요.
2. **맞는 사람에게 갔는지 확인하되, 대개 "그렇다"가 정답입니다.** `.github/CODEOWNERS`에서 소유 팀을 확인하되, 리뷰어 목록만 보고 라우팅 공백이라 단정하지 마세요 — 많은 조직이 팀 요청을 그 팀 개인들로 치환하고, 그건 잘못 라우팅된 것과 겉보기가 같습니다. 타임라인의 `review_requested` / `review_request_removed` 이벤트를 보세요. `grafana/grafana#130614`은 개인 4명에 팀이 없어서 소유 스쿼드가 누락된 것처럼 보였지만, 타임라인은 CODEOWNERS로 `sharing-squad`가 자동 요청됐다가 그 팀 멤버들로 치환된 것을 보여줬습니다. 파일이 정말로 어느 규칙에도 매칭되지 않을 때만 — 잘린 검색이 아니라 항목을 직접 읽어 확인한 뒤에 — 공백을 알리세요.
3. **이슈 스레드에 PR이 올라갔다고 알리세요.** 이슈 구독자가 내 포크의 PR까지 자동으로 따라오지는 않습니다.
4. **그리고 기다리세요.** 큰 레포에서 1~2주 침묵은 정상이고, 외부 PR의 CI가 승인 대기로 멈춰 있는 것도 방치의 증거가 아닙니다. 재촉이 필요하면 새 정보를 담은 코멘트 **한 번**이지("rebased, CI green"), 맨몸의 "any update?"는 안 됩니다. 문구와 역효과 나는 안티패턴은 `references/message-templates.md` §4~6에 있습니다.
5. 메인테이너의 리뷰 피드백이 오면 빠르게 반영하되, *왜* 바뀌는지 사용자가 계속 이해하게 하세요 — 제안을 그냥 그대로 적용하지 마세요.

## 이 스킬을 계속 발전시키는 것에 대해

이 스킬은 반복적으로 사용하면서 실제로 겪은 일(빠져나간 죽은 이슈, 수치보다 실제로는 안 맞았던 레포, 어디에도 문서화되지 않은 PR 관례)을 바탕으로 계속 다듬어가는 걸 전제로 합니다. 실제 기여 시도에서 이 스킬이 예측한 것과 다른 일이 생기면, 그건 체크리스트나 채점 기준을 업데이트해야 한다는 신호입니다 — 일회성 해프닝으로 넘기지 말고 다시 반영하세요.