agentleFS
Sign inStart free
openkruiseopenkruise/agents/AGENTS.md

agents

AGENTS.md315 starsChanged 11 months agoApache-2.0View on GitHub

This file contains repository-wide rules. - Root rules apply repository-wide; keep durable cross-file or silently critical constraints in the deepest applicable AGENTS.md, leave details and public contracts to their owning code, tests, specifications, or proposals, and review changes root-to-leaf before removing guidance. - Sandbox recycle cannot occur in any cluster running sandbox-manager. All sandbox-manager API, Manager, Infra, cache, quota, and token flows treat recycle as nonexistent; do not add recycle-specific handling or compatibility. - The independent Sandbox controller retains recycle…

  • 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,774 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

Show its rules and text

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

15 rules. About 0 are common, 6 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    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. Very specific:

    Never use APIReader for List.

    line 73
  2. Very specific:

    Use APIReader for Get only when informer-backed reads cannot provide acceptable correctness or functionality, and only after explaining why …

    line 75
  3. Very specific:

    Follow standard Go idioms.

    line 100
  4. Distinctive:

    Prefer table-driven unit tests.

    line 103
  5. Distinctive:

    Do not introduce test stubs, fakes, or mocks unless necessary.

    line 105
  6. Distinctive:

    Do not create abstract interfaces or new types unless necessary.

    line 107
  7. Very specific:

    Test only when needed, using the narrowest changed package or selected test (-run, -count=1).

    line 109
  8. Distinctive:

    Check cancellation in retrying or long-running work and preserve meaningful error context.

    line 115
  9. Distinctive:

    Do not add Prometheus metrics (new collectors, counters, gauges, histograms, or instrumentation) unless the user explicitly requests them.

    line 117
  10. Very specific:

    Do not edit generated files under client/, proto/, or config/crd/ directly.

    line 122
  11. Very specific:

    After changing api/v1alpha1/, run make generate manifests.

    line 124
  12. Very specific:

    Prefer responsibility-specific package names.

    line 128
  13. Very specific:

    Never ignore errors. Classify wrapped errors with errors.Is and errors.As.

    line 133
  14. Very specific:

    Use structured key-value logging.

    line 139
  15. Distinctive:

    Do not remove useful comments unless they are obsolete.

    line 145

≈ “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

OpenKruise Agents Guide

This file contains repository-wide rules.

Instruction Scope

  • Root rules apply repository-wide; keep durable cross-file or silently critical constraints in the deepest applicable AGENTS.md, leave details and public contracts to their owning code, tests, specifications, or proposals, and review changes root-to-leaf before removing guidance.

Control Plane Layering

Sandbox-manager Runtime Contract

  • Sandbox recycle cannot occur in any cluster running sandbox-manager. All sandbox-manager API, Manager, Infra, cache, quota, and token flows treat recycle as nonexistent; do not add recycle-specific handling or compatibility.
  • The independent Sandbox controller retains recycle support for other deployments. Its recycle capability does not imply CR reuse across deliveries in sandbox-manager deployments.
  • Secret edits restart nothing, so every --secret-config key used by the active authentication, storage, or quota mode must reach its owning configreload component Reload. Fields irrelevant to that mode need no dispatch. Restart-only inputs belong in flags.

