From 6a23dfeec1632d25736fcbff33cc9fb2a53d4e1c Mon Sep 17 00:00:00 2001 From: LeonTung Date: Mon, 27 Apr 2026 12:03:32 +0800 Subject: [PATCH] chore(CLAUDE.md): add shared UI component lock convention to CLAUDE.md (#14381) ### What problem does this PR solve? AI coding agents (Claude, Copilot, etc.) tend to directly edit files in `src/components/ui/` when asked to tweak styles or add props, treating them like ordinary feature code. This silently breaks the shared component library that both shadcn primitives and project-authored common components live in. This PR adds a `Shared UI Component Lock` convention to `web/CLAUDE.md` to instruct AI agents to treat the entire `src/components/ui/` directory as read-only. Any customization must be done via wrappers or composition outside the directory; exceptions require explicit user approval. ### Type of change - [x] Other (please describe): Update `CLAUDE.md` --- web/CLAUDE.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/web/CLAUDE.md b/web/CLAUDE.md index 126d32217d..822689cd09 100644 --- a/web/CLAUDE.md +++ b/web/CLAUDE.md @@ -41,6 +41,14 @@ When refactoring or extracting components, **verify layout behavior after each s For React Query / cache invalidation bugs, **carefully compare query keys across all consuming components and mutation hooks**. Mismatched keys (e.g., with/without `refreshCount`) are a common root cause of stale data or duplicate requests. - Systematically: (1) list every component/hook that calls `useQuery` for this data, (2) compare their query keys character-for-character, (3) check every mutation's `onSuccess` for cache invalidation, and (4) verify no parent re-renders are remounting the observer. +### Shared UI Component Lock +The folder `src/components/ui/` is the project's **shared UI library** — it contains both official shadcn/ui primitives and project-authored common components built on top of shadcn. Both kinds are intended to be reused across the app and **must not be modified casually**. + +- **Do not modify, refactor, restyle, or "improve"** any file under `src/components/ui/` (including subfolders), even if it seems like the most direct fix. +- If a component does not meet requirements, **wrap or compose it** in a new component **outside** `src/components/ui/` (e.g., under `src/components/` or a feature folder), and customize via `className`, `props`, or composition. +- Exceptions require **explicit user approval** in the same conversation. When in doubt, ask first and propose a wrapper-based alternative. +- Adding a new shared component to `src/components/ui/`, or upgrading a shadcn primitive via the official `shadcn` CLI, is allowed only when the user explicitly requests it. + ### React Patterns and Conventions - **Prefer `requestAnimationFrame` or `useLayoutEffect`** over `setTimeout(..., 0)` for focus or DOM measurement operations. - **Prefer `useTranslation` from `react-i18next`** over project-wrapped utilities like `useTranslate`.