From e6142645974588c82874c5b50273b108d8dad197 Mon Sep 17 00:00:00 2001 From: Jan Novak Date: Fri, 7 Aug 2026 20:37:08 +0200 Subject: [PATCH] Require exact command snippets in plan execution summaries The Step 0 entry described what happened in prose but omitted the actual kubebuilder/go install invocations, which is exactly the detail a future reader would want to copy and reproduce. Codifies "include the real command line, not a paraphrase" in CLAUDE.md and rewrites the Step 0 entry with the exact commands run, including the go install path correction (kubebuilder v4.15.0 is the module root now, not .../cmd/kubebuilder) and the controller-gen invocations kubebuilder ran on its own. Co-Authored-By: Claude --- CLAUDE.md | 15 +++- .../2026-08-07-1747-proxy-operator.md | 80 ++++++++++++++++--- 2 files changed, 80 insertions(+), 15 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3900081..1224782 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -104,11 +104,20 @@ originating plan in `docs/plans/`, so the two files pair up 1:1. Create the file section per step after that, in chronological order (bottom of the file), not newest-first like `CHANGELOG.md`. -Keep each entry light — a few sentences on what was done, plus anything genuinely +Keep the prose light — a few sentences on what was done, plus anything genuinely interesting or non-obvious about how it went (a judgment call made, a spec gap found, something that didn't work as expected). This is not a duplicate of the plan or the -diff; skip steps that went exactly as planned with nothing worth flagging. Commit the -summary update together with that step's implementation commit. +diff; skip steps that went exactly as planned with nothing worth flagging. + +**Include exact commands.** Any invocation of an external tool that isn't a plain file +edit — CLI scaffolding tools (`kubebuilder`, code generators), package installs, other +non-obvious shell commands — goes in as a fenced code block with the exact +command-line actually run, not a paraphrase. Prefer the real invocation over a +description of it; a future reader (or a future Claude) should be able to copy the +snippet and reproduce the step. Trim noisy stdout, but keep anything that changed the +outcome (a flag that mattered, an unexpected error, a version that got picked +automatically). Commit the summary update together with that step's implementation +commit. ### Changelog diff --git a/docs/plans-executions/2026-08-07-1747-proxy-operator.md b/docs/plans-executions/2026-08-07-1747-proxy-operator.md index b0b81d6..d5c8174 100644 --- a/docs/plans-executions/2026-08-07-1747-proxy-operator.md +++ b/docs/plans-executions/2026-08-07-1747-proxy-operator.md @@ -4,16 +4,72 @@ Pairs with [docs/plans/2026-08-07-1747-proxy-operator.md](../plans/2026-08-07-17 ## Step 0 — Branch and scaffold -Branched `feat/proxy-operator` off the unborn `main`, installed kubebuilder v4.15.0 -via `go install`, and ran `kubebuilder init` + `kubebuilder create api` in place. +Branched off the unborn `main`: -Worth noting: `--domain example.com --group crawl` landed on the correct CRD group -(`crawl.example.com`) on the first try — the doubling trap the plan called out -(`--domain crawl.example.com --group crawl` → `crawl.crawl.example.com`) was avoided -by using the right flags from the start. `CONTROLLER_TOOLS_VERSION` came out at -`v0.21.0` by default in this kubebuilder release, so no Makefile edit was needed there. -Dropped the scaffolded `.github/workflows/` since the remote is Gitea. Pre-existing -`CLAUDE.md`/`CHANGELOG.md` content survived untouched; kubebuilder added its own -`README.md`, `AGENTS.md`, `.golangci.yml`, `.devcontainer/`, `Dockerfile` on top — -those get edited or left as-is in later steps. `go build ./...`, `go vet ./...`, and -`make manifests generate` all ran clean. Committed as `076bc66`. +```bash +git checkout -b feat/proxy-operator +``` + +Installed kubebuilder v4.15.0 into a scratch `GOBIN` rather than the default +`$(go env GOPATH)/bin`, since the module's package layout changed and +`go install .../cmd/kubebuilder@v4.15.0` (the path from the plan) 404s — the binary is +now the module root itself: + +```bash +GOBIN=/bin go install sigs.k8s.io/kubebuilder/v4@v4.15.0 +``` + +Scaffolded in place, with `kubebuilder` on `PATH`: + +```bash +kubebuilder version +# KubeBuilder: v4.15.0, Kubernetes: 1.36.0 + +kubebuilder init --domain example.com \ + --repo gitea.home.hrajfrisbee.cz/kacerr/egress-proxies-operator --plugins go/v4 +# WARN: target directory not empty (expected — CLAUDE.md, docs/, .claude/ already existed) + +kubebuilder create api --group crawl --version v1alpha1 --kind Proxy \ + --resource --controller +``` + +`create api` auto-ran `make manifests` at the end, which pulled and ran +`controller-gen` itself: + +```bash +sigs.k8s.io/controller-tools/cmd/controller-gen@v0.21.0 +"$(bin)/controller-gen" object:headerFile="hack/boilerplate.go.txt",year=2026 paths="./..." +``` + +Confirmed the CRD group landed correctly (no doubling — `--domain example.com +--group crawl` was used specifically to avoid the `crawl.crawl.example.com` trap +called out in the plan): + +```bash +grep -A2 "GroupVersion =" api/v1alpha1/groupversion_info.go +# SchemeGroupVersion = schema.GroupVersion{Group: "crawl.example.com", Version: "v1alpha1"} +``` + +Dropped the scaffolded GitHub Actions workflows (remote is Gitea, not GitHub): + +```bash +git rm -r --cached .github 2>/dev/null; rm -rf .github +``` + +Ran the full manifest/codegen pass once more to confirm the toolchain is reproducible +end to end: + +```bash +make manifests generate +# controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases +# controller-gen object:headerFile="hack/boilerplate.go.txt",year=2026 paths="./..." +``` + +then `go build ./...` and `go vet ./...`, both clean with no output. + +Worth noting: `CONTROLLER_TOOLS_VERSION` in the generated `Makefile` came out at +`v0.21.0` by default in this kubebuilder release, so the Makefile edit the plan +anticipated wasn't needed. Pre-existing `CLAUDE.md`/`CHANGELOG.md` content survived +untouched; kubebuilder added its own `README.md`, `AGENTS.md`, `.golangci.yml`, +`.devcontainer/`, `Dockerfile` on top of them — those get edited or left as-is in +later steps. Committed as `076bc66`.