← 블로그로 돌아가기

키보드 중심 이슈 트리아지

키보드 중심 이슈 트리아지

하루를 터미널에서 보낸다. vim 모션으로 파일을 탐색하고, 프리픽스 키로 tmux 팬을 전환하고, Ctrl-R로 셸 히스토리를 검색한다. 그러다 백로그 트리아지가 필요해지면, 모든 프로젝트 관리 도구가 마우스에 손을 뻗으라고 한다.

Jira는 이슈를 여는 데 클릭이 필요하다. 패널을 닫는 데 또 한 번. 프로젝트 전환에 또 한 번. Linear는 빠르지만 여전히 근본적으로 마우스 퍼스트다: 포인트하고, 클릭하고, 스크롤한다. GitHub Issues는 이슈를 열 때마다 풀 페이지 로드가 발생한다. 이 도구들은 브라우저에서 작업하는 프로덕트 매니저를 위해 설계되었지, 터미널에서 작업하는 개발자를 위한 것이 아니다.

인터랙션당 마찰은 작지만 하루를 통틀면 엄청나다. 오전에 30개 이슈를 트리아지한다면, 마우스에 손 뻗기, 클릭, 읽기, 클릭해서 닫기 사이클이 30번이다. 리스트를 순서대로 스캔하면 될 일에 키보드에서 손이 60번 떠난다.

Beadbox는 이것이 말도 안 된다고 생각하는 개발자를 위해 만들었다.

키보드 완결형 트리아지 워크플로

Beadbox는 네이티브 데스크톱 앱으로(Tauri 기반, Electron 아님), beads 이슈 트래커의 실시간 비주얼 대시보드를 렌더링한다. 에픽 트리, 의존관계 배지, 상태 필터, 프로그레스 바가 표시된다. 그리고 이 모든 것을 마우스 없이 탐색할 수 있다.

트리아지 세션은 이렇게 진행된다:

  1. Beadbox를 연다. 가장 최근 워크스페이스가 자동 로드된다. 상태 배지, 우선순위 표시, 담당자 컬럼이 있는 테이블에 이슈가 표시된다.

  2. j를 눌러 리스트 아래로 이동. k로 위로 이동. vim 스타일 모션으로, 이미 가진 근육 기억과 동일하다. 선택 하이라이트가 위치를 추적한다.

  3. Enter를 눌러 상세 패널을 연다. 선택된 이슈가 사이드 패널로 확장되어 전체 설명, 코멘트, 의존관계, 메타데이터가 표시된다. 리스트에서의 위치를 잃지 않고 읽을 수 있다.

  4. Escape를 눌러 패널을 닫는다. 리스트로 돌아오고, 커서는 떠난 곳 그대로다. j를 눌러 다음 이슈로 이동.

  5. /를 눌러 검색. 검색 바가 나타난다. 키워드나 이슈 ID를 입력하면 리스트가 즉시 필터링된다. Escape로 검색을 지우고 전체 리스트로 돌아간다.

  6. 에픽 트리에서 화살표 키를 사용. 중첩된 하위 태스크가 있는 에픽을 볼 때, 좌우 화살표로 트리 노드를 접고 펼 수 있다. h와 l도 동작한다(vim 스타일 수평 탐색). 15개 이슈의 에픽을 디스클로저 삼각형 하나 클릭하지 않고 스캔할 수 있다.

이것이 전부다. j/k로 이동, Enter로 열기, Escape로 닫기, /로 검색, 화살표 키로 트리 확장. 5개 키가 트리아지 탐색의 90%를 커버한다.

트리아지 중 상태 변경이나 우선순위 올림이 필요한 이슈를 발견하면, 터미널로 내려간다:

bd update bb-f8o --status in_progress --priority 1

Beadbox가 밀리초 이내에 변경을 감지하고(파일 시스템 워치와 WebSocket을 통해) 다시 렌더링한다. 새로고침도 클릭도 없이 업데이트된 상태 배지가 보인다. j를 누르고 계속 진행하면 된다.

읽기와 쓰기가 의도적으로 분리된 이유

여기서 대부분의 GUI 도구가 실수한다. 모든 것을 처리하려 한다: 이슈 읽기, 필드 편집, 상태 변경, 의존관계 관리. 결과는 폼의 산이다. 상태용 드롭다운 메뉴. 설명용 텍스트 입력. 의존관계 관리용 모달 다이얼로그. 이 인터랙션 전부가 클릭을 요구한다.

Beadbox는 다른 접근을 택했다. 읽기 중심 인터페이스다. 쓰기는 CLI가 처리한다.

beads CLI(bd)가 이슈 데이터의 정규 소스다. 에이전트가 쓰고, 스크립트가 쓰고, 자동화가 쓴다. GUI를 통한 두 번째 쓰기 경로를 만들면 동기화 문제가 발생하고 버그 대상 면적이 두 배가 된다.

대신 Beadbox는 이해와 탐색에 철저하게 최적화한다. 터미널이 가장 못하는 질문에 답한다: 에픽 트리 전체 모습은? 어떤 이슈가 블로킹되어 있고, 무엇에? 이 기능 얼마나 진행됐나? 지난 1시간 동안 뭐가 바뀌었나? 이것들은 비주얼한 질문이다. bd list의 플랫 텍스트 출력이 기술적으로 답할 수 있지만, 프로그레스 바가 있는 접을 수 있는 트리는 한눈에 답한다.

키보드 단축키는 그 한눈을 빠르게 만들기 위해 존재한다. 스캔하고, 읽고, 이해한다. 행동이 필요하면 bd 명령을 입력한다. 두 도구가 각각 가장 잘하는 것을 담당한다.

