docs: add CLAUDE.md and update .gitignore

.gitignore

@@ -1,2 +1,3 @@
 .idea
+.claude
 /release

CLAUDE.md

@@ -0,0 +1,33 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This is a Go library providing cursor-based pagination utilities for GraphQL Relay-style pagination. It handles cursor encoding/decoding (base64) and page extraction with `first/after` and `last/before` parameters.
+
+## Commands
+
+```bash
+# Run all tests
+go test ./...
+
+# Run tests with race detection and coverage (as in CI)
+CGO_ENABLED=1 go test -race -coverprofile=coverage.txt -covermode=atomic ./...
+
+# Run a single test
+go test -run TestGetPage ./...
+
+# Lint
+golangci-lint run
+
+# Check for vulnerabilities
+govulncheck ./...
+```
+
+## Architecture
+
+Single-package library with:
+- `pagination.go` - Core functions: `Validate`, `GetPage`, `EncodeCursor`, `DecodeCursor`, and `PageInfo` struct
+- Cursors are base64-encoded strings
+- `GetPage` is generic and works with any type via a cursor extraction function