docs(doctrine): foreign code keeps its own style, limits stay strict in ours

This commit is contained in:
bchanot committed 2026-10-23 16:54:46 +02:00
1 parent 70e0f9ac41
commit 71d28f8616
5 files changed
+31 -10

No files matched your search

+15 -2
View File
@@ -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.
+7 -6
View File
@@ -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.
---
+3 -1
View File
@@ -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
+4
View File
@@ -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
+2 -1
View File
@@ -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"}
]