---
name: vibe-init
description: 사용자가 vibe-coding 설정을 만들거나 변경해 달라고 요청할 때 이슈 트래커, 트리아지 라벨 어휘, 도메인 문서 구조를 `AGENTS.md`와 설정 문서에 기록한다. 설정 파일이 없다는 이유만으로 실행하지 않으며, 다른 스킬은 로컬 Markdown 기본값으로 진행할 수 있다.
disable-model-invocation: true
---

# 바이브 초기화

**한국어 저장소 글:** 한국어 문서, 커밋 메시지, 이슈, PR, 리뷰 또는 댓글의 초안을 쓰기 전에 설치된 `vibe-docs` 스킬을 읽고 그 `필수 적용 순서`를 따른다. `vibe-docs`는 표현만 다루며 이 스킬의 권한이나 외부 변경 범위를 넓히지 않는다.

사용자가 요청한 저장소별 설정의 초안을 작성한다. 다른 스킬을 사용하기 위한 필수 선행 작업은 아니다. 설정 파일이 없을 때의 동작은 [설정 문서와 기본값](references/defaults.md)을 따르며, 사용자가 초기화를 요청하지 않았다면 이 스킬의 설정 작성 절차를 시작하지 않는다.

- **이슈 트래커**: 이슈를 관리하는 곳(미설정 기본값은 로컬 Markdown이며, 명시적 초기화에서는 사용자가 선택한 트래커를 기록)
- **트리아지 라벨**: 다섯 정규 트리아지 역할에 쓰는 문자열(기본 한국어)
- **도메인 문서**: `CONTEXT.md`와 아키텍처 결정 기록(ADR)을 저장하는 곳, 그리고 읽는 규칙

이 스킬은 모든 설정을 `AGENTS.md`에만 기록한다. `CLAUDE.md`나 다른 에이전트 지시 파일은 읽거나 쓰지 않는다. 그런 파일이 있어도 마찬가지다.

이것은 프롬프트 구동 스킬이지 결정적 스크립트가 아니다. 탐색하고 발견한 것을 제시한다. 사용자와 확인한 뒤 기록한다.

## 과정

### 1. 탐색

이 저장소를 살펴 출발 상태를 파악한다. 있는 것을 읽는다. 가정하지 않는다:

- `git remote -v`와 `.git/config`: GitHub 저장소인가? 어느 저장소인가?
- `git status --short`: 이 실행 전에 이미 있던 변경은 무엇인가? 나중에 이 스킬의 변경과 섞지 않도록 정확한 경로를 기록한다.
- 현재 브랜치와 upstream의 차이: 원격 트래커를 사용할 때 어느 브랜치를 push해야 하는가? 이 실행 전에 이미 push되지 않은 커밋이 있는가?
- 저장소 루트의 `AGENTS.md`: 있는가? 이미 `## Agent skills` 섹션이 있는가?
- 저장소 루트의 `CONTEXT.md`와 `CONTEXT-MAP.md`
- `docs/adr/`과 `src/*/docs/adr/` 디렉터리
- `docs/agents/`: 이 스킬의 이전 출력이 이미 있는가?
- `.agents/plans/`: 로컬 마크다운을 이슈 트래커로 쓰는 관행이 이미 있다는 신호
- `docs/agents/out-of-scope/`(또는 기존 `.agents/out-of-scope/`): 거부된 요청 지식베이스가 이미 쓰이고 있다는 신호
- `vibe-plan` / `vibe-deep-plan`이 설치되어 있는가? (이 스킬 폴더 옆의 스킬 폴더, 또는 사용할 수 있는 스킬 목록의 이름). 이들은 라벨 어휘를 사용한다. 둘 다 계획 유형을 사용한다. `vibe-plan`은 트리아지 상태를, `vibe-deep-plan`은 결정 맵 상태와 결정 유형을 사용한다. 따라서 설치 여부가 B절의 실행을 결정한다.
- 모노레포 신호: `pnpm-workspace.yaml`, `package.json`의 `workspaces` 필드, 또는 자체 `src/`를 가진 채워진 `packages/*`. 패키지가 둘 이상이고 규모가 큰 저장소에서만 다중 컨텍스트를 제시한다. 신호가 없으면 단일 컨텍스트이고, 대부분의 저장소가 여기에 속한다.

