agentleFS
Sign inStart free
NVIDIAKnown publisherNVIDIA/ccluster/AGENTS.md

ccluster

AGENTS.md10 starsChanged 2 days agoApache-2.0View on GitHub

Two Kubernetes operators from one Go module, with a Helm chart catalog and generated Python models. Read README.md for the project and local quickstart. This repository's conventions take precedence over generic kubebuilder scaffolding. Read the relevant document before changing the area it covers; these contain the detailed contracts and workflows omitted from this guide. CLAUDE.md points here and .claude/skills points to .agents/skills. Keep shared instructions tool-neut

  • Installs packages
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository3 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Read the relevant document before changing the area it covers.

    line 27
  2. Distinctive:

    Keep cp/ip RBAC separate and their leader-election IDs distinct.

    line 60
  3. Very specific:

    Never hand-edit generated CRDs, the operators' generated RBAC roles, zz_generated.*.go, PROJECT, operator chart templates/ or .helmignore, …

    line 68
  4. Distinctive:

    Commit the resulting generated changes.

    line 85
  5. Very specific:

    Follow Kubernetes API conventions: standard types such as metav1.Time, metav1.Condition, and current observedGeneration on conditions and …

    line 91
  6. Distinctive:

    Keep reconciliation idempotent and watch-driven.

    line 93
  7. Very specific:

    Before a commit run make pre-commit: it tidies, regenerates, fixes lint and runs the Go, chart and Python tests.

    line 96
  8. Distinctive:

    Run checks appropriate to the changed inputs, including required generators.

    line 102

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

ccluster — Agent Guide

Two Kubernetes operators from one Go module, with a Helm chart catalog and generated Python models. Read README.md for the project and local quickstart. This repository's conventions take precedence over generic kubebuilder scaffolding.

Repository map

PathPurpose
cmd/ccluster-{cp,ip}-operator/Separate binaries for separate clusters; cp drives Argo CD, ip verifies catalogs/cluster_base against CCLClusterConfig.
cmd/ccluster/, internal/cli/The ccluster command line (cobra): init, register, unregister, server. Released as per-platform tarballs and through go install.
internal/server/, ui/ → internal/server/ui/dist/ccluster server: a read-only dashboard. A net/http JSON API under /api/v1/ plus the React (Vite, TypeScript, Kaizen UI) app from ui/, whose build is embedded with go:embed.
internal/controller/{cp,ip}/Per-operator controllers; shared bootstrap is in internal/manager/.
internal/registry/Generic per-chart registry (chart path → function) and the *_registry packages built on it, such as the ip operator's verifier_registry, the cp operator's drift_registry, and the validator_registry that checks component values.
api/ccluster/v1alpha1/CRD types; API group is ccluster.nvidia.com.
pkg/client/Generated Go clientset, apply configurations, listers and informers for the API types, for programs outside this repository and for the cp operator's infra-plane watch in internal/remote/; test/client/ tests them.
pkg/cclclient/Hand-written high-level client on pkg/client, the Go counterpart of Python's CCLClient: registers infra planes and applies component sets in one namespace.
internal/argocd/v1alpha1/, internal/externaldns/v1alpha1/Hand-written partial Argo CD and external-dns API mirrors; extend them rather than using unstructured.
config/ → charts/{cp,ip}/chart/Kustomize sources → generated operator Helm charts. Deploy with Helm.
catalogs/Helm charts with typed Go values, part of the Go module: cluster_base/ platform components (each registered with a Verifier the ip operator runs), deployments/ tenant workloads, resources/ the queues and volumes they use. A chart that runs a binary built here keeps its source in a subdirectory, such as deployments/compute_deployment/compute-ssh/.
hack/pyschema/ → python/CRD spec/status and chart values → JSON Schema → Pydantic package.
examples/Hand-written examples. examples/quickstart/ registers a cluster and deploys an inference service through the Go SDK (compiled with the module) and Helm, and walks through the Python SDK versions in python/examples/; its manifests/ are round-tripped by the Python tests.

Read for your task

Read the relevant document before changing the area it covers; these contain the detailed contracts and workflows omitted from this guide.

TaskReference
Reconciliation, ownership, tenancy, ordering or statusDESIGN.md
Adding controllers, APIs or catalog components; generators, RBAC or HelmDevelopment
Writing or running testsTesting
Deploying, debugging or removing a local installationDevelopment: cluster operations
Docker, CI, the Go version, artifact versions or publishing workflowsBuild and release contracts
Python package usagePython README
Committing, pushing or opening a PRcommit-pr skill
Reviewing a PR or diffpr-review skill
Preparing or publishing a releaserelease skill

