[CHORE] adding agents.md

[nicolastakashi]

No description provided.

[SuperQ]

I would love to have this, but I think we should think about a system to sync these between all the exporters. I don't want to hand-maintain 70+ of these across the community.

[nicolastakashi]

I would love to have this, but I think we should think about a system to sync these between all the exporters. I don't want to hand-maintain 70+ of these across the community.

Thanks for raising this @SuperQ
One idea that could helps by leveraging infrastructure we already have:

How it would work

Each exporter repo gets two files:

node_exporter/
├── AGENTS_EXPORTERS.md   ← synced automatically, do not edit manually
└── AGENTS.md             ← maintained per-repo, imports the common part

AGENTS.md in each exporter starts with:

@AGENTS_EXPORTERS.md

## Project-specific guidelines
... exporter-specific content ...

AGENTS_EXPORTERS.md contains the shared conventions across all exporters (metric naming, collector patterns, contribution rules, etc.) and is distributed automatically via the existing sync_repo_files.sh mechanism, the same one that already propagates Makefile.common, LICENSE, and other common files across the ecosystem.

Why this approach

• Local file reference (@AGENTS_EXPORTERS.md), no external URL fetching, works natively with any agent that supports local file imports (Claude Code, Codex, Cursor)
• Each repo stays independent maintainers freely edit AGENTS.md for project-specific content without affecting the synced file
• Reuses existing infrastructure, no new tooling, no new repos, just an additional file in the sync list

What would need to change

1. Add AGENTS_EXPORTERS.md to the source repo that sync_repo_files.sh pulls from
2. Add AGENTS_EXPORTERS.md to the list of files the script distributes to exporter repos
3. Each exporter gets an AGENTS.md (like this PR) with @AGENTS_EXPORTERS.md at the top — this could also be bootstrapped by the sync script on first run

The content split would be something like:

AGENTS_EXPORTERS.md (common): metric naming conventions, node/exporter namespace rules, collector patterns, how to run tests, fixture update workflow, contribution guidelines common to all exporters.

AGENTS.md (per-repo): project-specific entrypoints, collector inventory, build quirks, OS-specific notes.

WDYT? Happy to send a PR to the sync script if this direction makes sense.

[ArthurSens]

Yeah, I think we should have most of these guidelines on the website, and in AGENTS.md we just point to the website and add what is specific to each exporter

[nicolastakashi]

Yeah, I think we should have most of these guidelines on the website, and in AGENTS.md we just point to the website and add what is specific to each exporter

One of the things I've been testing and I can't make sure yet is, we don't have any guarantee that agents will follow external links, so pointing into the AGENTS.md will be a best effort

[kgeckhart]

I see a mix of things that apply only to node_exporter, apply to a few exporters, and apply to all exporters. The guidance I read about AGENTS.md is that it's best to keep it light and hyper focused on unique aspects of the project. Linking out to docs (that the agent is hopefully trained on 🤞) or providing guidance the agent can glean easily from looking at surrounding code might end up bloating token use for minimal gain.

I would be happy to start with just node_exporter as we figure out what's valuable and when we get another repo or two look at doing a multi-file approach with syncing for the clear overlapping guidance. This can be captured in issues on an exporter board (working out the details on that ATM).

[ArthurSens]

Could we start with something that says metric names should follow Prometheus naming conventions, and things that are very specific to node exporter?

I'm not really familiar with this codebase, so I can't really tell what kind of instructions only apply here 😅.

[ArthurSens]

Maybe the test fixtures, if it's not already documented somewhere else? I don't see this in other exporters 🤔.

[ArthurSens]

ah, just remembered that we could document something about the procfs dependency being responsible for parsing proc files, instead of adding this logic in the exporter