Skip to content

CLAUDE.md

Latest commit

 

History

History
183 lines (154 loc) · 7.5 KB

CLAUDE.md

File metadata and controls

183 lines (154 loc) · 7.5 KB
Raw

PHP project (>=8.2) with Symfony.

This project is a PHP library for using the Geocaching API.

Architecture

  • Uses PSR-7, PSR-17, PSR-18 for HTTP client agnosticism
  • HTTPlug for HTTP client abstraction
  • Plugin architecture with Http\Client\Common\Plugin
  • Clients separated by business domain (GeocacheClient, UserClient, etc.)

Environments

HTTP Logging

  • GeocachingHttpLoggerPlugin available for HTTP request/response logging
  • Automatic token masking in logs
  • Configuration via Options::enableHttpLogging()

Tests

  • PHPUnit 12 with PHP 8 attributes (#[DataProvider])
  • Unit tests in tests/
  • Test command: composer run phpunit
  • Currently 234 tests, 902 assertions

Common Issues Fixed

  • Query string concatenation: use ternary operator to avoid "Array to string conversion"
  • Interface types: HttpMethodsClientInterface instead of HttpMethodsClient
  • StatusClient bypasses auth/BaseUri plugins but keeps logging

API Reference URLs

All clients follow official Swagger patterns:

  • /geocaches, /users, /adventures, /lists, /logs, /trackables, etc.
  • Adventure anon endpoints: /adventures/anon/ (not /adventures/)

Code Review / Audit Rules

  • Before flagging a "hand-rolled stdlib" or "unnecessary wrapper" finding, grep for actual call sites first. A one-line wrapper reused across many callers (e.g. Enum/EnumTrait.php's getList()/getListId(), used by 11 enums) is DRY, not over-engineering — don't suggest removing it.
  • RetryStrategy implementations share eligibility logic in Reliability/AbstractRetryStrategy.php (retryable exceptions/status codes, shouldRetry(), getMaxAttempts(), isRetryableStatusCode()). Only getDelay() differs per strategy (FixedDelayStrategy, ExponentialBackoffStrategy). Add new strategies by extending this base class, not by copy-pasting.
  • Don't flag public interfaces (e.g. ClientBuilderInterface) as yagni just because this repo has one implementation — this is a library, and external consumers may type-hint or mock against public interfaces even with no in-repo evidence.
  • A method used only via a trait (e.g. RateLimitAwareDelay::getRateLimitDelayMs()) must be protected, not private, if any class using the trait is subclassed — PHP traits don't relax visibility across the class hierarchy the way you'd expect.

RTK (Rust Token Killer) - Token-Optimized Commands

Golden Rule

Always prefix commands with rtk. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use.

Important: Even in command chains with &&, use rtk:

# ❌ Wrong
git add . && git commit -m "msg" && git push

# ✅ Correct
rtk git add . && rtk git commit -m "msg" && rtk git push

RTK Commands by Workflow

Build & Compile (80-90% savings)

rtk cargo build         # Cargo build output
rtk cargo check         # Cargo check output
rtk cargo clippy        # Clippy warnings grouped by file (80%)
rtk tsc                 # TypeScript errors grouped by file/code (83%)
rtk lint                # ESLint/Biome violations grouped (84%)
rtk prettier --check    # Files needing format only (70%)
rtk next build          # Next.js build with route metrics (87%)

Test (60-99% savings)

rtk cargo test          # Cargo test failures only (90%)
rtk go test             # Go test failures only (90%)
rtk jest                # Jest failures only (99.5%)
rtk vitest              # Vitest failures only (99.5%)
rtk playwright test     # Playwright failures only (94%)
rtk pytest              # Python test failures only (90%)
rtk rake test           # Ruby test failures only (90%)
rtk rspec               # RSpec test failures only (60%)
rtk test <cmd>          # Generic test wrapper - failures only

Git (59-80% savings)

rtk git status          # Compact status
rtk git log             # Compact log (works with all git flags)
rtk git diff            # Compact diff (80%)
rtk git show            # Compact show (80%)
rtk git add             # Ultra-compact confirmations (59%)
rtk git commit          # Ultra-compact confirmations (59%)
rtk git push            # Ultra-compact confirmations
rtk git pull            # Ultra-compact confirmations
rtk git branch          # Compact branch list
rtk git fetch           # Compact fetch
rtk git stash           # Compact stash
rtk git worktree        # Compact worktree

Note: Git passthrough works for ALL subcommands, even those not explicitly listed.

GitHub (26-87% savings)

rtk gh pr view <num>    # Compact PR view (87%)
rtk gh pr checks        # Compact PR checks (79%)
rtk gh run list         # Compact workflow runs (82%)
rtk gh issue list       # Compact issue list (80%)
rtk gh api              # Compact API responses (26%)

JavaScript/TypeScript Tooling (70-90% savings)

rtk pnpm list           # Compact dependency tree (70%)
rtk pnpm outdated       # Compact outdated packages (80%)
rtk pnpm install        # Compact install output (90%)
rtk npm run <script>    # Compact npm script output
rtk npx <cmd>           # Compact npx command output
rtk prisma              # Prisma without ASCII art (88%)

Files & Search (60-75% savings)

rtk ls <path>           # Tree format, compact (65%)
rtk read <file>         # Code reading with filtering (60%)
rtk grep <pattern>      # Search grouped by file (75%). Format flags (-c, -l, -L, -o, -Z) run raw.
rtk find <pattern>      # Find grouped by directory (70%)

Analysis & Debug (70-90% savings)

rtk err <cmd>           # Filter errors only from any command
rtk log <file>          # Deduplicated logs with counts
rtk json <file>         # JSON structure without values
rtk deps                # Dependency overview
rtk env                 # Environment variables compact
rtk summary <cmd>       # Smart summary of command output
rtk diff                # Ultra-compact diffs

Infrastructure (85% savings)

rtk docker ps           # Compact container list
rtk docker images       # Compact image list
rtk docker logs <c>     # Deduplicated logs
rtk kubectl get         # Compact resource list
rtk kubectl logs        # Deduplicated pod logs

Network (65-70% savings)

rtk curl <url>          # Compact HTTP responses (70%)
rtk wget <url>          # Compact download output (65%)

Meta Commands

rtk gain                # View token savings statistics
rtk gain --history      # View command history with savings
rtk discover            # Analyze Claude Code sessions for missed RTK usage
rtk proxy <cmd>         # Run command without filtering (for debugging)
rtk init                # Add RTK instructions to CLAUDE.md
rtk init --global       # Add RTK to ~/.claude/CLAUDE.md

Token Savings Overview

Category Commands Typical Savings
Tests vitest, playwright, cargo test 90-99%
Build next, tsc, lint, prettier 70-87%
Git status, log, diff, add, commit 59-80%
GitHub gh pr, gh run, gh issue 26-87%
Package Managers pnpm, npm, npx 70-90%
Files ls, read, grep, find 60-75%
Infrastructure docker, kubectl 85%
Network curl, wget 65-70%

Overall average: 60-90% token reduction on common development operations.