CLAUDE.md points here and .claude/skills points to .agents/skills. Keep shared instructions tool-neutral. Put detailed procedures in the linked docs or skills rather than expanding this file.

Architectural guardrails

  • Argo CD runs only in the control-plane cluster and is installed by the cp Helm chart. The operator creates Applications; it must never install or upgrade Argo CD itself.
  • Managed Argo CD resources use ownership annotations and ownedBy checks, never owner references. Applications require explicit, reverse, one-at-a-time teardown.
  • Rollout order is list position. Release is monotonic: degradation must not withdraw an already released Application. Do not introduce ApplicationSet or RollingSync.
  • Preserve namespace isolation: Applications live beside their CCLComponentSet; cluster Secrets and AppProjects live in the Argo CD namespace. Projects allow only the catalog repository, and cluster Secrets are project-scoped.
  • CCLInfraPlane Available=True guarantees its namespace's AppProject already exists.
  • The cp operator makes no cloud API calls. DNS records are published by external-dns from DNSEndpoints in the operator's namespace, never a tenant's; zones are the user's.
  • Keep cp/ip RBAC separate and their leader-election IDs distinct.
  • The ip operator verifies cluster_base and never installs, upgrades or deletes anything. Verifiers read live objects, never Argo CD or Helm release state. Its RBAC is read-only apart from CCLClusterConfig status; a Verifier reading a kind adds a marker in internal/controller/ip.

Source of truth and generation

Never hand-edit generated CRDs, the operators' generated RBAC roles, zz_generated.*.go, PROJECT, operator chart templates/ or .helmignore, the Go client in pkg/client/, the UI build in internal/server/ui/dist/, or generated Python modules. Edit their sources and regenerate. charts/cp/chart/Chart.lock is generated by make helm-deps-update-cp.

Operator-chart Chart.yaml and values.yaml are preserved and may be edited. Kustomize inputs are hand-written. Python's hand-written files are documented in Development.

Changed inputRegenerate
API types, markers or API doc commentsmake manifests generate, make client-generate, make helm-generate, make python-generate
config/ or RBAC markersmake helm-generate (includes manifest generation)
Catalog Go values or their comments, or hack/pyschema/make python-generate
hack/clientschema/make client-generate
ui/make ui-build (needs Node; see Development)

Commit the resulting generated changes. API and catalog doc comments ship in schemas; comment-only edits can require regeneration too. Do not install CRDs into a cluster merely to regenerate files.

Implementation and validation

  • Follow Kubernetes API conventions: standard types such as metav1.Time, metav1.Condition, and current observedGeneration on conditions and status.
  • Keep reconciliation idempotent and watch-driven; preserve the explicit teardown retry.
  • Log messages are capitalized, past tense, without a trailing period, with the object type named and balanced key-value pairs.
  • Before a commit run make pre-commit: it tidies, regenerates, fixes lint and runs the Go, chart and Python tests. During iteration make test is enough.
  • New controller behaviour belongs in envtest. Use selective table tests for states envtest cannot cheaply reach. Test contracts, not implementation details.
  • Envtest does not prove RBAC or running watch wiring; use make test-e2e for those. make test-e2e-full adds real Argo CD reconciliation. See the testing guide for setup.
  • Run checks appropriate to the changed inputs, including required generators. Report what ran and any checks that could not run; the commit skill has the pre-commit matrix.

Cluster safety

  • Pin the intended cluster with a dedicated KUBECONFIG before cluster operations. Helm targets also accept KUBE_CONTEXT_CP / KUBE_CONTEXT_IP; do not put flags in KUBECTL. Standalone deploy-cp / deploy-ip otherwise use the current context.
  • Helm owns deployed CRDs: do not run make install before make deploy-cp. Existing CRDs can be adopted with make helm-adopt-crds-cp; see the development guide.
  • Deleting a CRD deletes its CRs. make undeploy-cp keeps CRDs but removes bundled Argo CD; finish required CR teardown while the controllers still run.
  • make clean deletes development clusters; make clean-all also removes tools and build output. E2e creates and deletes its own two clusters: never use a working cluster as KIND_CLUSTER_E2E_CP or KIND_CLUSTER_E2E_IP.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free