결정 기록 (ADR)

되돌리기 어렵거나 대안이 갈렸던 선택만 기록한다. 저장소에 커밋해 두므로 새로 클론해도 바로 보인다.

무엇을 남기는가

• 되돌리려면 비용이 크거나(구조·의존성·외부 도구를 바꿔야 함) 검토한 대안이 여럿이라 나중에 “왜 이걸 골랐는지”를 다시 물어볼 가능성이 있는 결정 → ADR
• 버그 수정, 작은 값 조정처럼 대안이 갈리지 않은 변경 → 남기지 않는다
• 회차별 진행 상황(한 것·막힌 것·다음 할 것) → 남기지 않는다

작성

• templates/adr.md를 복사해 NNNN-<슬러그>.md로 만든다. 번호는 4자리, 앞자리 0 채움, 순차 증가.
• 기존 결정을 뒤집으면 새 문서를 만들고, 옛 문서의 상태를 대체됨 (→ NNNN)으로 바꾼다. 옛 문서는 지우지 않는다.

목록

• 0001-pane-navigation-shortcut.md — 분할 pane 이동 단축키는 Ctrl+Shift+방향키, 에디터 포커스에서는 원래 동작 유지
• 0002-color-roles.md — 화면 크롬은 무채색으로 두고 유채색은 세션 상태와 로고에만 사용
• 0003-tab-group-unit.md — 탭 묶음 단위는 설정으로 고르고, 바꿀 때는 재시작해 변환
• 0004-claude-status-priority.md — Claude 상태를 모을 때 worktree 줄은 작업 중을, 프로젝트 줄과 상태 바는 권한 대기를 앞세움
• 0005-external-git-changes.md: 앱 밖의 git 변경은 메타데이터 감시와 초점 복귀로 따라가고, 외부 worktree는 모두 보여 줌
• 0006-macos-notification-signing.md: macOS 알림을 받으려고 개발 실행과 배포 빌드를 ad-hoc으로 서명하고, 알림은 메인 프로세스에서 띄움
• 0007-plan-hook-belloga-only.md: plan 훅은 Belloga 앱 안의 터미널에서 시작된 세션에만 안내를 넣음
• 0008-module-structure.md: 프로세스 안쪽을 도메인 폴더로 나누고, 폴더 사이의 의존 방향을 eslint로 검사함
• 0009-radix-popover.md: 떠오르는 면은 Radix Popover로 만듦
• 0010-orca-status-bar-design.md: 상태 표시줄은 Orca 디자인을 그대로 따르고, 사용량 등급에 유채색을 씀
• 0011-claude-oauth-usage.md: Claude 사용량을 OAuth 사용량 API로도 가져오고, 토큰은 메인 프로세스 밖으로 내지 않음
• 0012-claude-hook-auto-install.md: Claude 훅은 앱이 켜질 때 전역으로 알아서 설치하고, 끄는 스위치는 설정 화면에 둠
• 0013-excalidraw.md: 그림 도구로 Excalidraw를 들이고, 파일은 옵시디언과 호환되는 .excalidraw.md에 압축하지 않은 json으로 둠
• 0014-graph-view.md: 그래프 보기는 force-graph를 React 래퍼 없이 쓰고, 그래프 모드의 사이드바는 루트 칸 목록으로 둠
• 0015-plan-templates-harness-mode.md: plan 템플릿과 규칙을 ~/.belloga/agents의 사용자 파일로 두고 하네스 모드에서 고치며, 규칙은 따로 켜는 SessionStart 훅이 주입함
• 0016-worktree-hook.md: worktree 위치를 plan 방식에서 떼어 내, 만들기 전에 묻게 하는 worktree 훅으로 두고 그 켜짐을 앱의 미리 채우기에도 씀
• 0017-worktree-view-options.md: 워크트리 탭은 트리 대신 기본형, 카드형, 상태별 세 보기로 그리고, 설정의 Git 탭에서 고름
• 0018-plan-cloud-sync-storage.md: 계획 문서 클라우드 동기화는 GCS 해시 주소 저장 + 단일 포인터로 하고, 충돌은 파일 단위 예외 경로로만 다룸
• 0019-claude-chat-transcript.md: Claude 탭의 채팅 뷰는 기존 훅 요청에 실은 transcript 경로로 파일을 읽어 그리고, 훅 이벤트는 더하지 않음
• 0020-claude-chat-composer.md: Claude 탭은 Orca Native Chat의 Claude, 로컬 부분만 가져와 채팅 화면과 pty에 쓰는 자체 입력창으로 쓰고, 터미널 자르기는 지움
• 0021-terminal-links.md: 터미널 링크는 Orca의 탐지기를 가져오고, 파일을 앱 탭과 시스템 중 어디서 열지는 main이 실제 경로로 판정함
• 0022-docs-site.md: 문서 사이트는 이 저장소의 site/에 Starlight로 두고 Cloudflare로 docs.belloga.com에 올림