Add AGENTS.md#1113
Conversation
SeanMooney
left a comment
SeanMooney
left a comment
There was a problem hiding this comment.
my meta comment is much of this info shoudl live in the project docs and only high signal to noise ratio instruction shoudl be in the agents.md
the majority of agents.md shoudl effectivly be a routing layer like
https://llmstxt.org/
instead of telling it what CRDs exist
tell it where to find there defintions
instead of embdeing detailed developer practices
tell it where to discover them in a doc in the repo that is writeen for humans when it needs them
| ## Tech stack | ||
|
|
||
| | Layer | Technology | | ||
| |-------|------------| | ||
| | Language | Go (modules, multi-module workspace via `go.work`) | | ||
| | Scaffolding | [Kubebuilder v4](https://book.kubebuilder.io/) + [Operator SDK](https://sdk.operatorframework.io/) | | ||
| | CRD generation | controller-gen (DeepCopy, CRDs, RBAC, webhooks) | | ||
| | Config management | Kustomize | | ||
| | Packaging | OLM bundle | | ||
| | Testing | Ginkgo/Gomega + envtest (functional), KUTTL (integration) | | ||
| | Linting | golangci-lint (`.golangci.yaml`) | | ||
| | CI | Zuul (`zuul.d/`), Prow (`.ci-operator.yaml`), GitHub Actions | | ||
|
|
||
| ## Custom Resources | ||
|
|
||
| | Kind | Purpose | | ||
| |------|---------| | ||
| | `Nova` | Top-level CR. Owns databases, keystone services, and spawns sub-CRs for API, scheduler, metadata, and cells. | | ||
| | `NovaAPI` | Manages the Nova API deployment. | | ||
| | `NovaScheduler` | Manages the scheduler service deployment. | | ||
| | `NovaMetadata` | Manages the metadata service deployment. | | ||
| | `NovaCell` | Manages a Nova cell (contains conductor, compute, noVNCProxy for that cell). | | ||
| | `NovaConductor` | Manages the conductor service within a cell. | | ||
| | `NovaCompute` | Manages compute agent instances within a cell. | | ||
| | `NovaNoVNCProxy` | Manages the noVNC proxy for console access within a cell. | | ||
|
|
||
| The `Nova` CR has defaulting and validating admission webhooks. | ||
| Sub-CRs are created and owned by the `Nova` controller -- not intended to | ||
| be created directly by users. | ||
|
|
||
| ## Directory structure | ||
|
|
||
| | Directory | Contents | | ||
| |-----------|----------| | ||
| | `api/v1beta1/` | CRD types (`nova_types.go`, `novaapi_types.go`, `novacell_types.go`, `novacompute_types.go`, `novaconductor_types.go`, `novametadata_types.go`, `novascheduler_types.go`, `novanovncproxy_types.go`), conditions, webhook markers | | ||
| | `cmd/` | `main.go` entry point | | ||
| | `internal/controller/` | Reconcilers: `nova_controller.go`, `novaapi_controller.go`, `novacell_controller.go`, `novacompute_controller.go`, `novaconductor_controller.go`, `novametadata_controller.go`, `novascheduler_controller.go`, `novanovncproxy_controller.go` | | ||
| | `internal/nova/` | Nova-level resource builders (db-sync, common helpers) | | ||
| | `internal/novaapi/` | NovaAPI resource builders | | ||
| | `internal/novacompute/` | NovaCompute resource builders | | ||
| | `internal/novaconductor/` | NovaConductor resource builders | | ||
| | `internal/novametadata/` | NovaMetadata resource builders | | ||
| | `internal/novascheduler/` | NovaScheduler resource builders | | ||
| | `internal/novncproxy/` | NovaNoVNCProxy resource builders | | ||
| | `internal/webhook/` | Webhook implementation | | ||
| | `templates/` | Config files and scripts mounted into pods via `OPERATOR_TEMPLATES` env var | | ||
| | `config/crd,rbac,manager,webhook/` | Generated Kubernetes manifests (CRDs, RBAC, deployment, webhooks) | | ||
| | `config/samples/` | Example CRs (Kustomize overlays). Includes `collapsed_cell`, `compute-fake`, `compute-ironic`, `upcall`, and TLS variants. | | ||
| | `test/functional/` | envtest-based Ginkgo/Gomega tests | | ||
| | `test/kuttl/` | KUTTL integration tests | | ||
| | `hack/` | Helper scripts (CRD schema checker, local webhook runner) | | ||
| | `doc/` | Design docs, developer guide, testing guide | | ||
| | `ci/` | CI job definitions | | ||
|
|
There was a problem hiding this comment.
Agents.md shoudl not contian info that can be easilly discoverd form introspecting the repo.
the directory structre woudl be ok in the readme but not here.
the CRs and tech stack shoudl also not be only defiend for the llm so i woudl add both of those to the readme as well.
i woudl perer to replace all of this with a pointer to
https://github.com/openstack-k8s-operators/nova-operator/blob/main/doc/design.md
you shoudl add the crd over view to that and you can add another doc
for the techstack beside it adn add a pointer to that as well
similar to what you dided with the key dependecies.
There was a problem hiding this comment.
the idea of this file is to have some info to avoid initial grep/find to discover the basic structure that hopefully is not changing much (or changing at all at this point of the lifecycle of the operator). +1 to link design.md since this is internal knowledge for the nova-operator.
If you like this part to go away in favor of design.md this is fine by me.
There was a problem hiding this comment.
The other things I wanted to avoid here are:
- don't start with curl remote content immediately
- don't start grepping or trying to find files to build the initial understanding of the project.
For this reason reference to other files within the project are probably good, and stay <150 lines helps you to give an overview of the basic things.
Note that this is an initial template. I expect each team to customize/optimize depending on their experience and experiments with AI agents.
There was a problem hiding this comment.
i would prefer to have it in design.md as much as possibel
and yes i actually would prefer to have no links to external soruce in the agents.md and have those behind 1 layer of indirection to avoid the curlign issue too.
in general the local discover is relatively cheap and in general it not required unless you are impresices with your prompts.
having a basic overview is ok but ideally not in the AGENTS.md as its very easy for ti to get out of sync
we are in the process or movign the palcement operator into this repo and then adding cyborg too sot eh directory stucrue is going to change alotner in the short term
that why im hesitant to encode it here because its not currently stable.
There was a problem hiding this comment.
i would prefer to have it in design.md as much as possibel
+1 and it is a good idea to defer to that layer more knowledge. I think I will apply the same approach across the board in a follow up.
and yes i actually would prefer to have no links to external soruce in the agents.md and have those behind 1 layer of indirection to avoid the curlign issue too.
+1 agreed
in general the local discover is relatively cheap and in general it not required unless you are impresices with your prompts.
having a basic overview is ok but ideally not in the AGENTS.md as its very easy for ti to get out of sync
we are in the process or movign the palcement operator into this repo and then adding cyborg too sot eh directory stucrue is going to change alotner in the short term
that why im hesitant to encode it here because its not currently stable.
ack and this is why I removed the entire directory tree section that can be discovered. I also pointed to docs/design.md so we defer to that layer most of the guidelines.
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: fmount 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 |
This patch adds AGENTS.md to the repo to ensure any AI agent can follow the conventions defined for this operator. At the same time, it allows to not waste time navigating the repo to find initial information and save tokens. Signed-off-by: Francesco Pantano <fpantano@redhat.com>
2 participants
This patch adds
AGENTS.mdto the repo to ensure anyAI agentcan follow the conventions defined for this operator. At the same time, it allows to not waste time navigating the repo to find initial information and save tokens.