컨텍스트를 잃지 않는 워크스페이스 전환

여러 프로젝트(각각 자체 beads 데이터베이스를 가진)에서 작업하면, 워크스페이스 전환이 일상적인 마찰점이 된다. 대부분의 프로젝트 관리 도구에서 프로젝트 전환은 다른 URL로 이동, 다른 워크스페이스 로그인, 새 브라우저 탭 열기를 의미한다. 필터가 리셋된다. 스크롤 위치가 리셋된다. 이전 프로젝트에서 가졌던 멘탈 컨텍스트가 사라진다.

Beadbox는 다르게 처리한다. 헤더의 드롭다운에 감지된 모든 워크스페이스가 나열된다. 클릭(또는 키보드로 탐색)해서 다른 프로젝트를 선택하면, 그 프로젝트의 데이터베이스에서 전체 뷰가 리로드된다. 핵심 디테일: 필터와 스크롤 위치가 워크스페이스별로 유지된다. 돌아가면 모든 것이 떠난 그대로다.

감지는 자동이다. Beadbox가 ~/.beads/registry.json에서 등록된 워크스페이스를 스캔하고 .beads/ 데이터베이스를 포함하는 디렉토리를 발견한다. 새 프로젝트를 추가하고 bd init을 실행하면, 다음에 Beadbox를 열 때 드롭다운에 나타난다. 임포트도 설정 화면도 "워크스페이스 추가" 마법사도 없다.

여러 서비스를 관리하거나 여러 리포지토리에 걸쳐 에이전트를 관리하는 개발자에게, 이것은 Beadbox를 모든 활성 작업에 걸친 단일 창으로 만든다. 대안은 여러 터미널 창에서 각각 다른 --db 경로에 대해 bd list를 실행하고, 어떤 창이 어떤 프로젝트를 가리키는지 머릿속에서 추적하는 것이다.

대안 도구 비교

모든 주요 프로젝트 관리 도구가 기본 탐색에 마우스 조작을 요구한다:

Jira에는 키보드 단축키가 있다(j/k 존재). 하지만 상세를 여는 데 클릭, 프로젝트 전환에 클릭, 에픽 관리를 위한 깊이 중첩된 메뉴 탐색에 클릭이 필요한 리스트 뷰 사이 탐색이다. 단축키가 기반 위에 나중에 붙인 느낌이다.

Linear가 SaaS 도구 중 키보드 친화적에 가장 가깝다. Cmd+K로 커맨드 팔레트, 몇 가지 탐색 단축키가 있다. 하지만 워크스페이스 전환은 여전히 사이드바 메뉴 클릭이 필요하고, 커맨드 팔레트는 스캔 퍼스트가 아닌 서치 퍼스트 인터랙션 모델이다. 찾는 것이 무엇인지 알아야 한다. 트리아지는 아직 모르는 것을 스캔하는 것이다.

GitHub Issues에는 트리아지를 위한 의미 있는 키보드 탐색이 없다. 이슈를 클릭해서 열고(풀 페이지 로드), 뒤로 버튼 클릭으로 돌아가고, 반복한다. 리포지토리 간 전환은 URL 변경이다. 백로그의 키보드 중심 스캔은 존재하지 않는다.

Beadbox는 처음부터 키보드 트리아지를 전제로 설계되었다. 단축키가 마우스 퍼스트 UI 위에 나중에 얹은 것이 아니다. 탐색 모델 전체가 키보드에서 손을 떼지 않는 것을 전제로 한다. 마우스도 동작한다(모든 것이 클릭 가능). 하지만 프라이머리가 아닌 폴백이다.

진짜 비교하는 것

진짜 차이는 "어떤 도구가 키보드 단축키가 더 많은가"가 아니다. 인터랙션 모델이다.

마우스 퍼스트 도구는 발견 가능성을 위해 최적화한다. 모든 액션에 보이는 버튼이 있다. 온보딩과 기능을 찾아야 하는 비기술 사용자에게 좋다. 할 일을 알고 난 후의 속도에는 최악이다.

키보드 퍼스트 도구는 처리량을 위해 최적화한다. j/k/Enter/Escape를 익히면, 포인팅 속도가 아닌 읽기 속도로 트리아지한다. 트레이드오프는 초기 학습 곡선이 가파르다는 것(단축키 존재를 알아야 한다). 에디터와 터미널에서 이미 vim 모션을 쓰는 개발자에게 그 곡선은 사실상 평평하다.

Beadbox는 SaaS 도구에서 할 수 없는 트레이드오프도 한다: beads 전용이다. Jira의 인테그레이션, Linear의 사이클, GitHub의 풀 리퀘스트 링크를 얻지 못한다. 모든 것을 로컬에 저장하고, 오프라인에서 동작하고, AI 에이전트가 Unix 파이프를 통해 이슈를 읽고 쓸 수 있는 Git 네이티브 이슈 트래커의 비주얼 대시보드를 얻는다. 그것이 자신의 스택이라면 이 키보드 워크플로에 필적하는 것은 없다. 이슈 클로즈 시 Slack 알림이 필요하다면 현재로서는 적합한 도구가 아니다.

시작하기

Beadbox를 Homebrew로 설치:

brew tap beadbox/cask && brew install --cask beadbox

이미 beads를 사용하고 있다면, Beadbox가 .beads/ 워크스페이스를 자동 감지한다. 앱을 열고 j를 누르기 시작하면 된다.

macOS, Linux, Windows에서 동작한다. 베타 기간 동안 무료.