API Layer — sandbox-manager

  • The API layer is pkg/servers/**, including E2B-compatible protocols.
  • It owns routing, transport protocols, request and response models, protocol-level validation, authentication and authorization, error and status mapping, and compatibility behavior.
  • Logic that directly expresses an API protocol contract must remain here. Do not push protocol models, HTTP semantics, or compatibility rules into Manager or Infra.

Manager Layer — sandbox-manager

  • The Manager layer is pkg/sandbox-manager/**, excluding its infra/** subtree.
  • It owns protocol- and backend-independent business rules and use-case orchestration, including lifecycle, quota, admission, and release policy.
  • It accesses Sandbox backends only through neutral Infra interfaces and must not depend on pkg/servers or directly read or write backend-state resources.
  • Classify Kubernetes-backed capabilities by ownership, not technology: sandbox-manager process coordination, discovery, publication, and identity allocation stay in Manager when they are not Sandbox backend capabilities.

Infra Layer — sandbox-manager

  • The Infra layer is pkg/sandbox-manager/infra/**. It owns Sandbox backend infrastructure, not every Kubernetes operation used by sandbox-manager.
  • Concrete Kubernetes implementations of Sandbox infrastructure capabilities and their clients, caches, reads, and writes belong in implementation subpackages such as infra/sandboxcr.
  • It exposes protocol-neutral Sandbox capabilities and data upward. It must not depend on API models, HTTP status codes, authentication semantics, or Manager business policy.

Agent Sandbox Controller

  • cmd/agent-sandbox-controller and pkg/controller/** form an independent Kubernetes operator.
  • The controller's complete dependency closure must not include pkg/servers/** or pkg/sandbox-manager/**. Code shared with sandbox-manager must move to a genuinely neutral package; a shared or utility package must not hide an indirect reverse dependency.
  • Controllers may reconcile CRDs directly, but must not reuse sandbox-manager API behavior, business orchestration, or Infra implementations.

Kubernetes Read Discipline

  • Never use APIReader for List; prefer informer-backed clients or caches for Kubernetes reads.
  • Use APIReader for Get only when informer-backed reads cannot provide acceptable correctness or functionality, and only after explaining why and obtaining explicit user approval.

Dependency Rules

  • New sandbox-manager dependencies follow API -> Manager -> Infra. Do not add API-to-Infra shortcuts or lower-to-upper reverse dependencies.
  • pkg/features is controller-only. Code under pkg/sandbox-manager/** and pkg/servers/** must not import it or consume its gates through a shared wrapper.
  • For optional sandbox-manager behavior, prefer interface or option parameters that control a single call. Avoid package-global or process-global feature switches. Add a global switch only when per-call control cannot safely express the requirement, and document why global scope is necessary.
  • cmd/* entrypoints assemble dependencies and start components only; business logic belongs in the appropriate layer.
  • These rules are normative for new work. Existing cross-layer imports are legacy debt, not architectural precedent: do not add to or widen them. If a task requires a wider violation, propose a layering refactor first.
  • Shared packages must stay policy-neutral and must not import domain-specific packages merely to make reuse convenient.

Development

  • Follow standard Go idioms. Run gofmt -w on changed Go files.
  • New Go files must use the Apache 2.0 header from hack/boilerplate.go.txt. Keep code comments in English.
  • Prefer table-driven unit tests. Extend a suitable existing table; use a standalone test only when no table fits.
  • Do not introduce test stubs, fakes, or mocks unless necessary. Prefer exercising real implementations or existing test infrastructure first.
  • Do not create abstract interfaces or new types unless necessary. Introduce an abstraction only when a concrete, current need requires it.
  • Test only when needed, using the narrowest changed package or selected test (-run, -count=1). Do not run unrelated tests or repeat stable tests. For probabilistic failures, races, or other concurrency risks, rerun the relevant test enough times to trust it (-count=N, -race). make test runs the full pkg/... suite; use make vet and make lint only when warranted. Never run E2E tests for ordinary validation.
  • Check cancellation in retrying or long-running work and preserve meaningful error context.
  • Do not add Prometheus metrics (new collectors, counters, gauges, histograms, or instrumentation) unless the user explicitly requests them.

Generated Files And Design Changes

  • Do not edit generated files under client/, proto/, or config/crd/ directly.
  • After changing api/v1alpha1/, run make generate manifests. Use make generate or make manifests for their respective generated outputs.
  • New APIs and architectural changes require a proposal in docs/proposals/.
  • Prefer responsibility-specific package names. Do not create new catch-all utils, common, helpers, util, or base packages.

Errors And Logging

  • Never ignore errors. Classify wrapped errors with errors.Is and errors.As; use Kubernetes API error helpers for Kubernetes errors and client.IgnoreNotFound only where absence is acceptable.
  • Sandbox-manager domain errors belong in pkg/sandbox-manager/errors/; transport status mapping belongs in the API layer.
  • Use structured key-value logging. Controllers use logf.FromContext(ctx); sandbox-manager code uses klog.FromContext(ctx). Do not use fmt.Println for runtime logging.

Repository Hygiene

  • Do not remove useful comments unless they are obsolete.
  • A new submodule AGENTS.md must have a sibling CLAUDE.md whose sole content is @./AGENTS.md.
  • Commits must include sign-off, for example git commit -s.

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