docs: Claude - add review agents and CVE triage context#3254
Conversation
Introduces CLAUDE.md with module layout, make targets, single-test commands, KCP/SKR architecture, module installation flow, architectural guardrails, security guardrails, and links to agent_docs/ depth files. Adds .claude/rules/go-conventions.md (loads on *.go): points to .golangci.yaml as source of truth, documents nolint policy and FIPS constraint that are not machine-enforceable. Adds agent_docs/ depth files (architecture, reconcilers, CRD conventions, testing, codegen) for on-demand context beyond CLAUDE.md budget. Adds docs/CLAUDE.md with documentation writing style and templates. Adds CI gate (.github/workflows/check-generated-code.yml) that blocks PRs where generated files (CRD YAML, deepcopy) are out of sync with api/ types.
Adds two complementary review agents: - operator-reviewer (Sonnet): checklist-based compliance review for reconciler changes, CRD types, finalizers, SKR context lifecycle. - principal-engineer (Opus): design-level judgment — abstraction fitness, architectural fit, observability, error philosophy, maintainability. Adds .claude/cve-triage/context.md covering three CVE surfaces: container image (BDBA), Go module SCA (Mend), and Go SAST (Checkmarx). Includes FIPS constraint on crypto fixes and Checkmarx false-positive patterns specific to Kubernetes operators.
medmes
changed the title
c-pius
left a comment
c-pius
left a comment
There was a problem hiding this comment.
Overall I think this is too broad already. I would like to rather add specific configs step by step as we see need for them.
There was a problem hiding this comment.
We could do this, but I see this independent of Claude configs
There was a problem hiding this comment.
This I would rather see as hook preventing changes on config/crd/bases. Maybe also a rule on api/* instructing to regenerate after changes.
There was a problem hiding this comment.
Not entirely sure if super relevant, but this should be either a rule on api/*, or a dedicated CLAUE.md at api/
There was a problem hiding this comment.
Also not sure if too extensive already, but should be a rule on internal/controller/* or a seperate CLAUDE.md there
There was a problem hiding this comment.
Maybe also too extensive already. If provided, should be separate into different rules applying to **/*_test.go and tests.
There was a problem hiding this comment.
There was a problem hiding this comment.
Maybe a skill? Not entirely sure about it. I think something like this should be aligned with our sec team. Ideally, they should provide a skill supporting triaging that we can re-use. Same as with documentation.
There was a problem hiding this comment.
Not sure about this one. I think parts of it are not entirely correct. Also some things are general topics and high level covered in the existing CLAUDE.md, not specific to the reconcilers. Also some things I see not as entirely relevant for the reconcilers. I would not continue with this one.
There was a problem hiding this comment.
May be reasonable. We could try it out.
2 participants
Description
Depends on #3253 — review that one first.
Adds
operator-revieweragent (Sonnet, read-only): 9-section compliance checklist for reconciler changes, CRD types, finalizers, SKR context lifecycleAdds
principal-engineeragent (Opus, read-only): design-level judgment — abstraction fitness, architectural fit, observability, error philosophy, maintainabilityAdds
.claude/cve-triage/context.mdcovering three CVE surfaces: container image (BDBA), Go module SCA (Mend), and Go SAST (Checkmarx), with FIPS constraint on crypto fixesInvoke
operator-revieweron a sample reconciler change and verify structured outputInvoke
principal-engineeron a design decision and verify Opus model is usedCVE triage context covers all three scanner types from
sec-scanners-config.yamlRelated issue:
#3241