pdfly
AGENTS.md579 starsChanged 13 months agoBSD-3-ClauseView on GitHub
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 22
Use assert only within tests.
- Very specific: line 26
Prefer parametrized tests using pytest.mark.parametrize to cover multiple input scenarios efficiently.
- Very specific: line 28
Ensure the git submodule sample-files is initialized and updated
- Very specific: line 29
Run pre-commit install to set up the git hook.
- Very specific: line 30
Run pytest to execute the test suite.
- Distinctive: line 31
Ensure all tests pass before committing changes.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
- Commit Messages:
- AI-Disclosure: The last line of a commit message should be
Co-authored-by: {model_name} <{model_email}> - Format:
{PREFIX}: {DESCRIPTION}\n\n{BODY}, where PREFIX is the first that applies:- SEC: Security improvements. Typically, an infinite loop that was possible. Usually only used by the maintainers - others should report possible issues in this category privately first and only push a public change if told so.
- BUG: A bug was fixed. Likely there are one or multiple issues. Then write in the BODY: Closes #123 where 123 is the issue number on GitHub. It would be absolutely amazing if you could write a regression test in those cases. That is a test that would fail without the fix. A bug is always an issue for users - test code or CI that was fixed is not considered a bug here.
- ENH: A new feature! Describe in the body what it can be used for.
- DEP: Deprecation. Either marking something as “this is going to be removed” or actually removing it.
- PI: A performance improvement. DESCRIPTION must contain a benchmark section.
- ROB: A robustness change, e.g. dealing better with broken PDF files.
- DOC: A documentation change.
- TST: Adding or adjusting tests.
- DEV: Developer experience improvements, e.g., pre-commit or setting up CI.
- MAINT: Quite a lot of different stuff. Performance improvements are, for sure, the most interesting changes in here. Refactorings as well.
- STY: A style change. Something that makes code more consistent. Typically, a small change. It could also be better error messages for end users.
- BODY: If the commit relates to an issue (https://github.com/py-pdf/pypdf/issues) mention it:
- Closes #123: If the issue was fixed by this commit
- "Related to #123" or "See #123" otherwise
- AI-Disclosure: The last line of a commit message should be
- Project Language: (American) English must be used for all communication, including variable names, code comments, commit messages and documentation.
- Code Style Guidelines:
- Use
assertonly within tests.
- Use
- Test Style Guidelines:
- It is fine to use assert in the "arrange" step of a test to show which preconditions are expected before executing the code under test.
- Tests should have 3 sections: Arrange (setup data), Act (execute code under test), Assert (verify results). They do not need to have explicit comments separating the sections, but if the blocks get longer and more complex, it's appreciated.
- Prefer parametrized tests using
pytest.mark.parametrizeto cover multiple input scenarios efficiently.
- Project setup:
- Ensure the git submodule
sample-filesis initialized and updated - Run
pre-commit installto set up the git hook. - Run
pytestto execute the test suite. - Ensure all tests pass before committing changes.
- Ensure the git submodule
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

