code-placement-philosophy
shared code placed above the lowest level that reaches it, or landing in `common/` as a folder-module
Agent checkadvisory by defaultbasecode
The argument
Code Placement Philosophy
Place shared code at the lowest common ancestor common/ folder (each package's architecture doc defines the concrete hierarchy):
- First: search whether it already exists in
common/at any level — if found, use it. - Second: if not found, start local and promote later — moving code up when reuse is proven beats premature generalization.
- When promoting, the destination is decided by the companion test: a single-file primitive goes to the ancestor level's
common/<type>/; a shared concept with private companions becomes its own module at that level.common/never contains folder-modules — shared code is a primitive or a module, never a third thing.
Import granularity follows the import rule (module-api.md): every import names the file that declares what it imports. Never import through an index.ts, and never from your own package's entry.
The proof
fail
export const formatMoney = ({ cents }: { cents: number }): string => `$${(cents / 100).toFixed(2)}`;
pass
import { formatMoney } from '../common/utils/formatMoney';
export const getChargeLabel = ({ cents }: { cents: number }): string => `Charged ${formatMoney({ cents })}`;
Turn it down
Both lines go in your lightsout.config.json.
"standards-checks": { "code-placement-philosophy": "advisory" }"standards-checks": { "code-placement-philosophy": "off" }