Guides

The rule set is eight Markdown files in .claude/guides/, 1,813 lines in total, plus the 749-line .claude/CLAUDE.md that links them and holds the doctrine they elaborate.

They are written for an AI agent working in the repository, so Claude Code produces changes that match the conventions already in place.

But they are ordinary prose, and reading them yourself is the fastest way to learn how the codebase expects to be extended.

The guides state judgement, not syntax. The 25 scripts/check-*.ts harness checks catch a forgotten convention; the guides catch the more expensive mistake of building the wrong thing correctly.

How they hang together

.claude/CLAUDE.md opens with a link row to all eight guides, then four routing instructions that decide which one you read:

• Read ../GUARANTEES.md before changing money, refunds, stock, identity, soft-delete visibility, cache invalidation, events/activity or auth. A convenience rule in .claude/guides/ never overrides a system promise.
• Composing a feature → Platform Primitives first.
• Building anything non-trivial → run the Design Review checklist.
• Any net-new page, component, model, module, or any refactor → Before You Build.

The rest of CLAUDE.md is the doctrine the guides expand: Guarantees over tolerance. Deletion over accumulation. Composition over extraction.

It also holds:

• The table column standards
• The admin tone system
• The "Compute, Don't Cache" rule, including why a lifecycle status enum counts as a cache
• "Trace to the Sink" on phantom data flow
• The canonical-cascade rule
• The six-step method for approaching a task

The eight guides

The eight files, with their sizes:

design-review.md         56
before-building.md       95
platform-primitives.md   48
new-entity.md           109
code-style.md           269
data-api.md             273
ui-components.md        426
project-specific.md     537

The three shortest are the ones you read before writing anything. The three longest are references you return to while writing.

design-review.md

56 lines. Read it before building anything non-trivial.

Five questions to answer before writing code:

• Should this exist at all?
• Does a primitive already own it?
• Does it fight the system it lives in?
• Is the scope the minimum that satisfies the ask?
• Does it cross a line that needs a human?

It ends with five smell tests:

• Overriding most of a component's default classes
• Adding a column for something you could compute
• Building a card nobody asked for
• Minting a primitive without grepping
• Duplicating a sibling

Two minutes, before the build.

before-building.md

95 lines. Read it before a net-new page, model or module — or any refactor.

Three hard rules:

• Clone the nearest sibling — and if you cannot name that file, stop and ask
• Treat the request as a ceiling rather than a floor
• Add nothing that has no consumer today

It then gives a clone target for each of the four kinds of net-new work — surface, model, module, refactor.

The surface table names the exact file to copy, along with the primitives each one requires, for:

• An admin list page
• An admin detail page
• A settings card
• A form or dialog
• A web dashboard page
• A storefront page

The model section lists the real traps:

• Adding an enum
• Caching a derived value
• A speculative field with no reader
• A Json DSL column driving behaviour

platform-primitives.md

48 lines, and the shortest guide. Read it before composing a feature out of existing machinery.

It is a single table of the platform's canonical idioms, one row per concept:

• Lifecycle derived from decision timestamps (deriveTimestampStatus)
• Time-windowed liveness computed on read
• One canonical *_WHERE predicate, so a count and its list page cannot disagree
• Publish gates
• Transition legality
• Definition registries keyed by a real union with satisfies
• BaseCRUD for persistence
• Polymorphic ownerType/ownerId references
• The single Translation table
• emitOperatorAlert as the one alert fan-out
• The lib/import/ runtime
• resolveStorefrontPage() for composition
• Task definitions
• Severity projection
• SeoSubject

Each row names its exemplar file and what enforces it.

Writing a bespoke alternative to any row requires naming which of four failures the primitive hit:

• Missing capability
• Cannot express the rule
• Too much boilerplate
• You did not know it existed

new-entity.md

109 lines. Read it when adding an admin entity end to end.

It is the ordered registration checklist for a new admin entity, fifteen numbered steps:

1. The Prisma model
2. Permissions
3. Role grants
4. The server module
5. Activity logging
6. The soft-delete path
7. Cache tags
8. Sidebar nav
9. Section tabs
10. App pages
11. Components
12. The picker registry
13. Row indicators
14. Seed data
15. Dashboard widgets

Every step is tagged MECHANICAL, JUDGMENT, SILENT TRAP or ENFORCED, so you can see which omissions produce a build failure and which produce nothing at all.

Coupons is the template entity.

It also names the footguns. For multi-word modules the AdminModule key differs from its value (socialMedia: "social_media"), and permission literals use the value form.

code-style.md

269 lines. Read it when writing any TypeScript here.

What it covers:

• Function declarations for pure functions, arrow functions for server actions
• The find/get/fetch/create/is/to verb standard
• Platform-agnostic naming
• Co-located types
• Const objects instead of TypeScript enums
• The ~/ path alias
• cx from ~/utils/cva
• Structured error returns instead of thrown strings
• Schema-level validation with UI-level display
• The no-backwards-compatibility rule, which forbids type aliases, function aliases and re-exports when renaming

See Code style for the version of this checked by scripts.

data-api.md

273 lines. Read it when touching CRUD, queries, server actions or money.

The data layer:

• BaseCRUD mutation factories (createAction, updateAction, deleteAction, duplicateAction), with hand-written query actions around the module's read API
• Activation prerequisites through lib/activation-rules.ts
• API route error handling
• Money formatting through fromCents, because a raw object literal fails on Prisma Decimal
• The two server-action error patterns, and how to consume the [data, error] tuple

It also carries a Prisma field-awareness section listing the model-name mappings that trip people up:

db.shipping   not ShippingZone
db.coupon     not Discount
db.collab     not Affiliate

And it gives the four questions to answer before changing prisma/schema.prisma, starting with which promise in GUARANTEES.md the change enforces.

ui-components.md

426 lines. Read it when building or changing UI.

This is the guide that answers "which existing component do I reach for" before you write a new one.

What it covers:

• Sprite icons through <Icon />
• The styling token rules
• The semantic layout components, and when className is legitimate
• Stack usage, with a full props reference
• The empty-state rules — EmptyList for an inline list or grid, AdminEmptyState with presets for admin tables — and why an empty state must be updated when the UI it describes changes
• Layout and two-column boundary rules
• A variant reference for Badge and Button
• The component name casing convention

project-specific.md

537 lines. The longest guide, and the one that only applies to Litestore's admin.

• AdminCardHeader action patterns
• Inline editing with EditableField for simple fields, and a header action for complex content
• adminTokens type safety
• The TrackedLink component, and the ref-parameter naming convention that makes storefront link analytics comparable
• The AdminEntityTable wrapper
• The four useAdminMutation hooks (useAdminMutation, useFieldUpdate, useBulkMutation, useCreateMutation)
• Server-action file organisation, and when to split one
• Inline table-cell editing

Which guide to read

If you are about to build anything non-trivial, start with design-review.md.

If the thing is net-new — a page, a component, a model, a module — or if it is a refactor, read before-building.md and find the sibling you are cloning.

If you are composing a feature out of machinery that already exists, read platform-primitives.md first, and be ready to name which of the four failures the primitive hit if you write your own.

If the thing is an admin entity, work through new-entity.md in order.

While writing, the reference you need depends on the layer: code-style.md for TypeScript, data-api.md for CRUD, queries, server actions and money, ui-components.md for UI, and project-specific.md for the admin.

And before any change to money, refunds, stock, identity, soft-delete visibility, cache invalidation, events, activity or auth, ../GUARANTEES.md comes first:

A convenience rule in .claude/guides/ never overrides a system promise.

Related