Skip to content

docs: add AGENTS.md as the canonical contributor + agent guide #296

@dcmcand

Description

@dcmcand

Why

The repo currently relies on a local, gitignored CLAUDE.md for contributor and AI-agent guidance. That has two problems:

  1. 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.
  2. 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

  1. 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.
  2. Audit the content against the actual code before checking it in - the existing CLAUDE.md is stale on several points (see below).
  3. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions