What happened
The code agent on PR #356 renamed JSON serialization tags from resendWait to resendInterval on FleetNotification.ResendWait and NotificationRecordByName.ResendWait CRD types (commit d6366cb). This was a backward-incompatible CRD schema change — existing custom resources stored in etcd would fail validation, and FiringCanBeSent would zero-default, causing notification spam. The review agent (run 33465133921) correctly caught this as 2 critical findings and the fix agent reverted the change, but the initial error cost ~$8.54 in review + fix compute and ~32 minutes of wall-clock time.
What could go better
CLAUDE.md has constraints about generated files ("Never edit deploy/crds/*.yaml") and architectural boundaries ("API Types are pure data structures"), but nothing about CRD API backward compatibility. The code agent had no guidance that renaming JSON/YAML serialization tags on existing CRD types is a breaking change that requires a conversion webhook or migration strategy. With an explicit constraint, the code agent would have avoided the rename entirely and the review+fix cycle would not have been needed. Confidence: high — the agent's commit message shows it believed the rename was a straightforward fix, not a breaking change.
Proposed change
Add a CRD backward compatibility constraint to the Agents MUST section of CLAUDE.md, in the "Repo-Specific Constraints" or "Architectural Boundaries" area:
### CRD API Stability
- **Never rename JSON/YAML serialization tags** on existing CRD types (`api/v1alpha1/`) — this is a backward-incompatible schema change that breaks existing custom resources stored in etcd
- **Never remove or rename required fields** from CRD specs or status types
- If a field rename is genuinely needed, it requires a conversion webhook or explicit documentation that no existing resources use the old schema
- When in doubt, preserve the existing JSON tag and add a comment explaining the naming discrepancy
Validation criteria
The next 3 code agent runs on this repo that touch api/v1alpha1/ types should not attempt JSON tag renames or backward-incompatible CRD schema changes without proposing a migration strategy. If a Jira issue requests a field rename, the code agent should preserve backward compatibility and explain the constraint in its PR description.
Generated by retro agent from #357
What happened
The code agent on PR #356 renamed JSON serialization tags from
resendWaittoresendIntervalonFleetNotification.ResendWaitandNotificationRecordByName.ResendWaitCRD types (commit d6366cb). This was a backward-incompatible CRD schema change — existing custom resources stored in etcd would fail validation, andFiringCanBeSentwould zero-default, causing notification spam. The review agent (run 33465133921) correctly caught this as 2 critical findings and the fix agent reverted the change, but the initial error cost ~$8.54 in review + fix compute and ~32 minutes of wall-clock time.What could go better
CLAUDE.md has constraints about generated files ("Never edit deploy/crds/*.yaml") and architectural boundaries ("API Types are pure data structures"), but nothing about CRD API backward compatibility. The code agent had no guidance that renaming JSON/YAML serialization tags on existing CRD types is a breaking change that requires a conversion webhook or migration strategy. With an explicit constraint, the code agent would have avoided the rename entirely and the review+fix cycle would not have been needed. Confidence: high — the agent's commit message shows it believed the rename was a straightforward fix, not a breaking change.
Proposed change
Add a CRD backward compatibility constraint to the
Agents MUSTsection ofCLAUDE.md, in the "Repo-Specific Constraints" or "Architectural Boundaries" area:Validation criteria
The next 3 code agent runs on this repo that touch
api/v1alpha1/types should not attempt JSON tag renames or backward-incompatible CRD schema changes without proposing a migration strategy. If a Jira issue requests a field rename, the code agent should preserve backward compatibility and explain the constraint in its PR description.Generated by retro agent from #357