فهرست منبع

add AGENTS.md with instructions for coding agents (#154)

Gives coding agents the same conventions as the sibling container image repositories, including merging pull requests without rewriting signed commits (e.g. fast-forwarding to Dependabot's own commits), after Dependabot pull requests were merged with merge commits.

The final section documents how to base new `AGENTS.md` files on those of the other repositories, as done here.

Sources (only rules fitting this repository; Python / Pipfile specific rules omitted):
- base: https://github.com/fphammerle/docker-postfix/blob/129674aa0010b936ff669f42734c829c10deaf38/AGENTS.md (closest sibling: `Dockerfile`-only mail container image with a synced `dependabot.yml`), package version convention adapted to `POSTSRSD_PACKAGE_VERSION` and the `v<version>` subjects used in this repository's history
- sections "Merging pull requests" and the exception to "never push directly to `master`": https://github.com/fphammerle/docker-borgbackup-sshd/blob/5dd5edc6fb274fe8b180e6649789600ff9915270/AGENTS.md (proposed in fphammerle/docker-borgbackup-sshd#140)
- Dependabot rebase after CI fixes and the note on bot comments being corrupted on creation: https://github.com/fphammerle/docker-onion-service/blob/b5ce9a151b39feac9555fae3c97e20441e7d775b/AGENTS.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Fabian Peter Hammerle 1 هفته پیش
والد
کامیت
7432ceb2e5
1فایلهای تغییر یافته به همراه118 افزوده شده و 0 حذف شده
  1. 118 0
      AGENTS.md

+ 118 - 0
AGENTS.md

@@ -0,0 +1,118 @@
+# 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>`
+  (see https://web.archive.org/web/20261016172400/https://docs.github.com/en/pull-requests/how-tos/commit-changes/creating-a-commit-with-multiple-authors)
+- 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. `POSTSRSD_PACKAGE_VERSION` in `Dockerfile`): keep the subject line
+  `upgrade <package> package from v<old> to v<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, changes to address rewriting or the socketmap interface).
+- Never justify a package version update with the old pinned version no longer being installable
+  or the build failing because of it (e.g. "so the pinned version can no longer be installed") —
+  pins are intentional and breaking when the distribution moves on is their whole point. Keep the
+  version pinned; this applies to PR descriptions as well.
+
+## 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
+
+- Rebase on `master` before opening a PR.
+- One commit per PR; amend rather than adding new commits.
+- Force-push with `--force-with-lease` on feature branches.
+- **Never force-push to `master`.**
+- **Always open a pull request — never push directly to `master`** (the only exception is
+  fast-forwarding `master` to a pull request's head commit, see "Merging pull requests").
+- **Never amend or force-push a branch whose PR is already merged or closed** — that rewrites
+  history that's already landed (or been reviewed) and leaves a dangling branch that no longer
+  reflects what merged. For a follow-up change, create a **new** branch (from current `master`)
+  and a **new** PR instead.
+
+## Merging pull requests
+
+- Keep existing commit signatures: never rewrite commits when merging — no GitHub squash or rebase
+  merge, no cherry-picking or re-creating commits locally. Rewriting replaces signed commits (e.g.
+  Dependabot's) with new, unsigned or differently signed ones.
+- Pull requests / branches with a **single commit**, or whose changes should be squashed into a
+  single commit: **fast-forward** `master` to the branch's head commit, so that exact commit lands
+  on `master`.
+  - Squashing belongs on the branch, done by its author — squashing someone else's signed commits
+    yourself would drop their signatures.
+  - The head commit's parent must be the current `master` tip. If it isn't, have the branch
+    rebased by its author (for Dependabot: the rebase command, see "GitHub comments that
+    @-mention a bot").
+  - All checks must have passed on **that exact head commit** — a push to `master` doesn't wait
+    for them the way GitHub's merge button does.
+  - Then push the head commit: `git push origin <head-sha>:master` (no force) — GitHub marks the
+    pull request as merged.
+- Pull requests / branches with **multiple commits that should stay separate**: create a merge
+  commit (GitHub merge method `merge`).
+- Never call GitHub's merge API without an explicit merge method, and never use `squash` or `rebase`.
+
+## CI failures
+
+- Fix CI failures automatically, iterating until all checks are green — no need to ask first.
+- After a fix for a failing build is merged into `master`, **automatically** comment the
+  Dependabot rebase command on each of Dependabot's open pull requests (without being asked), so
+  their checks re-run on top of the fix instead of staying red. Follow the mandatory steps in
+  "GitHub comments that @-mention a bot" below.
+
+## 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. 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.
+  - Creating the comment has corrupted the body **every time** so far, while editing it to the
+    same text came through intact — so never consider a bot command posted after the create
+    call alone; the read-back and (almost always needed) edit are part of posting it.
+- 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.
+
+## `AGENTS.md` across repositories
+
+- The `AGENTS.md` files of the owner's repositories share most of their rules. Find them all with
+  a GitHub code search for `user:fphammerle filename:AGENTS.md`.
+- Creating an `AGENTS.md` for a repository: base it on **all** of them, not just one. Start from
+  the closest sibling, keep only the rules that fit the particular repository (e.g. no Python /
+  `Pipfile` rules for a `Dockerfile`-only repository), and adapt repository-specific examples
+  (e.g. package names, commit subject conventions from `git log`). In the commit message, reference
+  the individual source each part was based on with full permanent URLs (commit hash + path).