AGENTS.md: init

[lucasew]

Simpler approach for a AI coding agent entrypoint.

No need for AI disclosure as I wrote it all by hand.

Things done

• Built on platform:
  • x86_64-linux
  • aarch64-linux
  • aarch64-darwin
• Tested, as applicable:
  • NixOS tests in nixos/tests.
  • Package tests at passthru.tests.
  • Tests in lib/tests or pkgs/test for functions and "core" functionality.
• Ran nixpkgs-review on this PR. See nixpkgs-review usage.
• Tested basic functionality of all binary files, usually in ./result/bin/.
• Nixpkgs Release Notes
  • Package update: when the change is major or breaking.
• NixOS Release Notes
  • Module addition: when adding a new NixOS module.
  • Module update: when the change is significant.
• Fits CONTRIBUTING.md, pkgs/README.md, maintainers/README.md and other READMEs.
• Follows the automation/AI policy.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/lets-create-skills-for-nixpkgs-development/78627/20

[patka-123]

#536518 (review)

Still applies verbatim.

[nh2]

I think this is still too generated and verbose.

There's no point telling an agent

Assist a human contributor.

or

Follow the checklist

or

• Did you understand the issue being asked?

(all of these sound like genericisms to me that do not help a machine doing its job) or

The user is responsible for the changes you do. You are just a tool to do it faster.

For this last one in particular I do not see what concretely it will achieve.

I also don't think there's a point in

**Ask first**

- Commit changes.
- Push changes.
- Open/update PRs.
- Comments.
- Destrutive Git operations: force-push, rebase, history rewrite.
- Set up a worktree for a branch.

because that surely depends on the individual user's preference on how to use their tools.

---

In alignment with what I wrote here I suggest to write this file fully by hand, and keep it as minimal as possible.

Be able to justify every line. For example:

• Ask your agent to package some software. Does it declare success on something suboptimal, such as fail to run the formatter? Then add 1 line to AGENTS.md, do the same again, and see if it helps. Finally, remove the line again, and observe it fail again. Then report here that this helped and why.

The guiding pricing principle should be:

• For contributors that choose to use a LLM to work on nixpkgs, what are concrete points that will uncontroversially help their work?

[lucasew]

I was actually following some informal standards on how to do a effective AGENTS.

It's a v1. I may not be the best person to do that but I am trying.

The main thing is that the repo has rules and the model is supposed to follow all them and issues would be essentially gaps on docs because LLMs start from scratch, like a new contributor, every contribution.

I wanted to, for example, give it a build failure issue, it could confirm that the problem is there, do the research on where it was already addressed and if not work on the solution.

[eclairevoyant]

This shouldn't be necessary and just increases burden to maintain yet another copy of the standards.... when the regular contributor docs can be improved instead. -1

[pyrox0]

I do not see the point in an AGENTS.md file being anything more than a list of documentation locations. If documentation seems to belong in AGENTS.md, we should consider it being better suited for the main documentation. Anything more than that is overkill, in my opinion. If an agent can't comprehend our(admittedly not the best) docs that are already in the repo, I see no reason to accept those contributions, as we expect that humans are able to. Agents should also not be responsible for understanding guidelines beyond what is stated in the docs. Humans should always be in control and the ones with final understanding of changes. Therefore, I see no point in making it so agents can do all the thinking for someone.

[wolfgangwalther]

#536518 (review)

Still applies verbatim.

Precisely.

[rhendric]

If taking this approach instead of something minimal like #534657, at a minimum, I think we need to know who will maintain this. I fear that this file will become an append-only log of things people felt they needed to add before their otherworldly patron did what they wanted. When would anyone ever have the confidence to remove something from this file? In the absence of an objective way to determine that a line is no longer load-bearing for the current generation of LLMs, such calls would have to be made by someone or some team (or they never get made and this becomes an ever-growing pile of bloat). Who is stepping up to do that?

(This comment is not an endorsement, in general, of wizards multiclassing into warlocks. I'm approaching this as harm reduction — it may be globally optimal to offer clean needles to the public, even if people shooting up is net harmful to society, because without that option people may make worse decisions.)

[lucasew]

I would suggest to only use it as an entrypoint. If a guideline changes we change the guideline file instead.

[rhendric]

• Can you reliably query GitHub as a non-anonymous user to gather information?

That's an example of an entrypoint? Seems like a thing you or someone at some point came up with as a reaction to an agent not doing that thing and screwing up as a consequence. What's to stop there from being more such things? Where would they go if not here?

[nh2]

If taking this approach instead of something minimal like #534657, at a minimum, I think we need to know who will maintain this. I fear that this file will become an append-only log of things people felt they needed to add

I agree (see also above).

The more minimal this is, the better (both given controversy of using LLMs among some nixpkgs contributors, human review effort, and, in my experience, for the LLM).

I didn't know that

• docs: add AGENTS.md and symlink CLAUDE.md #534657

existed. I think that's a much better starting point than the contents currently proposed in this PR.

[emilazy]

(Just noting that the Nixpkgs core team is looking at this and related PRs per #534657 (comment) and #534657 (comment).)

[rhendric]

(Watching bullet points like this being appended to this PR is direct evidence for my argument here.)

[lucasew]

(Watching bullet points like this being appended to this PR is direct evidence for my argument here.)

Are you dogfooding the AGENTS too?

[rhendric]

Sorry, I don't understand your question. I don't use LLMs for anything, if that's what you're asking.

[lucasew]

Sorry, I don't understand your question. I don't use LLMs for anything, if that's what you're asking.

Well, the only use of this file is being a LLM entrypoint. There is nothing to maintain. If it messes up it can be either a documentation gap or a guideline gap, so the idea here is to avoid the LLM to reward hack its way through by telling that LLM autonomy is not welcome and the repo has well defined rules.

Another static check we could introduce to avoid automated slop is a PR check that auto closes PRs that do not have the template on the end part of the PR body, that way it stops being a burden on reviewers as a PR that does not follow the template would be a low hanging fruit slop.

Trivial changes, tbh, are pretty hard for a LLM to get wrong, the way it is is performing great in my tests. It even was able to grok around hooks and stuff, even though the result could be better. I, myself, was essentially guiding it through the solution I was expecting it to achieve.

I even got some first turn merges.

BTW that __structuredAttrs unnoficial guideline should be formalised somewhere, the model was consistently "forgetting" that.

Models can be useful to benchmark the gaps of the documentation, if a model do not follow a guideline it's either the user that forgot to ask to redo the checklist, a documentation gap or the model cut corners reading documentation, which may be a checklist issue.