docs(doctrine): foreign code keeps its own style, limits stay strict in ours
This commit is contained in:
1 parent
70e0f9ac41
commit
71d28f8616
5 files changed
+31
-10
No files matched your search
+15
-2
@@ -2,7 +2,20 @@
|
|||||||
Repo-specific instructions live in ./CLAUDE.md (project scope). -->
|
Repo-specific instructions live in ./CLAUDE.md (project scope). -->
|
||||||
|
|
||||||
# Global coding preferences
|
# 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
|
## Code style
|
||||||
- Simple, readable, maintainable > clever or compact.
|
- 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
|
- Assumed shortcut → `shortcut:` comment at the site (limit + upgrade
|
||||||
path), harvested into TODO.md so "later" stays findable.
|
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
|
- Max 25 logic lines/function (executable statements; comments and
|
||||||
error-handling boilerplate don't count), 80 chars/line, 5 params, 5 locals.
|
error-handling boilerplate don't count), 80 chars/line, 5 params, 5 locals.
|
||||||
- Too many params → struct/object. Too many vars → split/extract.
|
- Too many params → struct/object. Too many vars → split/extract.
|
||||||
|
|||||||
@@ -57,12 +57,13 @@ TESTS PRESENT: yes / no
|
|||||||
|
|
||||||
## NORMS TO APPLY (from CLAUDE.md)
|
## NORMS TO APPLY (from CLAUDE.md)
|
||||||
|
|
||||||
- Max 25 lines per function (excluding comments)
|
The norms are the "Limits" and "Code style" sections of the global CLAUDE.md,
|
||||||
- Max 80 chars per line
|
read them there. Function comments when role is not obvious.
|
||||||
- Max 5 parameters per function
|
|
||||||
- Max 5 local variables per function
|
Origin first: run `bash ~/.claude/lib/code-origin.sh` on the target repo.
|
||||||
- No global variables
|
`foreign` → refactor toward the file's own style (granularity, layout,
|
||||||
- Function comments when role is not obvious
|
naming, idioms, "Foreign code: keep its style"), never toward the limits,
|
||||||
|
unless the dispatch prompt explicitly asks for the limits.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -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:
|
FIRST, then check changed code against those norms. This repo's:
|
||||||
≤25 logic lines/function, ≤80 chars/line, ≤5 params, ≤5 locals, no
|
≤25 logic lines/function, ≤80 chars/line, ≤5 params, ≤5 locals, no
|
||||||
global state, intent-not-mechanics comments, explicit naming, versioned
|
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
|
- **deadcode** — dead/zombie introduced OR orphaned by the delta: unused
|
||||||
functions/exports/imports/vars, unreachable branches, stale feature
|
functions/exports/imports/vars, unreachable branches, stale feature
|
||||||
flags, commented-out blocks, references to deleted files/symbols
|
flags, commented-out blocks, references to deleted files/symbols
|
||||||
|
|||||||
@@ -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
|
and dispatch on the new branch; on a working branch dispatch in place. Never
|
||||||
`gitflow finish` — integration is human-gated.
|
`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")
|
Agent(subagent_type="refactorer")
|
||||||
prompt: "Refactor to strict project norms, preserving external behavior
|
prompt: "Refactor to strict project norms, preserving external behavior
|
||||||
|
|||||||
@@ -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": 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": 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"}
|
||||||
]
|
]
|
||||||
Reference in new issue
Block a user