Skip to content

Improve CLAUDE.md: add project-specific AI guidelines, remove global duplication #10

@alexei-led

Description

@alexei-led

Summary

Current CLAUDE.md is decent but contains some generic Go advice already in global config. Needs more spotinfo-specific patterns.

What to Add

Data Update Workflow

## Data Sources & Updates

The embedded data files are critical — they provide offline capability:
- `internal/spot/data/spot-advisor-data.json` — Interruption rates, savings % (from AWS S3)
- `internal/spot/data/spot.js` — Static spot pricing (from AWS S3, wrapped in JS callback)

**Update flow:**
1. `make update-data` → downloads fresh spot-advisor-data.json
2. `make update-price` → downloads fresh spot.js
3. Commit updated data files
4. `make all` → rebuilds binary with new embedded data

**Important:** Data files are committed to git — they ARE the offline fallback. Always update both together.

Live Price Fallback

## Live Price Fallback (`liveprice.go`)

When static pricing shows $0 for newer instance types:
1. Falls back to EC2 DescribeSpotPriceHistory API
2. Requires valid AWS credentials
3. Queries last 24h of pricing data
4. Returns latest price per AZ

This is the most complex code path — test with both mocked and real API.

MCP Integration

## MCP Server (`internal/mcp/`)

spotinfo has an MCP server mode for AI assistant integration.
- Separate from CLI — started with different entry point
- Exposes spot data as MCP tools
- If modifying: follow patterns from aws-mcp-server and k8s-mcp-server

Testing Notes

## Testing Notes

- Tests use testify (assertions + require)
- Tests run in parallel (`t.Parallel()`) — ensure no shared state
- **Resilient to data changes:** Tests should NOT hardcode specific prices or instance types from embedded data — AWS updates these feeds regularly
- **Coverage:** `make test-coverage` generates HTML report
- **Race detector:** `make test-race` — always run before PR

CI/CD Specifics

## CI/CD

- **Auto-release:** Quarterly (Jan/Apr/Jul/Oct) via `auto-release.yaml` — smart change detection
- **Docker:** Multi-arch via buildx, published to ghcr.io
- **Release trigger:** Push tag starting with `v` (e.g., `git tag v1.2.3 && git push origin v1.2.3`)
- **Default branch:** `master`
- NEVER add AI co-author to git commits

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions