CNTRLPLANE-3718: Add Agentic SDLC context files#363
Conversation
Rename CLAUDE.md to AGENTS.md and add quick-reference sections (critical rules, key patterns, prohibitions, repository layout). CLAUDE.md is now a symlink to AGENTS.md so Claude Code continues to discover it automatically.
- Add ARCHITECTURE.md link to README.md and AGENTS.md - Replace duplicated Architecture section in AGENTS.md with link to ARCHITECTURE.md - Standardize single-test example to TestName across all docs
openshift-ci-robot
added
the
jira/valid-reference
|
@sanchezl: This pull request references CNTRLPLANE-3718 which is a valid jira issue. Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "5.0.0" version, but no target version was set. DetailsIn response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository. |
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
WalkthroughThe PR adds and revises repository documentation for agent instructions, contributing workflow, architecture reference material, and README onboarding/test guidance. It also removes the previous CLAUDE guidance content. ChangesRepository Documentation Refresh
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 15✅ Passed checks (15 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@ARCHITECTURE.md`:
- Around line 29-37: The controller package paths in the architecture table are
inconsistent with the repo layout and should be normalized. Update the Package
column entries to use the actual controller paths from the codebase, especially
the serving cert controller path referenced by starter.go, so the table matches
the navigable package structure. Keep the same controller names, but correct
each package reference to the real `pkg/controller/...` locations used in the
repository.
- Around line 57-65: The CA rotation timeline example is internally inconsistent
because the automated rotation trigger does not line up with the 26-month
lifetime and the “remaining < 13m” condition. Update the timeline in
ARCHITECTURE.md so the rotation point referenced by the example is consistent
with the trigger logic in the signing CA lifetime explanation, either by
changing the trigger threshold or adjusting the T+13m event to reflect when the
condition actually becomes true.
In `@README.md`:
- Line 34: The README link is pointing to the wrong location because the
`enhancements/` path segment is missing from the GitHub URL. Update the existing
documentation link in README so it matches the adjacent link pattern and points
to the correct `openshift/enhancements` path for the “Testing a
ClusterOperator/Operand image in a cluster” section.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository: openshift/coderabbit/.coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 6902ad55-1fe2-40cc-a076-0323fe97b2b5
📒 Files selected for processing (6)
AGENTS.mdARCHITECTURE.mdCLAUDE.mdCLAUDE.mdCONTRIBUTING.mdREADME.md
| | Controller | Package | Watches | Reconciles | | ||
| |-----------|---------|---------|------------| | ||
| | Serving Cert Signer | `servingcert/controller/` | Services, Secrets | Creates TLS Secrets for annotated Services | | ||
| | Serving Cert Updater | `servingcert/controller/` | Services, Secrets | Refreshes certs approaching expiry | | ||
| | ConfigMap CA Injector | `cabundleinjector/configmap.go` | ConfigMaps | Injects CA bundle into annotated ConfigMaps | | ||
| | APIService CA Injector | `cabundleinjector/apiservice.go` | APIServices | Sets `spec.caBundle` on annotated APIServices | | ||
| | Webhook CA Injectors | `cabundleinjector/admissionwebhook.go` | Mutating/ValidatingWebhookConfigs | Sets `caBundle` on annotated webhooks | | ||
| | CRD CA Injector | `cabundleinjector/crd.go` | CRDs | Sets conversion webhook `caBundle` | | ||
| | Legacy Vulnerable Injector | `cabundleinjector/configmap.go` | ConfigMaps named `openshift-service-ca.crt` | Injects legacy bundle for pre-4.7 upgraded clusters | |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Normalize the controller paths.
The package column drops pkg/controller/, and servingcert/controller/ does not match the repo layout. That makes the table harder to use as a navigation aid.
Based on the repo layout in AGENTS.md and pkg/controller/servingcert/starter/starter.go.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@ARCHITECTURE.md` around lines 29 - 37, The controller package paths in the
architecture table are inconsistent with the repo layout and should be
normalized. Update the Package column entries to use the actual controller paths
from the codebase, especially the serving cert controller path referenced by
starter.go, so the table matches the navigable package structure. Keep the same
controller names, but correct each package reference to the real
`pkg/controller/...` locations used in the repository.
| The signing CA has a 26-month lifetime, designed around the 12-month maximum upgrade interval: | ||
|
|
||
| ``` | ||
| T+0m CA-1 created (or rotated) | ||
| T+12m Cluster upgraded, all pods restarted | ||
| T+13m Automated rotation: CA-1 remaining < 13m → CA-2 created | ||
| T+24m Cluster upgraded again, all pods restarted | ||
| T+26m CA-1 expires (no impact — pods already restarted) | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make the rotation example internally consistent.
T+13m conflicts with the preceding remaining < 13m trigger on a 26-month CA. At exactly 13 months remaining, the condition is still false, so the example reads as off by one.
Based on the CA rotation timeline in this file.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 59-59: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@ARCHITECTURE.md` around lines 57 - 65, The CA rotation timeline example is
internally inconsistent because the automated rotation trigger does not line up
with the 26-month lifetime and the “remaining < 13m” condition. Update the
timeline in ARCHITECTURE.md so the rotation point referenced by the example is
consistent with the trigger logic in the signing CA lifetime explanation, either
by changing the trigger threshold or adjusting the T+13m event to reflect when
the condition actually becomes true.
| ### Running in a Cluster | ||
|
|
||
| ### Building the test binary | ||
| See [Testing a ClusterOperator/Operand image in a cluster](https://github.com/openshift/enhancements/blob/master/dev-guide/operators.md#how-can-i-test-changes-to-an-openshift-operatoroperandrelease-component). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the documentation link.
The URL is missing the enhancements/ path segment, so it points to the wrong location in the openshift/enhancements repo.
Based on the adjacent link pattern in this README.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` at line 34, The README link is pointing to the wrong location
because the `enhancements/` path segment is missing from the GitHub URL. Update
the existing documentation link in README so it matches the adjacent link
pattern and points to the correct `openshift/enhancements` path for the “Testing
a ClusterOperator/Operand image in a cluster” section.
|
@sanchezl: all tests passed! Full PR test history. Your PR dashboard. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here. |
openshift-ci
Bot
added
the
needs-rebase
|
PR needs rebase. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
2 participants
Summary
Details
All four files are cross-referenced and consistent. AGENTS.md links to ARCHITECTURE.md for detailed architecture rather than duplicating it.
Design Decisions in ARCHITECTURE.md are sourced from code analysis, git history, and internal research notes — not just inferred from code structure.
Test plan
readlink CLAUDE.md→AGENTS.mdmake build,make test-unit,make verifySummary by CodeRabbit