Proposal: concise guidance for AI-assisted contributions

[user01010111]

Would you be open to a short, tool-agnostic "AI-assisted contributions" checklist in docs/developers.txt, linked from the pull-request template?

This would not be an effort to encourage or increase the level of AI authorship in the project. The intention is that, where contributors already choose to use these tools, they have clearer NUT-specific guidance for producing accurate, useful and maintainable contributions.

The existing guidance already covers disclosure, human responsibility, coding style and ASCII portability. A quick review of the AI-labelled pull requests suggests that some recurring review costs could be avoided with a little more upfront direction. Examples include invented or stale source assumptions, changes made at the wrong layer, missed NUT helpers and build metadata, unsupported hardware or platform claims, and speculative reactions to CI failures.

The proposed addition would be concise and would direct contributors and their tools back to the existing authoritative documentation. It could emphasise verifying claims against current source and specifications, keeping changes narrowly scoped, testing the affected behaviour where practical, reporting untested boundaries honestly, and diagnosing CI failures before making further changes.

The aim would be to improve the accuracy and value of AI-assisted contributions that are made, hopefully improving the resulting code quality while reducing avoidable review work and unnecessary CI runs for maintainers. It would not replace human review or responsibility or prescribe a particular model.

If that sounds useful, I would be happy to prepare a small draft for review. Would you prefer it as a subsection of docs/developers.txt, or somewhere else?

[jimklimov]

Thanks, the idea sounds reasonable, I would be happy to get a boilerplate :)

From what I saw in other projects, there is usually a directory for an LLM like /.claude with some md files to explain the expectations, which are detected automatically. I do not know if there is some common /.ai or whatever location which everyone would find and so avoid duplicating the data.

This file might refer machines to developers.txt among other hints, and the latter can mention (to humans) that an LLM should be pointed at that tile.

[user01010111]

Thanks, that sounds sensible. There is not currently one filename recognised automatically by every tool, but AGENTS.md appears to be the closest tool-neutral convention: it is an open format supported by a growing range of coding agents.

I suggest adding a concise AGENTS.md at the repository root which directs agents to docs/developers.txt, docs/developer-guide.txt and the existing pull-request checklist, while keeping the authoritative detail in those existing documents. A brief note in docs/developers.txt could tell contributors to ensure their tool reads AGENTS.md if it does not detect it automatically.

That should avoid maintaining separate .claude, .cursor and similar copies which could drift apart. I will prepare a small draft along those lines for review.

[jimklimov]

Thanks!