AGENTS.md Convention

Entirius repositories are worked on by developers and by AI coding agents. Each repository keeps one instruction file that every tool reads.

Files

File	Role
AGENTS.md	the single source of the repo’s agent instructions, in English
CLAUDE.md	the single line @AGENTS.md (Claude Code import), zero content of its own
README.md	for humans: what this is, quick start; does not duplicate AGENTS.md (README Convention)

Why: AGENTS.md is an open industry standard (agents.md) read by most tools (Codex, Cursor, Zed, Jules); Claude Code reads CLAUDE.md and supports @file imports. One text serves every tool. Instruction changes go to AGENTS.md only.

Sections

The recommended sections, in this order:

Section	Content
header	one sentence: the repo, its distribution name, its import name
## Commands	the targets the repo’s own Makefile has (Makefile Convention); a target of another repo’s Makefile is not listed
## Conventions	English only, MPL-2.0 and headers, toolchain, git flow, “don’t commit by default”, no AI attribution (Git Flow)
## Architecture	key modules and entry points, telegraphic
## Settings	optional: the settings the module reads
## Gotchas	optional: traps a change runs into

Example: AGENTS.md of entirius-py-payu-sdk, a library in the shape above.

Size Tiers

Targets for the length of the file: library ≤ 60 lines, Django module ≤ 200, service / frontend / harness ≤ 300. What does not fit moves to the repo’s docs/ and is linked. They are targets: the files of some repositories are longer today and shrink as their reference sections move to docs/.

Never in a Public AGENTS.md

Internal plan or roadmap ids, non-English text, private hosts or repos, targets of another repo’s Makefile presented as the repo’s own, test counts and other numbers that drift, a version floor that contradicts pyproject.toml.

A rule is written out in the file or links the Handbook. A public repo never points to a document its visitors cannot open.

Conventions Line

The rule against AI attribution (Git Flow) is one line under ## Conventions. A repo that already has a longer section for it keeps that section.

- No AI attribution in commits or PR descriptions: no `Co-Authored-By` trailer for an agent, no "Generated with" footer.

Next

README Convention: the file the same repo shows to humans