Skip to content

README.ko.md

Latest commit

 

History

History
262 lines (205 loc) · 16.1 KB

README.ko.md

File metadata and controls

262 lines (205 loc) · 16.1 KB
Raw

gadak gadak

Latest Release CI License

Find the thread in your backlog.

English · 한국어 · 日本語

지라를 쓰기 싫은데 어쩔 수 없이 써야 해서 만들었습니다. 묵은 이슈들을 클로드로 뒤지다가 한참 걸리고 결국 rate limit에 걸려 중단된 적이 있는데, 그때 만들기 시작했습니다. 크롬에 지라 탭이 잔뜩 쌓여 피곤해지는 것도 겸사겸사 없애고 싶었고요.

gadak은 필요한 Jira 프로젝트와 Confluence 스페이스만 골라 이 컴퓨터에 캐시합니다. 이슈와 댓글, 변경 이력, 위키 문서를 한 검색창에서 찾고, SQL로 집계합니다. 쓰기는 Jira가 먼저 받은 뒤 캐시가 따라 바뀝니다. 데스크톱 앱, gadak serve가 여는 브라우저 탭, CLI가 같은 캐시를 보고, Claude Code에는 스킬 하나로 넘깁니다. 바이너리 하나로 돌고, gadak 계정은 없습니다.

Atlassian이 직접 내는 Rovo MCP가 있는데 왜 이걸 쓰냐고 물으실 텐데, 대답은 아래 다른 선택지에 적어 뒀습니다. 짧게는 집계와 오프라인입니다.

먼저 눌러 보기

라이브 데모에 이슈 534건이 들어 있습니다. 설치도 계정도 없이 브라우저에서 열립니다. 바로 가기: 연결 전에 확인할 것 · 설치 · Claude Code · 지원 범위.

연결 전에 확인할 것

  • 연결되는 Jira는 Atlassian Cloud입니다. API 토큰 하나로 같은 사이트의 Jira와 Confluence에 붙습니다. 스코프 없는 사용자 토큰(ATATT…)이어야 하고, 조직 키(ATCTT…)로는 로그인이 안 됩니다. Jira Server와 Data Center는 gadak init --server에 Personal Access Token 하나이고, 위키는 거기서는 꺼져 있습니다.
  • 가져올 범위는 직접 정합니다. --projects와 --spaces로 고르고, 스페이스를 지정하기 전에는 위키를 가져오지 않습니다.
  • 캐시는 이 컴퓨터 안의 SQLite 파일 하나입니다. 처음 한 번은 전체 동기화가 필요합니다(측정한 사이트에서 3.7분). 그 뒤로는 gadak serve가 기본 60초 간격으로 증분 동기화를 돌리고, 한 시간에 한 번 대조해서 지워진 이슈를 캐시에서도 지웁니다. 캐시는 지워도 됩니다. 다시 동기화하면 돌아옵니다.
  • API 토큰은 캐시에도, 로그에도, 스냅샷에도 남지 않습니다. ~/.gadak/config.json에 0600 권한으로 저장되고, 내 사이트로 보내는 요청의 Authorization 헤더에만 쓰입니다.
  • 텔레메트리는 없습니다. gadak이 연결하는 곳은 직접 설정한 곳뿐입니다. 전체 목록은 SECURITY.md에, 연결마다 끄는 방법은 docs/NETWORK.md에 있습니다.
  • 몇 가지 읽기는 Jira에 직접 묻습니다. 첨부파일 보기, gadak issue --editmeta, gadak fields, gadak api가 그렇습니다.
  • 캐시를 읽는 에이전트는 읽은 내용을 자기 모델로 보냅니다. 에이전트가 봐도 되는 프로젝트만 캐시하세요.

설치와 첫 실행

macOS 앱(CLI 포함):

brew install --cask midagedev/tap/gadak

CLI만:

brew install midagedev/tap/gadak-cli

첫 실행은 사이트 주소, 이메일, API 토큰, 프로젝트를 차례로 묻고, 끝나면 gadak serve가 http://gadak.localhost:7777을 찍습니다. 첫 동기화는 최근 이슈부터 돕니다:

gadak init && gadak serve

처음부터 범위를 좁히려면 프로젝트와 스페이스를 함께 줍니다:

gadak init --projects ENG,PROD --spaces ENG

화면은 한국어로 뜹니다. dmg, 리눅스 tarball, Docker, 업그레이드는 docs/INSTALL.md.

Windows. 데스크톱 앱은 Microsoft Store에 있습니다. Store가 서명하니 SmartScreen도 Smart App Control도 막지 않고, 0.20.2부터는 gadak이 PATH에 올라갑니다. CLI만 쓰려면 최신 릴리스의 gadak_<version>_windows_amd64.zip(또는 arm64)을 풉니다. 릴리스의 데스크톱 zip(Gadak-<version>-windows-x64.zip)은 서명이 없어서 SmartScreen이 막습니다 (docs/WINDOWS-SIGNING.md). 그때는 Store로 가고, Smart App Control은 끄지 마세요.

