diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..4359cd7
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,30 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This repository builds a Docker image for running pre-commit hooks in CI/CD pipelines. The image is based on Go and includes Python (via pipx), Ruby, and common development tools like goimports and go-pre-commit.
+
+## Build Commands
+
+The project uses GitLab CI with custom templates:
+- Build and push are handled by the `build` and `push` commands from the `buildtool/build-tools` image
+- No local Makefile; builds run in CI pipeline
+
+## Release Process
+
+Releases use git-cliff for changelog generation:
+```bash
+git cliff -o CHANGELOG.md
+```
+
+Version is stored in `.version` as JSON: `{"version":"vX.Y.Z"}`
+
+## Conventional Commits
+
+This project uses conventional commits. Commit types:
+- `feat`: New features
+- `fix`: Bug fixes
+- `chore`: Maintenance tasks (deps, CI)
+- `docs`, `perf`, `refactor`, `style`, `test`: As standard