### 2. 발견한 것을 제시하고 묻기

있는 것과 빠진 것을 요약한다. 그다음 절을 순서대로 제시한다. 한 번에 한 절씩 묻고 답을 받은 뒤 다음 절로 간다.

각 절의 권장 답을 먼저 제시한다. 사용자는 한 단어로 답할 수 있다. 선택지가 둘 이상 있을 때만 한 줄 설명을 붙인다. 탐색에서 이미 답이 나온 절은 건너뛴다. 예를 들어 트리아지가 설치되지 않았으면 B절을 건너뛰고, 모노레포가 아니면 C절을 건너뛴다.

**A절: 이슈 트래커.**

> 설명: "이슈 트래커"는 이 저장소의 이슈를 관리하는 곳이다. `vibe-plan`과 `vibe-review` 같은 스킬은 여기서 읽고 쓴다: `gg issue create`를 호출할지, `.agents/plans/` 아래 마크다운 파일을 작성할지, 또는 사용자가 설명하는 다른 워크플로를 따를지 알아야 한다. 이 저장소에서 실제로 작업을 추적하는 곳을 고른다.

기본 제안: 이 스킬들은 GitHub에 맞춰 설계되었다. `git remote`가 GitHub을 가리키면 그것을 제안한다. `git remote`가 GitLab(`gitlab.com` 또는 자체 호스트)을 가리키면 GitLab을 제안한다. 그 밖의 경우(또는 사용자가 원하면) 다음을 제시한다:

- **GitHub**: 이슈를 저장소의 GitHub Issues에서 관리한다(`gg` CLI 사용)
- **GitLab**: 이슈를 저장소의 GitLab Issues에서 관리한다(`gg` CLI 사용)
- **로컬 마크다운**: 이슈를 이 저장소의 `.agents/plans/<feature>/` 아래 파일로 관리한다(개인 프로젝트나 리모트 없는 저장소에 적합)
- **기타**(예: Jira, Linear): 사용자에게 워크플로를 한 단락으로 설명해 달라고 한다. 스킬이 자유 형식 글로 기록한다

선택을 `docs/agents/issue-tracker.md`에 기록한다. GitHub과 GitLab 템플릿에는 "PR을 요청 표면으로"(PR을 기능 요청으로 취급하는지 정하는 설정) 플래그가 있으며, 기본값은 **꺼짐**이다. 꺼진 채로 두고 언급하지 않는다. 트리아지 대기열에 외부 PR을 원하는 사용자는 나중에 파일에서 플래그를 켤 수 있다.

**B절: 라벨 어휘.** `vibe-plan`과 `vibe-deep-plan`이 둘 다 설치되어 있지 않으면(탐색이 알려준다) 이 절 전체를 건너뛴다. 두 스킬 중 라벨을 사용하는 스킬이 없기 때문이다.

둘 중 하나라도 설치되어 있으면 정확히 한 질문만 한다:

> 기본 라벨을 유지하시겠습니까? (권장: **예**)

기본값은 한국어 라벨이다. 각 축에 접두사를 붙인다:

- **트리아지 상태**(`vibe-plan`): `상태:분류필요` (needs-triage), `상태:정보필요` (needs-info), `상태:에이전트작업` (ready-for-agent), `상태:사람작업` (ready-for-human), `상태:처리안함` (wontfix)
- **계획 유형**(`vibe-plan` 또는 `vibe-deep-plan`): 호스트형 명세 이슈와 계획 이슈, 결정 맵에 쓰는 `유형:계획`
- **결정 지도 라벨**(`vibe-deep-plan`): 결정 맵 상태용 `상태:초안`, 그리고 네 결정 티켓 유형용 `유형:조사` / `유형:프로토타입` / `유형:인터뷰` / `유형:작업`