Claude Code와 다른 에이전트

gadak skill install

스키마와 쿼리 패턴이 담긴 파일 하나를 설치하고, 별도 프로세스는 띄우지 않습니다. gadak skill install codex처럼 이름을 붙이면 cursor·gemini·opencode·grok에도 같은 파일이 들어갑니다. 셸이 없는 Claude Desktop에는 gadak mcp install claude-desktop으로 MCP 서버를 등록합니다.

gadak 앱의 터미널에서 Claude Code로 이슈 목록을 바꾸고 라벨 비율 대시보드를 저장해 여는 한국어 세션
앱 창 안의 셸(⌘K → 터미널, 또는 Ctrl+`)에서 gadak claim NMA-140을 치면 이슈가 진행 중으로 바뀝니다. 그 셸에서 시작한 Claude Code 세션이 옆의 보드를 움직입니다. 프롬프트 두 줄 외에는 대본이 없고, 에이전트가 일하는 구간은 빨리 감았습니다. 녹화: e2e/demo/terminal-claude-demo.spec.ts, record-terminal-claude.sh.

한국어 계정의 함정 하나. Jira는 상태와 우선순위 이름을 계정 언어로 번역해서, priority = High는 오류 없이 0행이고 에이전트는 그걸 "그런 이슈는 없다"로 읽습니다. 필터는 status_category와 priority_rank로 걸어야 하고, 스킬이 그렇게 가르칩니다. SQL로 찾은 이슈는 gadak sql --no-header "…" | gadak views open --keys -로 앱에 띄우고, gadak views open --jql '…'은 JQL을 필터 칩으로 내려놓습니다.

쓰기(create, edit, comment, transition, claim, link, 위키 page)는 Jira를 거친 뒤 캐시가 갱신되고, 에이전트가 남긴 것에는 에이전트 이름이 붙습니다. SQL 레퍼런스는 docs/MIRROR.md, 도구별 연결은 docs/AGENT_SETUP.md.

SQL로 집계하기

JQL에는 GROUP BY가 없습니다. 에픽별 열린 이슈를 세는 데 이번 측정에서는 API 결과 8페이지를 받아 합산해야 했는데, gadak에서는 쿼리 한 번입니다:

gadak sql "select epic_key, count(*) from issues_full where resolved_at is null
           and epic_key <> '' group by epic_key order by 2 desc"

같은 쿼리를 Datasette Lite가 데모 스냅샷에서 브라우저 안에서 돌려 줍니다. 나머지 쿼리는 docs/RECIPES.md.

성능 측정

2026-08-26, 실제 Atlassian Cloud 업무 프로젝트(이슈 3,296건)에서 잰 중앙값입니다. gadak 쪽은 CLI 프로세스가 뜨는 시간까지 넣은 값입니다.

질문 REST API gadak
단순 필터 100건 583 ms 19 ms 31×
이슈 1건과 전체 변경 이력 710 ms 28 ms 25×
텍스트 검색 543 ms 41 ms 13×
에픽별 열린 이슈 (GROUP BY) 4,761 ms, API 8페이지를 받아 합산 22 ms 214×
변경 이력 집계 JQL로 표현 불가, 순회하면 약 28분 14 ms

첫 전체 동기화는 위 사이트에서 3.7분이고, 캐시는 동기화 주기만큼 늦습니다. 측정 방법은 docs/BENCHMARKS.md.

지원 범위와 다른 사용 방식

Atlassian Cloud, Jira Server/Data Center, Linear, 내장 트래커에서 같은 명령을 씁니다. Linear 동기화는 gadak sync --source linear입니다. 서비스별로 무엇을 거절하는지는 셀마다 코드를 인용한 docs/SUPPORT_MATRIX.md에 있습니다.

어느 서비스에도 없는 것이 셋 있습니다. 화면으로서의 스프린트, Jira 대시보드, Jira 알림함. 스프린트 계획, 관리자 작업, 1분의 지연도 안 되는 일은 Jira에서 계속 합니다(docs/CONCEPT.md).

Atlassian 계정 없이 시작하려면 gadak init --local로 내장 트래커를 씁니다. 워크스페이스를 옮기는 명령은 gadak --workspace <new> migrate --from <old>이고, Linear로 옮길 때는 --to linear를 붙입니다. 다른 컴퓨터와 페어링은 gadak --workspace laptop init --pairing-code-stdin입니다.

폰 앱 (베타)

아이폰 앱은 이미 돌리고 있는 gadak serve에 페어링합니다. 자기 네트워크 안에서 끝나고, 중간에 계정도 남의 서버도 없습니다. 캐시가 가진 것은 폰도 보여줍니다. 필드, 첨부, 연결된 이슈, 위키, 진행 중인 스프린트와 그 뒤의 전부. 한 줄로 끝나는 수정은 폰에서 끝납니다. 코멘트, 라벨, 마감일, 사진, 에픽 밑에 새 이슈. 쓰기는 데스크톱과 똑같이 원본을 먼저 통과합니다. 페이지나 커스텀 필드 편집, 뷰 작성, 대시보드 배치, 카드 끌기는 데스크톱 몫이고, 앱이 그 컨트롤 자리에서 그렇게 말합니다.

폰에서 쓰는 장면 — Fields 구역과 첨부가 보이는 이슈, 상태를 진행 중으로 옮기고, 코멘트를 쓰고, 사진을 붙여 스레드에 올린다

한 테이크 중 쓰는 절반입니다. 전체는 사이트에서 재생됩니다 — GitHub 마크다운은 <video>를 지웁니다. 연출이 아니라 실제로 써집니다: 데모 스냅샷을 그 자체로 하나의 트래커로 띄워 놓고 찍었습니다.

베타이고 상태는 그게 전부입니다. 빌드는 내부 테스터용 TestFlight로만 가고 공개 다운로드는 없습니다. 스토어 등록은 심사자가 제 네트워크에 들어오지 않고도 앱을 볼 수 있는 경로가 먼저입니다.

다른 선택지

Rovo MCP는 Atlassian이 호스팅하니 설치할 것이 없고, Jira와 Confluence를 검색하고 쓰기도 합니다. 대신 집계 도구가 없고 네트워크 없이는 아무것도 못 읽습니다. 에픽별 미해결 개수 같은 것을 물으면 페이지를 여러 번 받아다 클라이언트 쪽에서 세게 됩니다. gadak은 로컬 캐시에 SQL을 던지니 그게 GROUP BY 한 줄이고, 비행기에서도 읽힙니다. 대신 바이너리를 깔아야 하고, 첫 동기화를 한 번 기다려야 하고, 읽는 값은 마지막 동기화 시점의 것입니다.

jira-cli는 명령마다 API를 칩니다. 먼저 있던 것으로 Scrumdog, jira-offline, jira-cache가 있습니다. gadak은 Jira와 Confluence를 한 캐시에 넣고 SQL·데스크톱· 브라우저·CLI·MCP를 함께 얹은 쪽입니다. 항목별 표는 docs/FAQ.md에 있습니다.

만들지 않기로 한 것

  • 캐시에 직접 쓰기. 기록은 Jira입니다. 로컬에 쓰기 모델을 두면 충돌을 풀어야 하고, 그건 다른 제품입니다.
  • 여러 사람이 함께 쓰는 배포. 보안 모델이 한 사람, loopback, 인증 없음이라 정면으로 충돌합니다. 계정도 서버도 강제하지 않는 대가입니다.
  • 스프린트 계획 화면. 읽는 쪽은 만들었습니다. 활성 스프린트의 남은 날과 진행률, 이월 표시, 스프린트로 자른 회고까지. 이슈를 스프린트 사이로 끌어다 놓는 것과 속도 예측은 Jira와 Linear의 화면에서 계속 합니다.
  • 업데이트 확인. 만들었다가 뺐습니다. 하루 한 번 GitHub에 새 버전을 묻고 있었는데, 나가는 요청 목록을 짧게 유지하는 쪽이 낫다고 판단해 0.22에서 지웠습니다. 목적지가 여섯에서 다섯이 됐습니다. 업그레이드는 brew upgrade입니다.
  • Confluence Server. Jira Server는 인스턴스를 직접 띄워 셀마다 명령을 돌린 뒤에 지원한다고 적었습니다. 위키 쪽은 클라이언트가 없어서 안 된다고 적습니다. 검증하지 않은 것을 지원한다고 적지 않는 것이 이 목록의 규칙입니다.

상태와 호환성

상태: 0.24, 아직 0.x입니다. 동기화, 읽기 API, 쓰기, 데스크톱·웹·CLI·MCP를 실제 사이트에서 확인했습니다. 한 사람이 만들고, 라이선스는 Apache-2.0입니다. 이름은 엉킨 실에서 뽑아낸 한 줄기, '가닥'에서 왔습니다.

0.x에서 바꾸지 않기로 약속한 것은 specs/000-product/data-model.md의 셋입니다. issues_full과 RECIPES 쿼리, gadak sql의 출력 형식, gadak views open --keys -의 의미. 항목별 확인 명령은 docs/PROMISES.md에, 무엇이 나왔는지는 CHANGELOG.ko.md에 있습니다.

한 줄 남겨 주세요

텔레메트리가 없어서 누가 쓰는지 저는 모릅니다. 어디에 썼는지, 그 뒤로도 쓰고 있는지 알려 주세요. 잘 안 됐거나 결과가 틀렸다면 그 이야기가 더 반갑습니다. GitHub 이슈, X @midagedev 멘션, 메일 midagedev@gmail.com, 어느 쪽이든 됩니다.

공개된 곳에는 실제 이슈 내용과 토큰, 사이트 주소를 빼고 적어 주세요. 버그 리포트에는 Cloud인지 Server인지, gadak 커밋, 실행한 명령이 있으면 됩니다. 커밋의 GDK-nnn 키는 공개 백로그로 이어집니다. 코드로 오시려면 .github/CONTRIBUTING.md와 docs/project/GOOD_FIRST_ISSUES.md.

문서