Browse Source

AGENTS.md: sync with instructions of other repositories

Bring in rules added in the other repositories since: learning from mistakes, permanent source URLs and no hard-wrapping in commit messages, the stricter procedure for @-mentions of bots and PR descriptions without the private session URL. Python / Pipfile rules don't apply to this container image repository. Package version update commits follow the convention already documented in docker-onion-service, using this repository's `upgrade <package> package from <old> to <new>` subject lines; CI tooling changes aren't user-facing; `.github/dependabot.yml` is synced with another repository.

Based on https://github.com/fphammerle/free-disk/blob/356731a084bb99e163f400833c198041664a154c/AGENTS.md and https://github.com/fphammerle/systemctl-mqtt/blob/985c7a418c277d45a1e51b07e489de423e1bffcc/AGENTS.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude 5 days ago
parent
commit
a64bd403d2
1 changed files with 42 additions and 3 deletions
  1. 42 3
      AGENTS.md

+ 42 - 3
AGENTS.md

@@ -1,14 +1,34 @@
 # Agent Instructions
 
+## Learning from mistakes
+
+- Whenever you make a mistake and learn from it (pointed out by the user or noticed yourself),
+  record the lesson in `AGENTS.md` **automatically**, without being asked, so it isn't repeated.
+- If a mistake recurs although a rule for it already exists, make that rule stricter and more
+  concrete (e.g. a mandatory check before acting) instead of just restating it.
+- When writing or updating `AGENTS.md`, only add information that isn't already obvious from the
+  repository itself (e.g. Git LFS tracking is visible in `.gitattributes` and marked on GitHub).
+
 ## Commit messages
 
 - Attribution line: `Co-Authored-By: Claude <model name> <noreply@anthropic.com>` — always include the model name,
   e.g. `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`
 - Do **not** include a `Claude-Session:` line — the session URL is private.
+- Explain **why**, not what — don't restate in prose what's already obvious from `git diff` of
+  the commit (e.g. "add a notice to the README", "update section X").
+- When content is copied or adapted from another repository, reference the sources with full
+  permanent URLs (commit hash + path), e.g. `https://github.com/<owner>/<repo>/blob/<sha>/<path>`.
+- Don't hard-wrap long lines in commit message bodies — write each paragraph / list item on a single line; git log viewers wrap them automatically.
+- Package version updates (e.g. `POSTFIX_PACKAGE_VERSION`, `MOZILLA_CA_CERT_STORE_PACKAGE_VERSION`
+  in `Dockerfile`): keep the subject line `upgrade <package> package from <old> to <new>` and list
+  the **relevant changes** of the new version in the body, taken from the upstream changelog
+  linked in the comments above the version `ARG` (e.g. security fixes, behaviour changes).
 
 ## CHANGELOG
 
 - Only document **user-facing** changes (features, bug fixes, removed support).
+- CI / build tooling changes (e.g. GitHub Actions workflows, `dependabot.yml`) are not
+  user-facing → no entry needed.
 
 ## Pull requests
 
@@ -26,10 +46,29 @@
 
 - Fix CI failures automatically, iterating until all checks are green — no need to ask first.
 
+## Files synced with other repositories
+
+- Files starting with a `sync with <url>` comment are shared with other repositories. Keep them
+  structurally in sync and mention in the PR description when a change should be ported to the
+  referenced file as well.
+
 ## GitHub comments that @-mention a bot
 
 - Commands like `@dependabot rebase` must reach GitHub as plain text — tool-call composition can
   silently insert stray characters (e.g. interpunct `·`) into `@mentions`, which stops the bot from
-  recognizing the command.
-- After posting such a comment, read it back and confirm the body matches exactly what was
-  intended; if not, fix it immediately with an update rather than leaving a broken command posted.
+  recognizing the command. This has happened **repeatedly**, even with this rule in place, so the
+  following steps are **mandatory**:
+  - Before posting, check that the comment body is plain ASCII and contains no `·` (U+00B7).
+  - Post such comments **one at a time**, never several in parallel.
+  - Immediately after posting, read the comment back from GitHub and compare it character by
+    character with the intended text. Only then post the next one.
+  - If the body is wrong, edit the comment to the exact intended text (Dependabot does act on
+    edited comments) and read it back again — don't leave a broken command posted.
+- The same corruption also hits `@mentions` in PR descriptions and other GitHub text. Don't quote
+  bot commands literally there (describe them instead, e.g. "the Dependabot rebase command"), and
+  read every PR description back after creating or updating it.
+
+## Pull request descriptions
+
+- Don't include the Claude session URL — it's private. A footer containing it may be appended
+  automatically when a PR is created; read the description back and remove it with an update.