diff --git a/AGENTS.md b/AGENTS.md
index 9657ef47c..4001fc80b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -207,6 +207,27 @@ Two manifest variants exist:
 - **Standard:** Production-ready features
 - **Experimental:** Features under development/testing (includes `ClusterObjectSet` API)
 
+### API Conventions
+
+API changes in `api/v1/*_types.go` must follow the [OpenShift API conventions](https://github.com/openshift/enhancements/blob/master/dev-guide/api-conventions.md) in addition to upstream [Kubernetes API conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md).
+
+After modifying API types, run `make manifests crd-ref-docs` to regenerate CRDs, reference docs, and manifests. Run `make lint-api-diff` to validate changes against kube-api-linter.
+
+**Deprecating fields:** Follow Go and OpenShift conventions (see [openshift/api](https://github.com/openshift/api) for examples):
+
+```go
+// Deprecated: fieldName is no longer used and will be removed in a future release.
+// Explanation of why and what replaces it.
+//
+// +optional
+FieldName Type `json:"fieldName,omitzero"`
+```
+
+- Use `Deprecated:` with capital D and colon (Go convention, recognized by godoc and staticcheck)
+- Deprecated fields must be `+optional`, never `+required`
+- Add `omitzero` (structs) or `omitempty` (scalars) to JSON tags
+- For intentional reads of deprecated fields (e.g. deprecation warnings), add `//nolint:staticcheck` with a reason
+
 ---
 
 ## Git Workflows