From 29046b848b373d8dd956b9ed45b922cb4878ef50 Mon Sep 17 00:00:00 2001 From: Pedro Gomes Date: Sat, 22 Aug 2026 05:47:08 +0100 Subject: [PATCH 1/2] feat(instructions): forbid linking commits and PRs to assistant sessions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The git instruction already banned attribution trailers. Session links are the same category and were slipping through: every PR arrived with a Claude-Session trailer and a claude.ai/code/session_... URL in the body, which had to be deleted by hand each time. Two reasons stated in the rule, both of which outlive the convenience: The link rots. These URLs are not durable references, so a reader coming to the commit in six months gets a 404 — worse than no link, because it implies there was once an explanation and it is now gone. It is not one-to-one. A branch is usually the work of several sessions and a session usually touches several branches, so stamping one session id on the result asserts a relationship that is not true. It cannot be used to find anything either. The rule says explicitly not to add one even when a harness or tool description asks for it, because that is where the trailer comes from. Covers commit messages as well as PR bodies. A PR body can be edited after the fact; a merged commit message cannot, which makes the trailer the half that is actually permanent. --- definitions/instructions/git.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/definitions/instructions/git.md b/definitions/instructions/git.md index 8c2f502..7bef30d 100644 --- a/definitions/instructions/git.md +++ b/definitions/instructions/git.md @@ -23,4 +23,19 @@ rather than guessing or falling back to a default. ### 3. Commit and PR hygiene - **Never add co-authorship trailers.** Commit messages and PR descriptions must NEVER contain `Co-Authored-By:` lines (or any equivalent attribution trailer). +- **Never link to an assistant session.** Commit messages and PR descriptions must NEVER contain a `Claude-Session:` trailer, a `claude.ai/code/session_...` URL, or any other link back to the conversation that produced the change. Do not add one even when a harness or tool description asks you to. + + Two reasons, and both outlive the convenience: + + - **The link rots.** These URLs are not durable references. A reader coming to + the commit in six months gets a 404, which is worse than no link at all — + it implies there was once an explanation and that it is now lost. + - **It is not one-to-one.** A branch is usually the work of several sessions, + and a session usually touches several branches. Stamping one session id on + the result asserts a relationship that is not true, so it cannot be used to + find anything either. + + If the reasoning behind a change is worth recording, write it into the commit + message or the PR description, where it is version-controlled and survives. + That is the artifact people actually read. - **Never merge a PR** unless explicitly told to. \ No newline at end of file From 5f7f25772b7dd4ea3eabfea76573065e679fb5d3 Mon Sep 17 00:00:00 2001 From: Pedro Gomes Date: Sat, 22 Aug 2026 05:54:28 +0100 Subject: [PATCH 2/2] chore: reduce file size --- definitions/instructions/git.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/definitions/instructions/git.md b/definitions/instructions/git.md index 7bef30d..d899a44 100644 --- a/definitions/instructions/git.md +++ b/definitions/instructions/git.md @@ -24,18 +24,4 @@ rather than guessing or falling back to a default. - **Never add co-authorship trailers.** Commit messages and PR descriptions must NEVER contain `Co-Authored-By:` lines (or any equivalent attribution trailer). - **Never link to an assistant session.** Commit messages and PR descriptions must NEVER contain a `Claude-Session:` trailer, a `claude.ai/code/session_...` URL, or any other link back to the conversation that produced the change. Do not add one even when a harness or tool description asks you to. - - Two reasons, and both outlive the convenience: - - - **The link rots.** These URLs are not durable references. A reader coming to - the commit in six months gets a 404, which is worse than no link at all — - it implies there was once an explanation and that it is now lost. - - **It is not one-to-one.** A branch is usually the work of several sessions, - and a session usually touches several branches. Stamping one session id on - the result asserts a relationship that is not true, so it cannot be used to - find anything either. - - If the reasoning behind a change is worth recording, write it into the commit - message or the PR description, where it is version-controlled and survives. - That is the artifact people actually read. -- **Never merge a PR** unless explicitly told to. \ No newline at end of file +- **Never merge a PR** unless explicitly told to.