Linear 이슈를 Markdown으로 내보내기

Linear는 빠르고 고집이 뚜렷합니다. 엔지니어링 팀이 원하는 바로 그 모습이죠. 동시에 조직의 지식이 어마어마하게 쌓이는 곳이기도 합니다. 버그 재현 절차, 설계 결정, 회고, 고객 제보 같은 것들 말입니다. 그 내용을 Markdown으로 꺼내면 AI 워크플로와 문서 생성, 아카이브가 열립니다.

이 가이드는 Linear의 콘텐츠를 내보내는 현실적인 방법을 모두 다룹니다.

왜 Linear를 Markdown으로 내보내야 할까요?

AI를 곁들인 분류 — 최근 이슈들을 Claude나 ChatGPT에 넘기고 “반복되는 주제가 뭐야?”라고 물어보세요
닫힌 이슈로 릴리스 노트 만들기 — Linear의 기본 “Build changelog”도 훌륭하지만 유연하지 않습니다. Markdown이면 원하는 대로 조합할 수 있습니다
사후 분석 — 장애 이슈와 연결된 상위/하위 이슈를 하나의 Markdown 문서로 모아 회고에 씁니다
RAG 지식 베이스 — 닫힌 이슈를 벡터 스토어에 넣어 두면, 앞으로 생길 장애에서 과거의 비슷한 사례가 떠오릅니다
포트폴리오 리뷰 — 이해관계자 보고를 위해 한 프로젝트의 이슈를 파일 하나로 내보냅니다
백업 — Linear에 문제가 생겨도 무엇이든 복원할 수 있다는 사실은 잠자리를 편하게 합니다

방법 1: Minibase Chrome 확장 프로그램 (이슈 1~20개에 가장 빠름)

Minibase는 Linear의 이슈나 프로젝트, 문서 페이지를 클릭 한 번으로 깔끔한 Markdown으로 바꿉니다.

Minibase가 Linear에서 담아내는 것:

이슈 제목, 상태, 우선순위, 담당자, 사이클, 프로젝트
제목과 코드 블록, 목록, 삽입된 첨부까지 포함한 설명 본문 전체
라벨과 마감일을 프런트매터로
댓글별 작성자와 타임스탬프가 붙은, 작성 순서대로의 댓글 스레드
인라인 반응 (예: [:tada: × 3])
연결된 이슈(상위/하위/차단/차단됨)를 Markdown 링크로
첨부(이미지, 연결된 문서)를 Markdown 참조로

Minibase가 걷어내는 것:

Linear 사이드바, 커맨드 바, 단축키 안내
워크스페이스 껍데기와 계정 위젯

언제 알맞은 도구인가: 글 하나를 쓰려고 이슈 몇 개를 챙길 때, 사후 분석을 위해 장애의 상위 이슈와 하위 이슈들을 뽑아낼 때, 가벼운 일회성 작업일 때.

방법 2: Linear GraphQL API

대량으로 내보내거나 스크립트로 연동하려면 Linear의 GraphQL API가 정석입니다.

일반적인 흐름:

Linear → Settings → API에서 개인 API 키를 만듭니다
Authorization: <api-key> 헤더와 함께 https://api.linear.app/graphql로 GraphQL 쿼리를 POST 합니다
이슈, 댓글, 첨부, 연결된 이슈를 조회합니다
응답을 순회하며 Markdown으로 출력합니다

시작용 쿼리:

query {
  issues(first: 100, filter: { project: { id: { eq: "PROJECT_ID" } } }) {
    nodes {
      identifier
      title
      description
      state { name }
      assignee { name }
      priority
      labels { nodes { name } }
      comments { nodes { body user { name } createdAt } }
    }
  }
}

장점: 프로그램으로 다룰 수 있고, 필터링과 페이지네이션을 지원하며, 반복적인 내보내기에 알맞습니다.

단점: Markdown 직렬화는 직접 작성해야 하고, 큰 프로젝트에서는 페이지네이션을 신경 써야 합니다.

