ZenHub 컨벤션#

한마디로 (비개발자용)#

ZenHub는 할 일(이슈)을 카드처럼 관리하는 작업 보드입니다. 이 문서는 그 보드에 카드를 만들 때 지켜야 할 "집안 규칙"을 모아 둔 약속집이에요. 예를 들어 "큰 목표는 빨간 카드, 작은 일은 파란 카드"처럼, 카드를 어떤 종류로·어떤 이름으로·어디에 붙일지를 통일해 두는 것입니다. 덕분에 사람도 AI도 헷갈리지 않고 같은 방식으로 일을 정리할 수 있습니다.

무엇을·언제 (비개발자용)#

• 무엇을 해 주나요: 새 작업 카드(이슈)를 만들 때 올바른 종류·이름·연결 방식을 자동으로 지키게 해 줍니다.
• 큰 일과 작은 일을 부모-자식으로 묶어, 전체 그림(Epic) 아래에 세부 작업(Story)이 매달리도록 정리합니다.
• 일정(시작일·종료일)과 작업량 점수(Story Point)를 정해진 자리에 채워 넣습니다.
• 언제 작동하나요: ZenHub에 이슈를 새로 만들거나, 작업을 단계별 보드(파이프라인)로 옮기거나, 작업 분량을 추정할 때 이 규칙이 기준이 됩니다.
• 핵심 약속 하나: 이슈는 항상 GitHub 이슈로 만들고, ZenHub 이슈는 쓰지 않습니다(일정·이동 기능이 제대로 동작하기 때문).

핵심 용어 (비개발자용)#

ZenHub를 사용한 이슈 관리 규칙입니다.

⚠️ 단일 출처(Source of Truth): 이슈 생성·타입 계층·파이프라인 배치·종료 정책의 상세 규칙은 rules/zenhub-conventions.md에 있습니다. 이 SKILL은 그 요약이며, 두 문서가 다르면 rules/zenhub-conventions.md가 우선합니다. 브랜치 전략은 branch-hierarchy 스킬을 참조하세요.

이슈 생성 규칙#

GitHub 이슈 사용 (필수)#

모든 이슈는 GitHub 이슈로 생성합니다 (ZenHub 이슈 사용 금지)

// ✅ CORRECT: GitHub 이슈 생성 (ID는 항상 동적 조회 — 워크스페이스마다 다르므로 하드코딩 금지)
const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
const repoId = workspace.githubRepositories.find(r = >   /* 대상 GitHub 레포 선택 */).id;
const issueTypes = await mcp__zenhub__getIssueTypes({ repositoryId: repoId });
const epicTypeId = issueTypes.find(t = >   t.name ===  " Epic " ).id;

mcp__zenhub__createGitHubIssue({
  title:  " 기능 개발 " , // Issue Type이 Epic/Story를 이미 구분하므로 접두사 불필요
  repositoryId: repoId,
  issueTypeId: epicTypeId,
})

// ❌ WRONG: ZenHub 이슈 생성 (사용 금지)
mcp__zenhub__createZenhubIssue({...})

이유:

• GitHub 이슈는 파이프라인 이동 가능
• 타임라인 설정 정상 작동
• GitHub PR과 자동 연결
• 검색 및 필터링 용이

Issue Type 계층 (5-레벨)#

Repository ID, Issue Type ID, Pipeline ID, Organization ID는 워크스페이스마다 다르므로 항상 getWorkspacePipelinesAndRepositories() / getIssueTypes()로 동적 조회합니다(하드코딩 금지). 레벨(숫자가 작을수록 상위) 구조는 다음과 같습니다:

Initiative/Project 타입은 워크스페이스에 없을 수 있으므로 getIssueTypes()로 먼저 확인하고, 없으면 그 아래 레벨을 최상위로 대체하며 사용자에게 안내합니다.

이슈 생성 예시 (동적 조회 기반)#

Epic 생성#

const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
const repoId = workspace.githubRepositories.find(r = >   /* 대상 레포 선택 */).id;
const issueTypes = await mcp__zenhub__getIssueTypes({ repositoryId: repoId });
const epicTypeId = issueTypes.find(t = >   t.name ===  " Epic " ).id;

// 1. Epic 생성 (GitHub 이슈)
const epic = await mcp__zenhub__createGitHubIssue({
  title:  " 기능명 " ,
  body:  " Epic 설명... " ,
  repositoryId: repoId,
  issueTypeId: epicTypeId,
});

// 2. 타임라인 설정
await mcp__zenhub__setDatesForIssue({
  issueId: epic.id,
  startDate:  " 2026-01-27 " ,
  endDate:  " 2026-02-17 " ,
  zenhubOrganizationId: workspace.zenhubOrganization.id,
});

// 3. 파이프라인 이동
const backlog = workspace.pipelines.find(p = >   p.name ===  " Product Backlog " );
await mcp__zenhub__moveIssueToPipeline({
  issueId: epic.id,
  pipelineId: backlog.id,
});

Story 생성#

const featureTypeId = issueTypes.find(t = >   t.name ===  " Feature " ).id;

// Story 생성 (Epic 하위)
const story = await mcp__zenhub__createGitHubIssue({
  title:  " 기능명 " , // Issue Type(Feature)이 Story임을 이미 구분하므로 접두사 불필요
  body:  " Story 설명... " ,
  repositoryId: repoId,
  issueTypeId: featureTypeId,
  parentIssueId: epic.id, // Epic과 연결
});

// Story Point 설정
await mcp__zenhub__setIssueEstimate({
  issueId: story.id,
  estimate: 5,
});

Project/Initiative 생성, 우선순위 라벨(p0/p1/p2), 파이프라인 배치 매트릭스 등 상세 규칙은 rules/zenhub-conventions.md를 참조하세요.

이슈 제목 컨벤션#

Issue Type(Epic/Story/Sub-task 등)이 이미 종류를 구분하므로, 제목에 [Epic]/[Story] 같은 접두사를 붙이지 않습니다.

참고 사항#

1. ZenHub 이슈 vs GitHub 이슈

   • ZenHub 이슈: 파이프라인 이동/타임라인 설정 불가
   • GitHub 이슈: 모든 ZenHub 기능 정상 작동

2. 부모-자식 관계

   • parentIssueId 파라미터로 생성 시 연결
   • 또는 setParentForIssues로 나중에 연결
   • 자식의 Issue Type level은 부모보다 커야 합니다 (예: Epic(3) 아래 Story(4) ✅)

3. 검색

   • searchLatestIssues: GitHub 이슈만 검색됨
   • ZenHub 이슈는 검색 불가

4. 브랜치 계층 정책 (#5424)

   • 이슈 type이 Epic이거나 parent가 있는 경우 계층 브랜치를 사용해야 합니다
   • 구체적인 prefix·base 브랜치 규칙은 branch-hierarchy 스킬을 단일 출처로 참조하세요(이 문서에서 중복 서술하지 않습니다 — drift 방지)