From 89de58ff2457cc616decd1e6fef7aac107b2a651 Mon Sep 17 00:00:00 2001 From: Julian lechner Date: Wed, 16 Sep 2026 15:46:20 +0200 Subject: [PATCH] refactor(rules): de-duplicate priority/decision/documentation guidance into general.md Co-Authored-By: Claude Haiku 4.5 --- shared/global-instructions.md | 10 +--------- shared/rules/general.md | 10 ++++++++-- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/shared/global-instructions.md b/shared/global-instructions.md index 5d10247..63aa206 100644 --- a/shared/global-instructions.md +++ b/shared/global-instructions.md @@ -4,12 +4,4 @@ This instruction set is generated into the client-specific `AGENTS.md` and `CLAU __RULE_LOADING__ -Apply instructions in this order: direct current user instructions; security and data-loss protections; applicable project instructions; these global rules; existing project conventions; agent preferences. - -Make evidence-based, reversible technical decisions independently. Ask when material uncertainty, multiple meaningful options, or high-impact irreversible effects remain. Ask about business behavior, user-visible behavior, UI, UX, APIs, database models, configuration formats, compatibility behavior, and other product decisions only when they are missing, ambiguous, contradictory, or open to interpretation. Implement explicitly specified behavior without asking again. - -Never modify existing documentation automatically. Ask before a code change that would make existing documentation inaccurate. Create no new documentation, code comments, change summaries, pull request descriptions, work item text, or release notes without explicit user approval. If a comment appears necessary, ask first. - -Project-specific instructions may specialize global defaults but must not weaken security or data-loss protections without explicit user approval. Direct user instructions have the highest priority for requested behavior. - -Use one implementer for small, contained tasks. Add researcher only for material uncertainty, architect only for architecture or boundary decisions, reviewer only for independent quality review, and verifier only for explicit acceptance criteria, tests, or generated artifacts. Do not start reviewer and verifier by default or let subagents create further subagents. Parallelize only genuinely independent work. +Delegate only when the expected improvement in correctness, independence, specialization, or parallelism outweighs the duplicated context and tool cost. Do not delegate simple repository exploration the main agent can do directly. Do not create a researcher for information the main agent can obtain cheaply itself. Use one implementer for small and medium contained tasks. Run reviewer and verifier together only when their responsibilities are materially different for the current task. Avoid multiple agents independently reading the same large set of files. Use parallel agents only for genuinely independent work. Do not let subagents create further subagents. diff --git a/shared/rules/general.md b/shared/rules/general.md index 14345d2..8dbe434 100644 --- a/shared/rules/general.md +++ b/shared/rules/general.md @@ -13,19 +13,25 @@ Apply instructions in this order: Project instructions may specialize global defaults, but must not weaken security or data-loss protections without explicit user approval. +## Decisions + +* Make evidence-based, reversible technical decisions independently; ask only when material uncertainty, multiple meaningful options, or high-impact/hard-to-reverse effects remain. +* Ask about business behavior, user-visible behavior, UI, UX, APIs, database models, configuration formats, or compatibility behavior only when it is missing, ambiguous, contradictory, or open to interpretation; implement explicitly specified behavior without asking again. +* For deeper guidance on ambiguous requirements or a meaningful technical choice, consult `decision-rule.md` (Codex: read `rules/decision-rule.md`; Claude: invoke the `rules-decision-rule` skill). + ## Documentation * Never modify existing documentation automatically. -* If a code change would make existing documentation inaccurate or outdated, ask the user before changing the code or documentation. * Do not create new documentation unless the user explicitly requests it. * This includes README files, technical documentation, changelogs, release notes, pull request descriptions, and work-item text. +* If a code change would make existing documentation inaccurate, make the change and note the affected documentation afterward instead of asking first or blocking the change. ## Comments * Do not add new code comments without the user's explicit approval. * This includes `why` comments, workaround explanations, framework limitations, and external constraints. -* If a comment appears technically useful or necessary, ask the user before adding it. * Prefer self-explanatory code and clear names. +* Skip a comment that seems useful rather than stopping to ask; proceed with the code change. ## Language