Skip to main content

Claude Code Best Practices Guide

This document lists operational best practices for using Claude Code via:

  • Claude Code VS Code Extension
  • Claude Code CLI with an AI API Gateway

 

Security Best Practices

  • Treat API keys like passwords
    • Never paste keys into tickets, chats, or code repositories.
    • Prefer secure sharing (password manager / approved secure channel).
  • Avoid committing local config files
    • Do not commit ~/.claude/settings.json or any file that contains keys.
    • If you create project-level docs, include placeholders only.
  • Rotate keys if exposed
    • If a key appears in logs, shell history, or a repo, rotate immediately.
  • Minimize accidental disclosure
    • Be careful when screen-sharing terminals and VS Code settings.

 

Gateway + Model Alias Best Practices (AI API Gateway / LiteLLM)

  • Use the correct Base URL format
    • Best practice: set the base URL to the root host, not .../v1
      • Example (correct): https://aiapi-dev.stanford.edu
      • Example (wrong): https://aiapi-dev.stanford.edu/v1
  • Always use exact model aliases
    • Claude Code requires the model string to match the gateway alias exactly
    • Confirm availability with:

shell

curl -s https://aiapi-dev.stanford.edu/v1/models \
-H "Authorization: Bearer YOUR_AIAPI_KEY"
  • Standardize aliases across teams
    • Pick a small set of blessed aliases (e.g.,claude-4-sonnet/claude-opus-4-6) to reduce "invalid model" errors.

 

Claude Code Settings Best Practices (~/.claude/settings.json)

  • Keep one canonical global config per user
    • Store gateway routing and key in ~/.claude/settings.json
    • Avoid scattering keys across multiple tools if possible.
    • Use recommended compatibility flags
    • Include these to avoid gateway incompatibilities:

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

DISABLE_PROMPT_CACHING=1

Recommended template:

shell

{
    "$schema": "https://json.schemastore.org/claude-code-settings.json",
   "env": {
     "ANTHROPIC_BASE_URL": 
"https://aiapi-dev.stanford.edu",
     "ANTHROPIC_AUTH_TOKEN": "YOUR_AIAPI_KEY",
     "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
     "DISABLE_PROMPT_CACHING": "1"
  }
}

 

VS Code Extension Best Practices

  • Restart VS Code after config changes
    • Best practice: fully quit VS Code and reopen after editing:
      • ~/.claude/settings.json
      • VS Code settings.json
  • Keep prompts and workspace boundaries clear
    • Open the correct folder/workspace before requesting file edits.
    • Prefer explicit instructions like: "Create src/foo.ts and update package.json".
  • Review changes before you commit
    • Use git diff (or VS Code source control) to review AI-made changes.

 

CLI Best Practices

Always specify the model alias

  • Best practice:

shell

claude --model claude-4-sonnet/claude-opus-4-6

Avoid relying on defaults, which may differ by environment.

Available Models

  • Use CLI for quick checks and experiments
    • CLI is ideal for connectivity tests, quick refactors, or validating gateway/model availability before debugging VS Code.
  • Be mindful of shell history
    • Don't paste API keys directly into terminal commands.
    • Keep the key in ~/.claude/settings.json rather than exporting it inline.

 

Reliability / Debugging Best Practices

  • Start with a minimal connectivity prompt
    • "Say OK" (or "Reply only with CONNECTED") is a good smoke test.
  • If errors occur, isolate the layer
    • Test CLI first (removes VS Code factors)
    • Test VS Code extension next
    • Validate model alias using /v1/models
  • Common error interpretation
    • 401/403: key missing/invalid/unauthorized
    • 404 / model not found: bad alias or wrong endpoint
    • timeout/network: VPN/proxy/firewall/base URL unreachable
    • header-related: missing recommended flags in settings
Last modified