CLAUDE.md

1Use these rules as defaults, not as a reason to add ceremonial folders or wrapper layers.
2 
3## Core Principles
4 
5- Organize code around product capabilities, not framework vocabulary.
6- Keep related UI, state, rules, and data access close until a real boundary justifies moving
7  them apart.
8- Dependencies point from composition and UI toward stable rules and narrow capabilities.
9- Protect rendering code from business, state-management, and infrastructure complexity.
10- Keep one source of truth and derive everything else.
11- Apply KISS, YAGNI, and DRY together. Remove duplicated knowledge, not merely similar syntax.
12- Prefer explicit, readable flow over clever abstractions and hidden behavior.
13 
14## Screaming Architecture
15 
16The repository structure and public APIs should reveal what the product does.
17 
18Prefer:
19 
20```text
21features/
22  checkout/
23  search/
24  account-security/
25```
26 
27Avoid making the application read primarily as:
28 
29```text
30components/
31hooks/
32services/
33stores/
34utils/
35```
36 
37Technical folders are useful inside a capability, where their owner is clear. Generic top-level
38folders easily become dependency magnets with unclear ownership.
39 
40Names should use product language. Prefer `useCheckoutSummary`, `reserveStock`, and
41`AccountSecurityPanel` over `useData`, `processItems`, and `GenericPanel`.
42 
43## Suggested Structure
44 
45Start with the smallest structure that makes ownership obvious:
46 
47```text
48src/
49  app/                 startup, providers, router, global composition
50  pages/               route-level composition
51  features/
52    <capability>/
53      index.ts         optional public API
54      ui/              optional rendering components
55      model/           optional state, view models, decisions
56      api/             optional external data access
57      lib/             optional feature-local pure helpers
58  domains/             optional shared product rules and types
59  shared/
60    ui/                domain-free visual primitives
61    api/               generic transport/query infrastructure
62    lib/               genuinely generic pure helpers
63```
64 
65Folders are created when they contain a real responsibility. A small feature may be one cohesive
66file. Do not create empty layers in anticipation of future complexity.
67 
68## Dependency Direction
69 
70- `app` installs providers, constructs dependencies, and composes the application.
71- `pages` compose capabilities for a route. They do not own business rules or data protocols.
72- A feature owns one user-recognizable capability end to end.
73- Feature UI consumes its own model/view-model API, not raw infrastructure.
74- Shared domain code contains reusable product rules and stays independent of React and I/O.
75- `shared` contains only domain-free code. Product-specific code is not shared merely because
76  two files use it.
77- Avoid feature-to-feature imports. Compose features in a page, promote truly shared rules to a
78  domain module, or introduce a named workflow when coordination is the actual responsibility.
79- Cyclic imports are an architecture problem, not something to solve with a tooling workaround.
80 
81For a simple feature, direct `ui -> model -> api` dependencies are sufficient. Introduce ports,
82facades, dependency injection, or workflows only when they hide real complexity, enable
83important tests, or separate unstable infrastructure.
84 
85## Make Composition Read Like The Product
86 
87Pages and other composition boundaries should use capability-level APIs.
88 
89Prefer:
90 
91```tsx
92<CheckoutSummary />
93<PlaceOrderButton />
94```
95 
96Over:
97 
98```tsx
99<Card>
100  <Select options={paymentOptions} onChange={handlePaymentChange} />
101  <Button onClick={handleSubmit}>Submit</Button>
102</Card>
103```
104 
105The second version makes the page understand checkout behavior and low-level UI configuration.
106That knowledge belongs to the checkout capability.
107 
108This does not mean wrapping every native element or design-system primitive. Semantic HTML and
109visual primitives are correct inside feature UI. Create a capability component when it hides
110product behavior or gives composition code a clearer product-level API.
111 
112Avoid "raw components" whose consumers must know internal options, state transitions, query
113shapes, or protocol details. Avoid generic configuration-driven components that combine
114unrelated product modes behind dozens of props.
115 
116## UI Boundary
117 
118- Components render data and translate DOM events into named user intents.
119- Keep business decisions, data mapping, persistence, protocol handling, and multi-step async
120  flows outside rendering components.
121- UI receives render-ready values. It should not reconstruct domain meaning from raw DTOs.
122- Prefer intent props and commands such as `onApprove`, `renameProject`, or `submitOrder` over
123  generic `onChange`, `setState`, or `patch` APIs at capability boundaries.
124- Keep ephemeral visual state local: focus, hover, open/closed, and uncommitted input usually
125  belong in the component.
126- Split components by responsibility and API clarity, not by arbitrary line limits.
127- Prefer slots and composition over components with many layout modes and boolean props.
128- Use semantic HTML and preserve accessibility behavior.
129 
130A view-model hook is useful when it protects UI from state shape, async coordination, or business
131decisions. Do not create a pass-through hook that only renames one value to satisfy a diagram.
132 
133## State Ownership
134 
135Choose the smallest correct owner:
136 
137| State | Preferred owner |
138| --- | --- |
139| Ephemeral visual state | local component state |
140| Uncommitted form state | the form or feature |
141| URL/shareable navigation state | the router/URL |
142| Remote server resource and cache | a query/cache layer |
143| Shared capability state | that feature's model/store |
144| Cross-capability process | a named workflow or app-level model |
145 
146- A store is not a bucket for every value used by several components.
147- Split state by capability and lifecycle, not by data type.
148- Expose narrow selectors, hooks, or commands. Do not expose a complete mutable store to all UI.
149- Store transitions should express user or domain intent, not generic object mutation.
150- Derive values instead of storing synchronized copies.
151- Do not use effects to keep two pieces of application state synchronized.
152- React Context is suitable for dependency injection or stable scoped state. Avoid one broad
153  app context whose every update rerenders unrelated consumers.
154 
155State-library choice is an implementation detail. Architecture should survive replacing it
156without rewriting pages and rendering components.
157 
158## Effects And Async Work
159 
160- Use effects to synchronize with external systems, not to calculate render data or handle user
161  events.
162- Start event-driven work from the event or model command that owns it.
163- Every subscription, timer, listener, or in-flight operation must have a clear owner and
164  cleanup path.
165- The owning feature/model defines pending, success, empty, error, retry, and cancellation
166  semantics.
167- Prevent stale async results and race conditions where users can trigger overlapping work.
168- Do not hide failures with broad `catch` blocks or silently convert errors into empty data.
169 
170## Data And Infrastructure
171 
172- Treat network responses, storage, URL input, files, and third-party SDK output as untrusted.
173- Validate and normalize data at the boundary where it enters the application.
174- Map transport DTOs and external errors into product-oriented values before they reach UI.
175- Keep raw `fetch`, storage APIs, SDK calls, and protocol details out of rendering components.
176- Keep a feature-specific API adapter inside the feature until it has a real shared consumer.
177- Introduce a client, repository, gateway, service, or facade only when its responsibility is
178  distinct and useful.
179- Avoid wrapper chains that only forward calls. One clear adapter is better than
180  `Client -> Service -> Facade` without separate responsibilities.
181- Inject infrastructure when tests, multiple implementations, lifecycle, or unstable external
182  APIs justify it. Do not introduce dependency injection for every pure helper.
183 
184## Component And Hook APIs
185 
186- Component and hook APIs describe product intent, not internal implementation.
187- Avoid boolean prop combinations that create unclear or invalid modes. Prefer explicit variants
188  or separate components.
189- Avoid passing raw query results, stores, SDK clients, or large configuration objects through
190  component trees.
191- Keep public props small and cohesive. A component that needs unrelated groups of props likely
192  owns too many responsibilities.
193- Custom hooks encapsulate React state, lifecycle, or reusable reactive behavior. Pure
194  calculations remain plain functions.
195- Do not use `useEffect`, `useMemo`, `useCallback`, or `memo` by habit. Use them for correctness
196  or measured performance needs.
197- Do not duplicate server or domain state into component state merely to make it editable.
198  Create an explicit draft only when the UX requires commit/cancel semantics.
199 
200## Public Boundaries
201 
202- Export the smallest useful public surface of a feature.
203- Consumers should use a feature's public components, hooks, commands, and types, not deep
204  internal paths.
205- Keep implementation-only state, DTOs, adapters, and helpers private.
206- Do not create barrel files everywhere. Use a public entry point only where a real boundary
207  exists.
208- A reusable abstraction should have a clear owner and at least one current reason to exist.
209- Avoid generic `core`, `common`, `helpers`, `services`, or `utils` modules that collect
210  unrelated responsibilities.
211 
212## Growing The Architecture
213 
214Start local and promote code only after pressure appears:
215 
216- A second consumer may justify shared domain code, but similar code is not automatically the
217  same knowledge.
218- Repeated external integration logic may justify a shared adapter.
219- A process coordinating several capabilities may justify a named workflow.
220- A large feature may split into smaller capabilities when they have distinct responsibilities
221  and lifecycles.
222- Separate packages are useful when an enforceable boundary, independent reuse, or independent
223  lifecycle outweighs their maintenance cost.
224 
225Do not begin a small application with every possible layer, package, provider, repository,
226facade, and design pattern. Strong architecture makes growth cheaper; it does not predict every
227future requirement.
228 
229## Testing
230 
231- Test product behavior and public contracts, not implementation trivia.
232- Test pure rules with unit tests.
233- Test feature models and async transitions without rendering where practical.
234- Test components through accessible user behavior.
235- Test infrastructure mapping and validation at external boundaries.
236- Keep end-to-end tests for critical user journeys.
237- Mock external systems and unstable boundaries, not every internal function.
238- Add tests proportional to risk, especially for validation, permissions, races, retries,
239  cancellation, and regressions.
240 
241## Review Checklist
242 
243Before finishing a change, ask:
244 
245- Does the file location make its owner obvious?
246- Does composition code read in product language?
247- Is UI protected from raw state, DTOs, infrastructure, and business decisions?
248- Is there one source of truth?
249- Are effects only synchronizing external systems?
250- Is new shared code genuinely domain-free or genuinely shared?
251- Does every abstraction remove current complexity?
252- Can important behavior be tested without rendering the whole app?
253- Did the change preserve accessibility, error handling, and cleanup?
254- Is this the least code that clearly solves the current problem?
255