#399

AGENTS.md

@@ -335,6 +335,113 @@ Good:
       ? 'warning'
       : 'ready'))
 ```
+
+## Shared-system discovery and reuse
+
+Before creating a new component, hook, service, helper, utility, concern,
+representation, normaliser, validator, parser, fetcher, store, context, event
+bus, API client, query key, permission helper, dialogue, toast, form field, or
+version recorder, search the existing repository first.
+
+Do not search by name alone. Search by responsibility, behaviour, and usage
+intent as well. Typical search themes include:
+
+- dialogue, modal, confirm, alert, choice
+- validation error, field error, unprocessable entity
+- permission, role, member, admin, editable
+- URL normalise, sanitise, canonicalise
+- API call, query key, prefetch, cache invalidation
+- version, snapshot, history, restore
+- thumbnail, metadata, HTTP fetch, URL safety
+- form, field, input, textarea, warning, status badge
+- file storage, Active Storage, ZIP, export
+- transaction, locking, race, idempotency
+
+Before deciding that something new is needed, confirm at least:
+
+1. the existing definition
+2. its public API
+3. representative call sites
+4. other implementations with similar responsibility
+5. the nearest directory-level `AGENTS.md`
+
+Do not reject an existing implementation by name alone. Read the code and its
+usage first.
+
+When new behaviour is needed, make the decision in this order:
+
+1. use the existing common API as-is
+2. use the existing extension points of that API
+3. extend the existing common API minimally
+4. keep the implementation local when the meaning is feature-specific
+5. add a new common system only when multiple real users and a stable contract
+   are already clear
+
+Do not create a parallel foundation merely because the existing one feels
+slightly awkward, because a new one seems faster, or because the current task
+looks special.
+
+Do not create a second common platform with names such as `CommonFoo`,
+`SharedFoo`, `BaseFoo`, `FooManager`, `FooService`, `FooProvider`,
+`FooWrapper`, `FooUtils`, or `useFoo` when an existing system already owns the
+same responsibility. Judge by responsibility, not by spelling.
+
+Wrapper aliases, barrel exports, and re-export shims do not count as reuse.
+Using a different import path that merely forwards to the existing system does
+not satisfy a reuse requirement.
+
+Keep this boundary explicit:
+
+- business meaning stays in feature code
+- visual and mechanical shell stays in common code
+
+Common code may hold generic primitives, interaction shells, API transport,
+auth and permission helpers, query-key and prefetch conventions, validation
+error conversion, shared normalisation, version-recording mechanisms, storage
+helpers, HTTP safety, and other contracts that carry the same meaning across
+multiple features.
+
+Feature code should keep feature-specific states, labels, input fields,
+workflow steps, payload shapes, validation rules, and business decisions.
+
+Do not commonise business logic merely because the visuals look similar or two
+code fragments resemble each other.
+
+Create a new common system only when all of the following are true:
+
+- no existing implementation already owns the responsibility
+- there are multiple real consumers, or a clearly defined platform contract
+- the differences between consumers do not require option bloat
+- feature-specific vocabulary does not leak into common types, props, tones, or
+  state names
+- the location matches the existing directory structure
+- the new abstraction does not compete with an existing common system
+- it is not just a one-off wrapper for a single task
+
+Do not add unused tones, variants, options, callbacks, states, or abstractions
+for speculative future use.
+
+Before finishing work that touches shared systems, verify:
+
+- you searched for an existing implementation with the same responsibility
+- you are using the canonical import path or entrypoint
+- feature code is not reaching directly for a low-level primitive that already
+  has a higher-level common API
+- you did not bypass an existing common API
+- any new wrapper or shim is genuinely necessary
+- feature-specific vocabulary did not leak into common code
+- the feature did not reimplement a common shell
+- existing unrelated consumers were not changed without need
+- one task did not trigger a needless redesign of the whole foundation
+- any newly introduced common system really has multiple consumers
+
+For backend-specific discovery, Rails structure, services, representation
+selection, versioning, normalisation, and HTTP safety, follow
+`backend/AGENTS.md`.
+
+For frontend-specific component hierarchy, low-level primitive reuse, dialogue
+entrypoints, API/query helpers, validation/form infrastructure, state/storage,
+and layout reuse, follow `frontend/AGENTS.md`.
 - In TypeScript and TSX, do not write `let` followed by later `if` assignments
   when the value can be expressed as a single `const` initializer. Prefer
   `const` because it prevents accidental later reassignment.