From 71d28f8616477aca6ad3b89112c3c85c0a19bcd7 Mon Sep 17 00:00:00 2001 From: bchanot Date: Fri, 23 Oct 2026 16:54:46 +0200 Subject: [PATCH] docs(doctrine): foreign code keeps its own style, limits stay strict in ours --- CLAUDE.global.md | 17 +++++++++++++++-- agents/refactorer.md | 13 +++++++------ skills/audit-delta/SKILL.md | 4 +++- skills/refactor/SKILL.md | 4 ++++ skills/refactor/test-prompts.json | 3 ++- 5 files changed, 31 insertions(+), 10 deletions(-) diff --git a/CLAUDE.global.md b/CLAUDE.global.md index 82e4e18..6f3e5e3 100644 --- a/CLAUDE.global.md +++ b/CLAUDE.global.md @@ -2,7 +2,20 @@ Repo-specific instructions live in ./CLAUDE.md (project scope). --> # Global coding preferences -Apply unless repo-specific instructions override. +Strict in our code (project started by the user or Claude). Foreign +code (`bash ~/.claude/lib/code-origin.sh` → foreign) → "Foreign +code" wins. Repo-specific instructions override both. + +## Foreign code: keep its style +- Existing code's style is the norm unless the user says otherwise: + function granularity, file layout, naming, comment density, error + handling, idioms. Write like the neighbouring code. +- Neighbours work inline → work inline: no function, helper or + abstraction the file would not have written. Reuse what is in + scope (variables, macros, sizeof). +- Limits become guidelines: exceed them where the file's style + needs it. +- No refactor toward our norms unless asked. ## Code style - Simple, readable, maintainable > clever or compact. @@ -17,7 +30,7 @@ Apply unless repo-specific instructions override. - Assumed shortcut → `shortcut:` comment at the site (limit + upgrade path), harvested into TODO.md so "later" stays findable. -## Limits (adapt to language) +## Limits (our code: strict; foreign code: see above) - Max 25 logic lines/function (executable statements; comments and error-handling boilerplate don't count), 80 chars/line, 5 params, 5 locals. - Too many params → struct/object. Too many vars → split/extract. diff --git a/agents/refactorer.md b/agents/refactorer.md index e5480f6..4ca9fe9 100644 --- a/agents/refactorer.md +++ b/agents/refactorer.md @@ -57,12 +57,13 @@ TESTS PRESENT: yes / no ## NORMS TO APPLY (from CLAUDE.md) -- Max 25 lines per function (excluding comments) -- Max 80 chars per line -- Max 5 parameters per function -- Max 5 local variables per function -- No global variables -- Function comments when role is not obvious +The norms are the "Limits" and "Code style" sections of the global CLAUDE.md, +read them there. Function comments when role is not obvious. + +Origin first: run `bash ~/.claude/lib/code-origin.sh` on the target repo. +`foreign` → refactor toward the file's own style (granularity, layout, +naming, idioms, "Foreign code: keep its style"), never toward the limits, +unless the dispatch prompt explicitly asks for the limits. --- diff --git a/skills/audit-delta/SKILL.md b/skills/audit-delta/SKILL.md index 39de32d..c0a6c3a 100644 --- a/skills/audit-delta/SKILL.md +++ b/skills/audit-delta/SKILL.md @@ -277,7 +277,9 @@ Then offer to capitalize (per CLAUDE.md): recurring finding patterns → FIRST, then check changed code against those norms. This repo's: ≤25 logic lines/function, ≤80 chars/line, ≤5 params, ≤5 locals, no global state, intent-not-mechanics comments, explicit naming, versioned - APIs (`/api/v1/`), no-SPA-for-public-sites, security defaults. + APIs (`/api/v1/`), no-SPA-for-public-sites, security defaults. Foreign + code (`bash ~/.claude/lib/code-origin.sh` → foreign): measure consistency + with the existing style instead of the limits; security stays strict. - **deadcode** — dead/zombie introduced OR orphaned by the delta: unused functions/exports/imports/vars, unreachable branches, stale feature flags, commented-out blocks, references to deleted files/symbols diff --git a/skills/refactor/SKILL.md b/skills/refactor/SKILL.md index b3720dd..7b47007 100644 --- a/skills/refactor/SKILL.md +++ b/skills/refactor/SKILL.md @@ -16,6 +16,10 @@ model). The scope you name is the only reflection; the agent applies norms. and dispatch on the new branch; on a working branch dispatch in place. Never `gitflow finish` — integration is human-gated. +Origin: `bash ~/.claude/lib/code-origin.sh` on the target repo. `foreign` → +the refactorer aligns on the existing style, not on the limits, unless the +user asked for the limits explicitly; add that to the prompt below. + ``` Agent(subagent_type="refactorer") prompt: "Refactor to strict project norms, preserving external behavior diff --git a/skills/refactor/test-prompts.json b/skills/refactor/test-prompts.json index 69f1df3..8914820 100644 --- a/skills/refactor/test-prompts.json +++ b/skills/refactor/test-prompts.json @@ -1,5 +1,6 @@ [ {"id": 1, "prompt": "Refactor src/services/payment.ts — it's gotten messy", "expected": "Read file, apply project norms (≤25 logic lines/function, ≤80 chars/line, ≤5 params), preserve external behavior, run tests after"}, {"id": 2, "prompt": "Refactor the calculateOrderTotal function — too long, too many vars", "expected": "Extract sub-functions, name explicit, no behavior change, verify tests still pass"}, - {"id": 3, "prompt": "Clean up the auth module without changing behavior", "expected": "Module-level refactor, dead code removal, consistency, all original public API preserved"} + {"id": 3, "prompt": "Clean up the auth module without changing behavior", "expected": "Module-level refactor, dead code removal, consistency, all original public API preserved"}, + {"id": 4, "prompt": "Refactor src/net.c in this third-party repo (code-origin says foreign)", "expected": "Align on the file's own style (inline branches, existing variables and macros), no extraction toward the 25-line limit unless the user asks for the limits"} ]