diff --git a/AGENTS.md b/AGENTS.md index 99012e0..d5393f4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # AI Instructions for Read the Docs This file lives in the `common` repo, -and is copied to each produciton repo. +and is copied to each production repo. Agents don't work with symlinks or submodules, so this is best for now. @@ -11,7 +11,7 @@ Read the Docs is a documentation hosting platform that builds and hosts document It supports multiple documentation tools (Sphinx, MkDocs, etc.) and automatically builds documentation from Git repositories. **Technology Stack:** -- Python 3.x +- Python 3.14 - Django web framework - Docker and Docker Compose for development - PostgreSQL database @@ -26,11 +26,11 @@ It supports multiple documentation tools (Sphinx, MkDocs, etc.) and automaticall ## Pull Requests -* Make the PR description maximum useful for humans, context first and most important. +* Make the PR description as useful as possible for humans; lead with the most important context. * Always open pull requests as drafts -* Put a footer note that this was generated by the AI agent in use +* Note in a footer that the PR was generated by an AI agent, but only if no such footer is already appended automatically — never add a second one * Use feature branches for all changes -* Don't include a "Changes" section, since the PR content is self-explanatory +* Write the description about *why*: the problem it solves, the approach taken, and anything a reviewer should double-check. Don't restate *what* changed — no "Changes" section, changelog, file lists, or per-change bullets — since the diff already shows that. Prefer "Sharpens the PR rules, which kept producing diff-restating descriptions" over "Reworded one bullet, fixed a typo, removed two sections." * Don't include Test Plan unless absolutely necessary. * Link related issues in the PR description, if there are any in the chat context * Prefix pull request titles, example `Api:`, `Builds:`, or `Docs:`. @@ -96,7 +96,6 @@ before they cause `IntegrityError` failures at deploy time. - Use Django conventions and best practices - Use type hints for function signatures - Write clear, concise docstrings for public functions and classes -- Run linters and formatters using `tox -e pre-commit` before committing code ## Front-end