설치된 스킬의 계열만 작성한다. **예**이면 그대로 작성한다. 사용자가 기본 라벨을 거부할 때만 재정의를 모아 기존 라벨을 적용한다. 이는 보통 트래커가 이미 다른 이름을 쓰기 때문이다(예: needs-triage를 `bug:triage`). 중복을 만들지 않는다.

**C절: 도메인 문서.** 단일 컨텍스트를 기본으로 삼는다. 저장소 루트에 하나의 `CONTEXT.md`와 `docs/adr/`를 둔다. 이 구조는 일반적인 저장소에 맞는다. 묻지 않고 기록한다.

탐색에서 모노레포 신호를 찾았을 때만 다중 컨텍스트 구조를 제시한다. 이 구조에서는 루트 `CONTEXT-MAP.md`가 컨텍스트별 `CONTEXT.md` 파일을 가리킨다. 그다음 사용자가 원하는 구조를 확인한다.

### 3. 확인하고 편집하기

사용자에게 다음의 초안을 보여준다:

- `AGENTS.md`에 추가할 `## Agent skills` 블록
- `docs/agents/issue-tracker.md`, `docs/agents/domain.md`, `docs/agents/triage-labels.md`의 내용(마지막은 계획 스킬이 설치되어 있을 때만)

기록 전에 편집하게 한다.

### 4. 기록하기

`AGENTS.md`가 있으면 편집하고, 없으면 만든다. 절대 `CLAUDE.md`를 편집하지 않는다. `CLAUDE.md`만 있어도 새 `AGENTS.md`를 만들고 `CLAUDE.md`는 그대로 둔다.

`AGENTS.md`에 이미 `## Agent skills` 블록이 있으면 중복을 추가하는 대신 내용을 제자리에서 갱신한다. 주변 섹션의 사용자 편집은 덮어쓰지 않는다.

**`.gitignore`**: 저장소가 git을 쓰면 에이전트 스크래치 경로를 무시하도록 `.agents/worktrees/`와 `.agents/prototype/`을 `.gitignore`에 추가한다. 이미 무시하는 경로는 추가하지 않고, 파일이 없으면 만든다. **로컬 마크다운** 트래커에서는 스킬이 티켓의 체크리스트를 구현 커밋에 함께 커밋하고, 무시된 파일은 커밋할 수 없다. 그래서 `.agents/plans/`는 **추적**해야 하고 스크래치 경로만 무시한다. `.agents/`를 통째로 무시하면 뒤에 `!` 패턴을 써도 그 안의 파일을 다시 포함할 수 없으므로 `.agents/*`와 `!.agents/plans/`로 바꾼다. 다른 트래커에서는 `.agents/` 전체를 무시해도 좋다.

블록:

```markdown
## Agent skills

### Korean repository text

한국어 문서, 커밋 메시지, 이슈, PR, 리뷰 또는 댓글의 초안을 쓰기 전에 설치된 `vibe-docs` 스킬을 읽고 `필수 적용 순서`를 따른다. `CONTEXT.md`, 이 글의 주제를 다루는 ADR, `docs/agents/`에 정의된 도메인 용어와 라벨 문자열은 원래 표기를 그대로 유지한다.

### Issue tracker

[이슈가 어디서 추적되는지 한 줄 요약]. 자세한 내용은 `docs/agents/issue-tracker.md`를 읽는다.

### Triage labels

[라벨 어휘 한 줄 요약]. 자세한 내용은 `docs/agents/triage-labels.md`를 읽는다.

### Domain docs

[구조 요약: "단일 컨텍스트" 또는 "다중 컨텍스트"]. 자세한 내용은 `docs/agents/domain.md`를 읽는다.
```

