[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

[nicolastakashi]

Good points, thanks both. I pushed a commit that covers the two things Arthur mentioned: a link to the Prometheus naming conventions instead of restating the rules, and a note that /proc parsing should go through procfs rather than getting reimplemented in a collector.

On scope, I'll go with Kyle's suggestion and keep this to node_exporter only for now. The multi-repo sync idea can wait until a couple more repos are on board and it's clearer what's actually shared versus exporter-specific. I can open a tracking issue for that once the exporter board exists.

If anything here still reads as too node_exporter-specific, or not specific enough, flag it and I'll adjust.

[ArthurSens]

Not sure if this is only my experience, but I feel like a very minimal AGENTS.md file does the job very very well and it's easier to maintain on the long term.

Things like Project Shape, Project Map would need to be constantly adjusted as the codebase evolves, and current models already do a pretty good job at reading the code and understanding how it is organized. Do we really need all those sections in AGENTS.md?

From all those sections, I'd keep only Rules. But again, this is just based on personal experience and I'm not an expert in all those different LLM protocols

[nicolastakashi]

I invested into this and there's an actual study on it: Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (ETH Zurich, Feb 2026). It backs what you're saying. Directory listings and codebase overviews don't move task success and add roughly 20% inference cost. Their recommendation is to limit instructions to what an agent can't infer, specific tooling or custom build commands, rather than describing what the code already shows.

I've applied some changes based on that, and below the justification from what I kept.

Rules stays, and I added a bullet about build tags gating collector availability, since that's a real gotcha and not something inferable from a folder name.

Build And Test Commands stays as its own section. Every line is a specific command you can't get from reading the code, like make test unpacking fixtures before running, or make test-e2e needing a binary at $GOPATH/bin/node_exporter. That's the "custom build commands" category the study explicitly says is worth keeping.

Toolchain Notes stays too, but I rewrote the Go version bullet. It used to say CI runs 1.26 while go.mod says 1.25.0, which just becomes wrong the moment either version changes. Now it points at where to check instead (the workflow's setup-go step, .promu.yml, .promu-cgo.yml) so the actual gotcha, that go.mod isn't the source of truth for what CI runs, survives a version bump.

Node Mixin is untouched. No version numbers to go stale, and it's telling you that CI regenerates and diffs specific files, not describing folder contents.