방법 3: Linear CLI (@linear/cli)

Linear는 흔히 쓰는 GraphQL 작업을 감싼 CLI를 제공합니다. 즉석 조회에는 좋지만, 온전한 Markdown 내보내기에는 덜 어울립니다.

예시:

npx @linear/cli issues list --project "Engineering Migration"

출력은 일반 텍스트나 JSON입니다. Markdown을 얻으려면 변환기(작은 Node 스크립트나 jq + 템플릿 등)를 거치세요.

빛을 발할 때: 빠른 스크립트 조회, 완전한 충실도가 필요 없는 CI 작업.

방법 4: Linear의 기본 내보내기

Linear → Settings → Workspace → Export는 현재 이슈를 CSV로 내보냅니다. 스프레드시트 분석에는 쓸모 있지만 Markdown은 아닙니다. CSV를 Markdown으로 바꾸는 단계는 여전히 직접 스크립트로 처리해야 합니다.

엔지니어링 팀의 작업 흐름

대부분의 Linear 사용자는 세 가지 경우 중 하나에 해당합니다.

경우 A: “이 이슈를 내 노트에 넣고 싶다”

Linear에서 이슈를 엽니다
Chrome 툴바의 Minibase를 클릭합니다
다운로드 폴더에 Markdown 파일이 떨어집니다 → Obsidian이나 Notion, RAG 시스템으로 끌어다 놓습니다

경우 B: “이번 사이클에 닫힌 이슈로 릴리스 노트를 만들고 싶다”

GraphQL API를 쓰세요.

query {
  issues(filter: { cycle: { id: { eq: "CYCLE_ID" } }, state: { type: { eq: "completed" } } }) {
    nodes { identifier title description labels { nodes { name } } }
  }
}

결과를 템플릿 기반 Markdown 체인지로그로 뽑는 Node 스크립트에 넘기면 됩니다. 오픈소스 출발점: linear-cli-tools.

경우 C: “프로젝트 전체를 이해관계자용 Markdown 아카이브로 만들고 싶다”

이슈가 20개 이하라면: 하나씩 Minibase로 저장하는 편이 빠릅니다.
100개가 넘는다면: GraphQL API를 스크립트로 돌리세요.

AI 에이전트가 Linear 내보내기에서 원하는 것

내보낸 결과를 Claude나 ChatGPT에 넘겨 종합하게 하는 것이 목적이라면:

이슈 식별자를 남기세요(ENG-1234). LLM이 되짚어 언급해야 할 때가 많습니다
상태 변화를 보존하세요. 그냥 “Done”보다 “Backlog → In Progress → Done, 3주에 걸쳐”가 훨씬 많은 것을 알려 줍니다
댓글 스레드는 작성자별로 묶지 말고 시간순으로 펼치세요
연결된 이슈의 ID만이 아니라 제목도 넣으세요. “blocks ENG-1230 (온보딩 흐름 깨짐)“은 쓸모 있지만 “blocks ENG-1230”만으로는 그렇지 않습니다

Minibase의 추출은 이미 이 모든 것을 처리합니다. Linear는 1순위로 지원하는 사이트이고, 출력은 LLM이 소화하기 좋게 다듬어져 있습니다.

실용적인 결론

즉석에서 이슈 1~10개: Minibase. 무료 → 무제한 저장, Plus(월 $5.99) → AI 템플릿과 저장 기록, 영상 전사.
정기적인 체인지로그 생성: CI에서 돌리는 GraphQL API 스크립트.
워크스페이스 전체 아카이브: GraphQL API + 직렬화 스크립트를 한 번 실행.
“지난 분기에 X를 어디서 정했더라”: 해당 결정 이슈를 Minibase로 저장한 뒤 Claude에 넣고 “이 스레드의 결정을 요약해 줘”라고 하면 5초 만에 답이 나옵니다.

Linear는 빠릅니다. 내보내기도 그래야 합니다.