diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index adc5d16..b645649 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -7,8 +7,8 @@ Testkit is a Go module providing a modular builder framework to streamline test
 ## Working Effectively
 
 ### Bootstrap and Dependencies
-- Ensure Go 1.26.0+ is installed
-- `cd /home/runner/work/testkit/testkit` (repository root)
+- Ensure Go 1.26.2+ is installed
+- Work from the repository root
 - `go mod tidy` -- downloads and organizes dependencies (takes ~2 seconds)
 - `go mod download` -- ensures all dependencies are available
 
@@ -151,7 +151,7 @@ pkg/test/       -- main library package (builder.go, examples.go, factory.go, do
 ```go
 module github.com/rios0rios0/testkit
 
-go 1.26.0
+go 1.26.2
 ```
 
 ### Example Application Output
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e4e5890..af1faf4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,14 @@ Exceptions are acceptable depending on the circumstances (critical bug fixes tha
 
 ## [Unreleased]
 
+### Added
+
+- added `CLAUDE.md` with project guidance for Claude Code sessions
+
+### Changed
+
+- refreshed `.github/copilot-instructions.md` to reflect Go 1.26.2 version requirement
+
 ## [0.1.2] - 2026-04-15
 
 ### Changed
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..4a9023e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,46 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+Go testing utility library (`github.com/rios0rios0/testkit`). Provides a modular builder framework for test environment setup. Pure library -- no deployable artifacts. Requires Go 1.26.2+.
+
+## Commands
+
+```bash
+go build ./...              # build all packages
+go test ./... -v            # run all tests
+go fmt ./...                # format (required before commit)
+go vet ./...                # static analysis (required before commit)
+golangci-lint run ./...     # lint (matches CI)
+go run cmd/example/main.go  # run example app -- use to validate changes
+```
+
+The `Makefile` pulls shared targets from `rios0rios0/pipelines` via `$SCRIPTS_DIR`. Use `go` commands directly for local development.
+
+## Architecture
+
+All library code is in `pkg/test/` (Go package name: `testkit`).
+
+| File | Purpose |
+|------|---------|
+| `builder.go` | `BaseBuilder` struct and `Builder` interface |
+| `factory.go` | `BuilderFactory`, `BuilderConfig`, global registry |
+| `examples.go` | `UserBuilder` reference implementation, `TestUser` entity |
+| `doc.go` | Package-level documentation |
+
+Tests live in the same package (`package testkit`) for internal field access.
+
+## Conventions
+
+- Custom builders embed `*BaseBuilder` and implement `Builder` (`Build`, `Reset`, `Clone`).
+- `With*` methods return the builder (method chaining).
+- Validation guards with `IsValidationEnabled()`; errors accumulate via `AddError()` and surface from `Build()`.
+- `Build()` returns a defensive copy of the entity.
+- Builders are not thread-safe.
+- Update `CHANGELOG.md` under `[Unreleased]` for user-facing changes.
+
+## CI
+
+`.github/workflows/default.yaml` delegates to `rios0rios0/pipelines/.github/workflows/go-library.yaml`. Runs on push/PR to `main` and tags.