Skip to content

CLAUDE.md

Latest commit

 

History

History
70 lines (55 loc) · 3.77 KB

CLAUDE.md

File metadata and controls

70 lines (55 loc) · 3.77 KB

EasyPost Agent Toolkit — Claude Code Guidance

Reading Order

  1. CLAUDE.md (this file) — dispatch rules and code generation standards
  2. AGENTS.md — security rules, API constraints, decision trees
  3. skills/easypost/SKILL.md — core domain knowledge (API-first, single source of truth)
  4. skills/easypost/references/ — deep-dive guides for complex flows
  5. skills/easypost/sdk-hints/{language}.md — concise SDK patterns for the user's language

Detecting User's Language

Determine the user's language from context (file extensions, imports, explicit mention). Route to the correct sdk-hint:

Language SDK Hint File
Python sdk-hints/python.md
Node.js / TypeScript sdk-hints/nodejs.md
Ruby sdk-hints/ruby.md
PHP sdk-hints/php.md
Java / Kotlin sdk-hints/java.md
C# / .NET sdk-hints/csharp.md
Go sdk-hints/go.md
curl / HTTP sdk-hints/curl.md

If the language is unclear, ask the user.

Task Router

User Intent Reference SDK Hint
Create shipment / buy label references/shipment-lifecycle.md sdk-hints/{lang}.md
Compare rates / cheapest rate references/rate-shopping.md sdk-hints/{lang}.md
SmartRate / delivery estimates references/rate-shopping.md sdk-hints/{lang}.md
Luma Promise / Select / Insights references/luma-smartrate.md sdk-hints/{lang}.md
Batch labels / bulk shipping references/batch-operations.md sdk-hints/{lang}.md
Track package references/shipment-lifecycle.md sdk-hints/{lang}.md
Verify address references/address-verification.md sdk-hints/{lang}.md
International / customs references/international-customs.md sdk-hints/{lang}.md
Tax identifiers (IOSS, EORI, etc.) references/tax-identifiers.md sdk-hints/{lang}.md
Insurance references/shipment-lifecycle.md sdk-hints/{lang}.md
Refund shipment references/shipment-lifecycle.md sdk-hints/{lang}.md
Carrier accounts references/carrier-accounts.md sdk-hints/{lang}.md
Webhooks references/webhooks-events.md sdk-hints/{lang}.md
Multi-parcel order references/batch-operations.md sdk-hints/{lang}.md
API endpoints / HTTP reference references/api-endpoints.md sdk-hints/curl.md
Error debugging references/error-handling.md sdk-hints/{lang}.md
Shipping terms / glossary references/support-kb.md —
Migrate from Shippo references/migrate-from-shippo.md sdk-hints/{lang}.md
Migrate from ShipEngine references/migrate-from-shipengine.md sdk-hints/{lang}.md
Migrate from Stamps.com references/migrate-from-stamps.md sdk-hints/{lang}.md
Migrate from ShipStation references/migrate-from-shipstation.md sdk-hints/{lang}.md
Schedule pickup references/pickup-operations.md sdk-hints/{lang}.md
File insurance claim references/claims.md sdk-hints/{lang}.md
EndShipper / platform shipping references/end-shippers.md + references/forge-embeddables.md —
Forge / Embeddables references/forge-embeddables.md —

Code Generation Rules

  1. Always wrap EasyPost calls in try/catch (or language equivalent) — see the error handling pattern in the relevant sdk-hint file.

  2. Use decimal types for money — rate amounts are strings. Never use floating point for money math.

  3. Use environment variables for API keys — never hardcode.

  4. Always check for empty rates — when rates is empty, check messages for rate_error entries.

  5. Convert units before sending — weight in ounces, dimensions in inches.

  6. incoterm goes in options, not customs_info — this is the most common international shipping mistake.