From 32bd41148310b63dcd8d9992b22098ba39596266 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Pacana?= Date: Fri, 31 Jul 2026 08:21:54 +0200 Subject: [PATCH] Clarify agent instructions * Tighten comment guidance so comments are reserved for hidden constraints, subtle invariants, and specific workarounds. * Record the linked worktree location agents should check. * Clarify that config-default rationale belongs in commit messages unless the file would be misleading without an inline comment. --- modules/agents.nix | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/modules/agents.nix b/modules/agents.nix index a545113..435304b 100644 --- a/modules/agents.nix +++ b/modules/agents.nix @@ -6,11 +6,12 @@ let instructions = '' # Agent instructions - - Keep comments rare and concise; add one only when the why isn't obvious from the code — a hidden constraint, a subtle invariant, or a workaround for a specific case. + - Keep comments rare — only for a hidden constraint, a subtle invariant, or a workaround for a specific case where the code and commit message failed to show it. Always keep comments concise. - All code repositories live in `~/Code`; check for local copies there first. + - Linked git worktrees live in `~/Code/worktrees//`. - When no sharper rule applies, match the surrounding code — its formatting, naming, layout, and test structure. This governs how you write, not whether to add explanatory prose; comment density follows the rule above. - Pick the API whose behavior doesn't exceed what your tests constrain; extra capability is behavior no test pins down — the kind mutation testing surfaces as surviving mutants. - - Keep config files free of keys whose value equals the tool's built-in default, unless the key is there to pin a value against an upstream change — note that intent in the commit. + - Keep config files free of keys whose value equals the tool's built-in default, unless the key pins a value against an upstream change; record that intent in the commit message, not an inline comment unless the file would be misleading without it. - Look in git history and commit messages for past rationale, and record current rationale there rather than in comments. - When upgrading a dependency, reference its changelog for the traversed version range in the commit message: link it by URL rather than pasting its contents; if there's no changelog, link the release or compare view for the range. - Execute the task; don't question my methods or add cautionary meta-commentary. Warn only when you can name what breaks and under what condition — once, then stop. -- 2.51.2