docs: add CLAUDE.md with repository guidance

Add project memory documenting build/test/lint commands, architecture, and
conventions to orient Claude Code and other AI coding agents in this repo.

Signed-off-by: Sergiy Kulanov <sergiy_kulanov@epam.com>

Author: SergK

CLAUDE.md

@@ -0,0 +1,83 @@
+# edp-sonar-operator
+
+`github.com/epam/edp-sonar-operator` — a Go kubebuilder operator that configures an **existing** SonarQube instance declaratively via Kubernetes CRDs. It does not install SonarQube; it reconciles its state. Quality gates defined here are the blocking gates enforced in every KRCI Tekton CI pipeline.
+
+CRD group: `edp.epam.com/v1alpha1` — `Sonar`, `SonarProject`, `SonarQualityGate`, `SonarQualityProfile`, `SonarUser`, `SonarGroup`, `SonarPermissionTemplate`.
+
+## Build & Test
+
+```bash
+make build          # fmt + vet + compile → dist/manager-<arch>
+make test           # unit + envtest integration tests (downloads envtest binaries on first run)
+make lint           # golangci-lint (config: .golangci.yaml)
+make lint-fix       # golangci-lint with auto-fix
+```
+
+Run a single test package:
+
+```bash
+go test ./internal/controller/qualitygate/... -v
+```
+
+Integration tests against a live SonarQube (optional):
+
+```bash
+TEST_SONAR_URL=http://localhost:9000 TEST_SONAR_USER=admin TEST_SONAR_PASSWORD=admin make test
+```
+
+## Code Generation
+
+After editing kubebuilder markers in `api/v1alpha1/` or controller RBAC comments:
+
+```bash
+make generate     # regenerates DeepCopy methods (zz_generated.deepcopy.go)
+make manifests    # regenerates CRDs → deploy-templates/crds/ and config/crd/bases/, also runs api-docs
+make mocks        # regenerates mockery mocks in pkg/client/sonar/mocks/
+```
+
+CRD YAML files in `deploy-templates/crds/` and `config/crd/bases/` are generated — do not edit manually. Same for `api/v1alpha1/zz_generated.deepcopy.go` and `api/common/zz_generated.deepcopy.go`.
+
+## Architecture
+
+```
+cmd/main.go
+  └── creates controller-runtime Manager, registers all 7 reconcilers
+
+api/v1alpha1/          — CRD type definitions (spec, status, kubebuilder markers)
+api/common/            — shared SonarRef and HasSonarRef interface
+
+internal/controller/<resource>/
+  ├── sonar*_controller.go  — Reconcile() entry: fetches CR, resolves Sonar client,
+  │                           delegates to chain; handles finalizer + deletion
+  └── chain/
+      ├── chain.go           — handler interface + sequential chain runner
+      ├── factory.go         — MakeChain() wires handlers in order
+      ├── create_*.go        — idempotent create/update step
+      ├── sync_*.go          — sync sub-resources (conditions, rules, groups, perms)
+      └── remove_*.go        — deletion step (invoked on DeletionTimestamp)
+
+pkg/client/sonar/
+  ├── sonar.go               — Client struct (resty-based), base HTTP methods
+  ├── client_interface.go    — ClientInterface composed of sub-interfaces (hand-written, NOT generated)
+  ├── quality_gate.go        — QualityGateClient methods
+  ├── quality_profile.go     — QualityProfileClient methods
+  ├── group.go / user.go / project.go / permission_template.go / rule.go / system.go
+  ├── provider.go            — ApiClientProvider: resolves Client from Sonar CR + K8s Secret
+  └── mocks/                 — mockery-generated mocks (do not edit)
+
+deploy-templates/      — Helm chart (values.yaml, crds/, templates/); README auto-generated by helm-docs
+config/                — Kustomize manifests (crd, rbac, manager, webhook, certmanager, prometheus)
+bundle/                — OLM bundle manifests for OperatorHub
+```
+
+## Key Conventions
+
+**SonarRef dependency model.** Every child CR (`SonarQualityGate`, `SonarUser`, etc.) has a `spec.sonarRef.name` pointing to a `Sonar` CR. Reconcilers call `ApiClientProvider.GetSonarApiClientFromSonarRef`, which checks `sonar.Status.Connected == true` before building the HTTP client. If the parent `Sonar` is not yet connected, the child requeues after 30 s.
+
+**Chain of responsibility.** Each controller delegates work to a `chain.MakeChain(sonarApiClient)` call. To add a new reconciliation step, implement `ServeRequest(ctx, *sonarApiCRType) error` and append it in `chain/factory.go`. All handlers are tested individually with mock clients.
+
+**SonarQube REST client is hand-written, not generated.** `pkg/client/sonar/sonar.go` and sibling files wrap resty with idiomatic Go. `ClientInterface` in `client_interface.go` is the composition interface used by all chain handlers. Mocks in `mocks/` are generated from `ClientInterface` via mockery (`.mockery.yaml`).
+
+**Credentials.** The `Sonar` CR's `spec.secret` names a K8s Secret with `user` and `password` keys. The client is constructed with basic auth against `spec.url`.
+
+**Name field is immutable post-creation.** `SonarQualityGate.spec.name` (and analogous fields on other CRDs) drives the SonarQube resource name. Changing it after creation causes the old resource to be deleted and a new one created.