# 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 ` — always include the model name, e.g. `Co-Authored-By: Claude Sonnet 4.6 ` (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///blob//`. - 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 from to ` 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). - 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. - This has happened despite this rule, so before **every** amend / push to an existing branch, first fetch its PR's current state from GitHub — pull requests may have been merged since you last looked. - After a branch has been **fully** merged into `master`, delete it (on GitHub and locally). If only a subset of its commits was merged, keep it and rebase the remaining commits onto `master` instead (`git rebase --onto origin/master `). ## 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 :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 ` 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, no rules on `Dockerfile` version pins for a repository without a `Dockerfile`), 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).