Why
The repo currently relies on a local, gitignored CLAUDE.md for contributor and AI-agent guidance. That has two problems:
- It only helps Claude Code users. Codex, Cursor, Aider, Jules and other agent tools look for
AGENTS.md (a growing cross-tool convention). Anyone using a different agent gets no project context.
- Gitignored docs drift silently. The current
CLAUDE.md describes a root terraform/ directory and a single OpenTofu backend across all providers - neither is true anymore. Because the file isn't checked in, nobody on the team has been able to catch or fix the drift in review.
What this issue proposes
- Add
AGENTS.md at the repo root as the canonical, committed guide for both human contributors and any AI coding agent. It replaces the conceptual role of the current local CLAUDE.md.
- Audit the content against the actual code before checking it in - the existing
CLAUDE.md is stale on several points (see below).
- Keep
CLAUDE.md gitignored. Each developer's local CLAUDE.md can be a one-liner pointing to AGENTS.md if they want Claude Code's pickup behavior; the team source of truth is the committed AGENTS.md.
Drift the audit caught
Things the current CLAUDE.md says that are no longer accurate:
- Describes a root
terraform/ directory with modules/aws/, modules/gcp/, etc. That directory doesn't exist; AWS Terraform templates live embedded under pkg/provider/aws/templates/.
- Presents OpenTofu as the universal backing tool. Hetzner uses
hetzner-k3s directly, local relies on Kind via the Makefile, and existing consumes an external kubeconfig.
- Implies cluster providers are the only pluggable category. The repo already has
pkg/dnsprovider/ with a working Cloudflare implementation and a unified pkg/registry/ covering both categories. ADR-0004 documents the direction.
- Lists incorrect
Provider interface methods (Status doesn't exist; GetKubeconfig/Summary were missing).
- Wrong
OTEL_EXPORTER default (console documented, none in code).
- Misses
InfraSettings.SupportsLocalGitOps.
Related cleanup in the same PR
- Fix stale "Backed by OpenTofu" doc comments on the
Provider interface itself in pkg/provider/provider.go - they predate Hetzner and read as if the interface mandates Tofu.
Out of scope (potential follow-ups)
- A broader audit of
docs/design-doc/ and docs/adr/ for the same tofu-everywhere framing.
- Whether to remove
CLAUDE.md from .gitignore entirely and let people choose to commit a pointer file - vs. keeping it ignored.
Why
The repo currently relies on a local, gitignored
CLAUDE.mdfor contributor and AI-agent guidance. That has two problems:AGENTS.md(a growing cross-tool convention). Anyone using a different agent gets no project context.CLAUDE.mddescribes a rootterraform/directory and a single OpenTofu backend across all providers - neither is true anymore. Because the file isn't checked in, nobody on the team has been able to catch or fix the drift in review.What this issue proposes
AGENTS.mdat the repo root as the canonical, committed guide for both human contributors and any AI coding agent. It replaces the conceptual role of the current localCLAUDE.md.CLAUDE.mdis stale on several points (see below).CLAUDE.mdgitignored. Each developer's localCLAUDE.mdcan be a one-liner pointing toAGENTS.mdif they want Claude Code's pickup behavior; the team source of truth is the committedAGENTS.md.Drift the audit caught
Things the current
CLAUDE.mdsays that are no longer accurate:terraform/directory withmodules/aws/,modules/gcp/, etc. That directory doesn't exist; AWS Terraform templates live embedded underpkg/provider/aws/templates/.hetzner-k3sdirectly, local relies on Kind via the Makefile, andexistingconsumes an external kubeconfig.pkg/dnsprovider/with a working Cloudflare implementation and a unifiedpkg/registry/covering both categories. ADR-0004 documents the direction.Providerinterface methods (Statusdoesn't exist;GetKubeconfig/Summarywere missing).OTEL_EXPORTERdefault (consoledocumented,nonein code).InfraSettings.SupportsLocalGitOps.Related cleanup in the same PR
Providerinterface itself inpkg/provider/provider.go- they predate Hetzner and read as if the interface mandates Tofu.Out of scope (potential follow-ups)
docs/design-doc/anddocs/adr/for the same tofu-everywhere framing.CLAUDE.mdfrom.gitignoreentirely and let people choose to commit a pointer file - vs. keeping it ignored.