계획 스킬이 설치되어 있고 B절이 실행되었을 때만 `### Triage labels` 하위 블록을 포함하고 `docs/agents/triage-labels.md`를 작성한다. 그렇지 않을 때는 둘 다 생략한다.

그다음 이 스킬 폴더에 있는 초안 양식을 바탕으로 문서 파일을 작성한다:

- [issue-tracker-github.md](references/issue-tracker-github.md): GitHub 이슈 트래커
- [issue-tracker-gitlab.md](references/issue-tracker-gitlab.md): GitLab 이슈 트래커
- [issue-tracker-local.md](references/issue-tracker-local.md): 로컬 마크다운으로 이슈를 관리하는 트래커
- [triage-labels.md](references/triage-labels.md): 라벨 매핑(계획 스킬이 설치되어 있을 때만)
- [domain.md](references/domain.md): 도메인 문서의 구조와 사용 규칙

"기타" 이슈 트래커를 선택하면 사용자의 설명을 바탕으로 `docs/agents/issue-tracker.md`를 처음부터 작성한다. 이 문서에는 초안 양식과 같이 한국어로 쓰는 규칙과 도메인 용어를 보호하는 규칙을 포함한다.

### 5. 커밋하기

Git 저장소이고 이 실행이 파일을 바꿨으면, 다음 원격 변경이나 다음 작업으로 넘어가기 전에 이 스킬의 변경을 커밋한다.

1. `git diff`로 결과를 확인한다. 탐색 때 이미 있던 변경은 이 스킬의 변경으로 보지 않는다.
2. `git add .`이나 넓은 경로를 쓰지 않고, 이 실행에서 만든 또는 바꾼 정확한 파일만 stage한다.
3. 대상 파일에 기존 사용자 변경이 섞이면 이 실행의 hunk만 안전하게 stage할 수 있는지 확인한다.
4. 안전하게 stage할 수 있으면 이 실행의 hunk만 stage한다.
5. 안전하게 나눌 수 없으면 커밋하지 않는다.
6. 안전하게 나눌 수 없으면 충돌한 경로를 사용자에게 알린다.
7. 안전하게 나눌 수 없으면 사용자에게 묻는다.
8. staged diff가 이 실행의 설정 변경만 담는지 확인한다.
9. 저장소의 기존 형식에 맞는 한 개의 커밋을 만든다.
10. 커밋 SHA를 확인한다. 커밋이나 확인이 실패하면 멈춘다.
11. 탐색 때부터 push되지 않은 기존 커밋이 있으면 자동으로 push하지 않는다.
12. 그 경우 이 스킬의 push가 기존 커밋도 함께 게시한다는 사실과 포함될 커밋을 사용자에게 보여준다.
13. 그 경우 사용자에게 push해도 되는지 묻는다.
14. GitHub, GitLab 또는 다른 원격 트래커를 사용하면 현재 브랜치를 일반 push한다. force push는 하지 않는다.
15. 원격 브랜치에 커밋 SHA가 있는지 확인한다. 라벨이나 이슈는 이 확인 뒤에 등록한다.

변경할 파일이 없거나 Git 저장소가 아니면 커밋을 만들지 말고 그 이유를 알린다. 필수 push나 원격 SHA 확인이 실패하면 GitHub이나 GitLab에서 라벨을 만들거나 수정하거나 다른 이슈 트래커를 변경하지 않는다.

### 6. 완료

설정이 끝나면 사용자에게 알린다. 어느 엔지니어링 스킬이 설정 문서를 읽는지도 알린다. 나중에 `docs/agents/*.md`를 직접 편집할 수 있다고 안내한다. 이슈 트래커를 바꾸거나 처음부터 다시 시작할 때만 이 스킬을 다시 실행하면 된다고 알려 준다.