PokeTokenBar: Instructions file for Claude Code

PokeTokenBar — Claude 프로젝트 지침

이 파일은 매 세션 전문이 로드된다. 그래서 여기엔 항상 적용되는 규칙만 둔다. 길고 상황별인 절차는 docs/reference/ 로 내리고 아래 인덱스에서 "언제 읽는가"로 가리킨다. 새 규칙을 더할 때도 같은 기준으로 배치한다 — 항상 적용이면 여기, 특정 작업 때만이면 참조 문서.

참조 문서 (필요할 때 읽는다)

문서	언제 읽나
docs/reference/release-workflow.md	버전을 배포할 때, release.sh 게이트에 막혔을 때, UI 변경으로 스크린샷·랜딩을 갱신할 때
docs/reference/provider-extension.md	새 사용량 소스·버전매니저·로그 루트를 추가할 때, 프로바이더 분기를 리뷰할 때
docs/reference/defect-log.md	결함·회귀를 고치는 중(부류 스윕 근거), 동시성·캐시·외부 로그 포맷·대용량 파일 읽기·상시 애니메이션·세이브 이전을 건드릴 때

각 문서의 frontmatter(summary/read_when)가 그 문서의 적용 범위를 다시 명시한다.

기여 언어 규약 (오픈소스 대비 — English first)

외부 컨트리뷰션을 받을 수 있도록 이 저장소는 영어를 first language 로 한다.

• PR 제목·본문은 영어만. 한국어로 지시받아도(예: "PR 올려줘") PR 산출물은 영어로 작성한다. 기존 git log(한국어)를 모방하려는 커밋 컨벤션 자동 감지보다 이 규칙이 우선한다.
• 스쿼시 머지 저장소라 PR 제목이 곧 main 커밋 제목이 된다 → PR 을 영어로 쓰면 공개 히스토리도 영어로 유지된다.
• 커밋 메시지도 영어 기본. 스쿼시 전 브랜치 커밋 목록도 PR 리뷰어에게 노출되므로 영어로 쓴다.
• 범위 밖(추후): 코드 주석·이 CLAUDE.md 본문의 영어 전환. README/랜딩은 이미 en/ko/ja 다국어 유지.

릴리스 (자연어 트리거)

사용자가 버전 배포를 자연어로 요청하면 — 예: "배포해줘", "릴리스 올려줘", "패치 배포", "2.1.1 배포", "release", "다음 버전 내줘" — 한 줄 명령을 시키지 말고 직접 수행한다.

버전 결정 (2026-07-03 확정 규칙): 사용자가 말한 단어가 곧 세그먼트 지정 명령이다 — 릴리스에 기능이 포함돼 있어도 변경 내용으로 재해석하지 않는다.

• "패치(해줘)" → x.y.Z+1 / "마이너" → x.Y+1.0 / "메이저" → X+1.0.0
• 버전을 직접 명시하면("2.4.1 배포") 그 값 그대로.
• 세그먼트 지정 없이 "배포/릴리스"만 말하면: 변경 성격 기준으로 제안 후 확인받고 진행.

문서·스크린샷·랜딩 갱신은 매 릴리스 필수다 — "할까요?" 묻지 말고 무조건 한다. 실행 절차·에셋 게이트·함정은 docs/reference/release-workflow.md, 체크리스트는 RELEASE.md.

릴리스는 외부 공개(비가역)이므로 실행 직전 적용할 버전과 노트 요약을 한 번 보여준 뒤 진행한다.

확장 규약 (새 프로바이더/툴 추가 시)

특정 플랫폼에 종속된 분기를 만들지 않는다. 손댈 지점은 정해져 있다 — 사용량 소스는 UsageProvider 구현체 + UsageStore.init 의 providers: 배열, 버전매니저는 BinaryLocator.commonToolDirectories(), 로그 루트는 프로바이더별 루트 목록(예: LocalUsageReader.claudeProjectRoots). 범용 경로(오늘/주/월 합계·burn·companion)에 == "claude_code" 류 리터럴 분기를 넣는 건 금지.

전체 규약과 리뷰 기준은 docs/reference/provider-extension.md.