명세서에서 티켓까지: Node.js와 Jira API를 활용한 Jira 설정 자동화

계획은 간단했습니다

우리가 작성한 명세서(specs)를 가져와서 이를 Jira의 에픽(epics), 스토리(stories), 하위 작업(subtasks)으로 변환한 뒤, 바로 스프린트(sprinting)를 시작하는 것이었습니다.

예상보다 오래 걸렸습니다. 실제로 어떤 일이 일어났는지, 그리고 제가 무엇을 배웠는지 공유합니다.

왜 Jira 설정을 자동화해야 할까요?

HandyFEM에는 8개의 에픽, 37개의 스토리, 그리고 약 160개의 하위 작업이 있습니다. 이를 수동으로 생성하려면 하루 종일 걸릴 것이며 오류가 발생할 가능성도 높습니다. 더 중요한 점은, 명세서가 이미 구조화된 형식(structured format)으로 작성되어 있었다는 것입니다. 구조화된 데이터를 Jira 이슈로 변환하는 것은 정확히 자동화되어야 할 반복적인 작업의 전형입니다.

그래서 저는 Jira REST API를 통해 이를 수행할 Node.js 스크립트를 작성했습니다.

문제 1 — Jira Spaces ≠ Jira Classic

제 계정은 Atlassian의 새로운 인터페이스인 Jira Spaces를 사용합니다. 클래식 Jira(Jira Classic)에는 CSV 가져오기 기능이 내장되어 있지만, Jira Spaces에는 없습니다.

이 내용은 어디에도 명시적으로 문서화되어 있지 않습니다. 가져오기 옵션을 찾으려는데 보이지 않는다는 것을 깨달으면서 직접 알게 되는 부분입니다.

교훈: 워크플로(workflow)를 계획하기 전에 항상 사용 중인 Jira 버전을 확인하세요. API는 여전히 작동하지만, 일부 엔드포인트(endpoints)는 다르게 동작할 수 있습니다.

문제 2 — API 토큰이 문제가 아니었습니다 (그전까지는)

첫 번째 시도: 연결 오류(connection error)가 발생했습니다. 저는 토큰 문제라고 가정했습니다. 하지만 아니었습니다. 이전 세션에서 만료된 토큰이 문제였습니다. 토큰을 다시 생성하니 연결 문제가 해결되었습니다.

진정한 교훈: curl -u email:token https://your-domain.atlassian.net/rest/api/3/myself 명령어를 사용하는 것이 스크립트를 실행하기 전 인증(auth)을 확인하는 가장 빠른 방법입니다.

문제 3 — 팀 관리 프로젝트(team-managed projects)에는 customfield_10014가 존재하지 않습니다

클래식 Jira에서는 스토리를 에픽에 연결할 때 customfield_10014(Epic Link)라는 필드를 사용합니다. 하지만 팀 관리 프로젝트(Jira Spaces)에서는 이 필드가 존재하지 않습니다. 대신 parent를 사용해야 합니다.

오류 메시지를 확인하자 원인이 명확해졌습니다:

"customfield_10014": "Field cannot be set. It is not on the appropriate screen, or unknown."

해결 방법: customfield_10014를 제거하고 parent: { id: epicId }만 남깁니다.

문제 4 — 팀 관리 프로젝트에서는 보드 검색이 작동하지 않습니다

Agile API 엔드포인트인 /rest/agile/1.0/board?projectKeyOrId=HFM은 보드가 존재하더라도 팀 관리형 프로젝트 (team-managed projects)의 경우 빈 값을 반환합니다.

Claude Code는 첫 번째 실패 이후 이 문제를 포착했습니다. Claude Code는 근본 원인과 해결 방법을 설명했습니다. 즉, 보드를 검색하는 대신 보드 ID (board ID)를 직접 하드코딩하는 것입니다.

// 팀 관리형 프로젝트에서는 작동하지 않습니다:
const boards = await fetch(`/rest/agile/1.0/board?projectKeyOrId=HFM`)

...

최종 설정의 모습

프로젝트 전체 라이프사이클을 아우르는 8개의 에픽 (epics):

• 기획 및 아키텍처 (완료)
• 디자인 시스템 (Design System) (진행 중)
• MVP 화면 (진행 중)
• 백엔드 (Backend) / Supabase
• 보안 및 개인정보 보호 (Security & privacy)
• PWA + SEO + 이메일
• 테스트 및 출시
• AI 에이전트 기능 (AI Agentic features) (v2)

상세한 설명과 수락 기준 (acceptance criteria)이 포함된 37개의 스토리 (stories).

스토리당 약 160개의 하위 작업 (subtasks) — 스토리를 종료하기 전 블로그 포스트를 작성하는 작업도 포함됩니다. 마지막 작업이 중요한 이유는, 작업 바로 옆에 존재하는 문서는 작성되지만, 별도로 계획된 문서는 작성되지 않기 때문입니다.

디자인 시스템 (DS) 구현부터 바르셀로나에서의 공개 출시까지, 논리적인 빌드 순서에 맞춰 매핑된 8개의 스프린트 (sprints).

보안: 토큰을 절대 하드코딩하지 마세요

스크립트는 자격 증명 (credentials)을 로드하기 위해 node --env-file=.env.local (Node v18+부터 기본 지원)을 사용합니다. dotenv 의존성도 없고, 코드베이스에 토큰도 남지 않습니다.

node --env-file=.env.local docs/handyfem-jira-import.js

두 스크립트 모두 .gitignore에 포함되어 있습니다. Claude Code에는 민감한 값을 직접 작성하지 말고, 개발자가 수동으로 추가할 수 있도록 항상 지침을 제공하도록 지시했습니다.

다르게 했을 점

전체 스크립트를 작성하기 전에 간단한 API 테스트부터 시작했을 것입니다. 인증 (auth)을 확인하기 위한 curl 호출 한 번과 프로젝트 엔드포인트를 확인하기 위한 호출 한 번만 있었어도 30분의 디버깅 시간과 많은 Claude 토큰을 아낄 수 있었을 것입니다.

또한, Jira를 자동화할 때는 항상 프로젝트가 클래식 (classic)인지 팀 관리형 (team-managed)인지 먼저 확인해야 합니다. API 노출 범위 (API surface)가 유의미할 정도로 다르기 때문입니다.

스크립트

두 스크립트 모두 HandyFEM 리포지토리의 docs/ 디렉토리에 있습니다:

• handyfem-jira-import.js — 에픽 (Epics), 스토리 (Stories), 하위 작업 (Subtasks) 생성
• handyfem-jira-sprints.js — 스프린트 (Sprints) 생성 및 이슈 (Issues) 할당

📚 HandyFEM App 시리즈
🔗 이전 글: Claude.ai를 활용한 HandyFEM 디자인 시스템 구축
🔗 다음 글: 곧 공개 예정 — Claude Code를 활용한 코드 기반 디자인 시스템 구축
🏷️ 이 시리즈의 모든 포스트: #HandyFEMApp

공개적으로 구축 중입니다. 모든 실수가 포함되어 있습니다.