From 7d14b3845b859af2f2282f565f1c040898adc7f6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tibor=20=C5=A0imko?= <tibor.simko@cern.ch>
Date: Thu, 27 Nov 2025 14:27:57 +0100
Subject: [PATCH] docs(claude): add initial Claude Code configuration (#164)

---
 .gitignore |  3 ++
 CLAUDE.md  | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/.gitignore b/.gitignore
index b74353a..e469103 100644
--- a/.gitignore
+++ b/.gitignore
@@ -106,3 +106,6 @@ venv.bak/
 
 # _cache folder with archived websites
 cache
+
+# Claude Code
+.claude
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..5c94aab
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+This file provides guidance for Claude Code when working with this repository.
+
+## Project Overview
+
+`cernopendata-client` is a command-line tool to download files from the CERN
+Open Data portal. It enables querying datasets and downloading/verifying
+individual data files.
+
+## Development Setup
+
+```bash
+# Using mise (recommended) - installs Python versions 3.8-3.14
+mise install
+
+# Create virtual environment and install in editable mode
+python3 -m venv env
+source env/bin/activate
+pip install -e '.[tests]'
+```
+
+## Testing and Code Quality
+
+The project uses `run-tests.sh` for all quality checks. Run all checks with:
+
+```bash
+./run-tests.sh
+```
+
+### Individual Check Commands
+
+| Command                              | Description                            |
+| ------------------------------------ | -------------------------------------- |
+| `./run-tests.sh --python-tests`      | Run pytest test suite                  |
+| `./run-tests.sh --format-black`      | Check Python formatting (black)        |
+| `./run-tests.sh --lint-flake8`       | Lint Python code (flake8)              |
+| `./run-tests.sh --lint-pydocstyle`   | Check Python docstrings                |
+| `./run-tests.sh --format-prettier`   | Check Markdown/YAML formatting         |
+| `./run-tests.sh --format-shfmt`      | Check shell script formatting          |
+| `./run-tests.sh --lint-shellcheck`   | Lint shell scripts                     |
+| `./run-tests.sh --lint-markdownlint` | Lint Markdown files                    |
+| `./run-tests.sh --lint-yamllint`     | Lint YAML files                        |
+| `./run-tests.sh --lint-jsonlint`     | Lint JSON files                        |
+| `./run-tests.sh --lint-commitlint`   | Check commit message format            |
+| `./run-tests.sh --lint-manifest`     | Check Python manifest (check-manifest) |
+| `./run-tests.sh --docs-sphinx`       | Build and test Sphinx documentation    |
+| `./run-tests.sh --docker-build`      | Build Docker image                     |
+| `./run-tests.sh --docker-tests`      | Run tests in Docker container          |
+| `./run-tests.sh --lint-hadolint`     | Lint Dockerfile                        |
+
+### Using tox for Multi-Python Testing
+
+```bash
+tox           # Run tests across all Python versions (3.8-3.14)
+tox -e py312  # Run tests for specific Python version
+```
+
+## Project Structure
+
+- `cernopendata_client/` - Main Python package
+  - `cli.py` - Command-line interface (Click-based)
+  - `downloader.py` - File download functionality
+  - `searcher.py` - Dataset search functionality
+  - `verifier.py` - File verification
+  - `validator.py` - Input validation
+  - `metadater.py` - Metadata handling
+  - `config.py` - Configuration
+  - `printer.py` - Output formatting
+  - `utils.py` - Utility functions
+  - `walker.py` - Directory traversal
+- `tests/` - Test suite
+- `docs/` - Sphinx documentation
+
+## Code Style
+
+- Python formatting: black
+- Python linting: flake8
+- Docstrings: pydocstyle (ignores D413, D301)
+- Commit messages: conventional commits (commitlint)
+- Shell scripts: shellcheck + shfmt
+- Markdown/YAML/JSON: prettier + markdownlint + yamllint + jsonlint
+
+## Key Notes
+
+- License: GPLv3
+- Python support: 3.8 - 3.14
+- Main branch: `master`