The guidebook / 181 guides
Developer tools
Code, configuration and workflows. Source-linked checks to help you move forward.
Check uv tool updates before upgrading: latest versions and stored constraints
Inspect uv tool updates, read stored version constraints and distinguish an ordinary upgrade from replacing a pin, with a local reproduction.
uv --with installed the package but its command is missing: inspect dependency executables
Compare two local-wheel installations to distinguish an importable extra package from its exported console command, then check the executable directory.
uvx works but uv tool list is empty: check temporary execution versus installation
Compare a successful temporary tool run with persistent installation, then verify registration, executable location and shell lookup as separate steps.
uv tool run cannot find the executable: separate package and command names
Read the executable list, pair the verified package with its command using --from, and compare two offline local-wheel runs with different exit codes.
Git missed a filename case change: verify a targeted two-step rename
Use an unused intermediate filename, inspect the staged path and unchanged contents, and verify casing before committing or deploying.
Uncommitted changes followed a Git branch switch: inspect before committing
See why staged edits can remain after switching branches, when Git refuses the switch, and how to avoid committing work on the unintended branch.
Changed Git email but old commits still show the old author: check the right layer
Compare effective identity, existing commit metadata, and the next commit without rewriting shared history or confusing author settings with account access.
Git restore returned the staged version: choose the source and destination
Use a three-version example to distinguish restoring a working file from unstaging it, without treating every restore action as return to HEAD.
Git stash left a new file behind: inspect untracked files before restoring
Check what a stash actually contains, distinguish include-untracked from all, and apply without dropping the saved entry first.
A file in .gitignore still shows changes: check whether Git already tracks it
Inspect the index, test the matching ignore rule, and review a targeted untracking change without deleting the local file.
uv run -m misses inline script requirements: choose module or script mode
Compare file execution with module execution, record the metadata boundary, and choose where dependencies and Python requirements belong.
Claude Code가 종료 훅 뒤 계속 작업할 때: 반복 방지와 완료 검증 구분하기
stop_hook_active와 연속 계속 실행 상한을 읽고, 종료된 턴을 검증 성공으로 오인하지 않는 진단 순서입니다.
uv venv used one Python but uv run selects another: check the project pin
Separate a one-command interpreter request from project Python selection, with an offline unavailable-version experiment and a safe recovery checklist.
GitHub API 403 오류: 재시도 전에 사용량 제한과 권한 부족 구분하기
403·429 응답의 본문과 Retry-After·잔여량 헤더를 읽고, 권한 문제를 재시도 루프로 숨기지 않는 확인 순서입니다.
uv sync removed a manually installed package: preserve it or declare it?
Choose between declaring a dependency and temporary inexact syncing, with an offline reproduction that separates package removal from lockfile freshness.
Claude Code 훅이 막지 못하거나 멈출 때: PreToolUse 종료 코드와 출력 확인
PreToolUse의 exit 1·exit 2·JSON 출력을 구분하고, 실제 도구 실행 없이 훅의 입력과 stderr를 점검하는 방법입니다.
GitHub 라이선스 배지가 없을 때: 파일·버전·API 확인 기록 만들기
라이선스 배지와 실제 파일, 자동 탐지 결과를 나눠 확인하고 검토 대상 버전과 미확인 권한을 기록하는 절차입니다.
uv --locked fails but --frozen passes: reproduce metadata drift offline
A dependency-free experiment shows why a successful frozen sync does not establish that uv.lock matches pyproject.toml, with exit codes and recovery checks.