diff --git a/.gitignore b/.gitignore
index 9ada4d7..7d212e5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 .idea
+.claude
 /release
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..29f86f6
--- /dev/null
+++ b/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