docs

AI Development

The Storefront Application V3 ships instruction files and skills that an AI coding agent reads. The architectural rules a reviewer would otherwise repeat by hand live in the repository where an agent reads them, and the recurring tasks that shape a storefront ship as skills an agent runs on request. Claude Code reads the instruction files and offers the skills when your request matches one, so an agent knows the layer boundaries, the naming conventions, and the quality workflow before you write your first prompt. The files are plain markdown, and the application runs the same without them.

Why the project ships agent context

A committed instruction file fixes an agent's repeat mistakes for everyone at once, such as a service inside a controller or an import across the client and server boundary.

These files are plain markdown and guide an agent without enforcing anything. ESLint, the type checker, and the test suite still do the enforcing, and you review an agent's diff the way you review a colleague's: read it, run pnpm typecheck and the tests, and open the affected page in a browser before you commit. Storefront DevTools show what that page fetched and rendered. Keep .env and API keys out of prompts.

Instruction files

The project ships a CLAUDE.md file at its root, one in each layer, and one for the end-to-end tests.

FileFocus
CLAUDE.mdProject-wide: the stack, the SDK packages, observability, architecture boundaries, data fetching and batch operations, testing, the quality workflow, i18n, and conventions.
src/server/CLAUDE.mdThe server layer: controllers, Inertia shared data, page prop rules, dependency injection, where services and mappers belong, routing, the oRPC API, and server testing.
src/shared/CLAUDE.mdThe contract between server and client: how shared types are designed, the one-import-path rule, how type augmentations are registered, and custom data types.
src/client/CLAUDE.mdThe client layer: the design system, typography, components, pages and layouts, composables, plugins and directives, the CMS integration, navigation, accessibility, SVG icons, and SSR guards.
testing/playwright/CLAUDE.mdThe end-to-end test suite: commands, layout, test data from the Storefront API, page objects and fixtures, navigation and URLs, authentication, and CI.

Claude Code loads these by walking up the directory tree from wherever a session starts, concatenating every CLAUDE.md it finds along the way rather than picking just one. A session started at the project root loads the root file. A session started inside src/server/ loads the root file and src/server/CLAUDE.md together, with the more specific file read last. A CLAUDE.md in a directory below the start directory loads when Claude reads a file there. That is why each layer carries its own file instead of repeating their rules in the root one.

The guides in docs/ hold deeper material, such as the glossary, testing, logging and tracing, styling, the tracking pipelines, and the Amplience content model. Point an agent to a guide when a task needs that level of detail.

Skills

.claude/skills/ holds SKILL.md files an agent invokes for a specific task rather than reading as general project context. Claude Code keeps each skill's description in context and loads the skill itself when your request matches that description. You can also name a skill directly in a prompt. The tables below list every skill folder.

Stack skills

One skill for each of the main libraries and tools of the stack, each covering the surface this project actually uses rather than the library's full feature set. The hono, inertia, and orpc skills state the library version they cover. They sit one level below the CLAUDE.md files: the skill covers the library's own API, the instruction file covers this project's rules for applying it.

SkillCovers
honoHTTP routing, the typed context, middleware, error handling, and Node.js deployment.
inertiaPage props, ctx.render(), the deferred, once, and server-only prop modifiers, and the client and SSR entry points.
orpcThe procedure builders, error code conventions, the client-side safe call pattern, and testing both sides of a mutation.
vitevite.config.ts, the build setup, and SSR configuration.
vitestThe parallel test projects, virtual module aliasing, and test environment variables.
pnpmDay-to-day package manager commands, and the rule that pnpm and pnpm exec are the only ones used.

Project convention skills

SkillCovers
translate-localesPropagates added, changed, and removed keys from src/i18n/locales/en_GB.json to every other locale file.
vue-best-practicesComposition API, <script setup>, and TypeScript conventions for components.
vue-testing-best-practicesThe testing setup and the component test patterns this project uses.
storybook-vue-storiesStory file structure, naming and variants, args and argTypes, render and play functions, and the existing Storybook mocks.
tracingMeasuring server-side latency with OpenTelemetry traces in a local Jaeger, before you propose a performance fix.

After you edit en_GB.json, translate-locales dispatches one translation subagent per locale, each briefed with the e-commerce context it needs to choose the right word for "basket" or "voucher" in that language. Each subagent writes its own locale file, and the skill then checks that every locale has the same keys. See Translate a new key in all locales.

Web quality skills

SkillCovers
web-quality-auditA full review across performance, accessibility, SEO, and best practices.
accessibilityWCAG 2.2 auditing, screen reader support, and keyboard navigation.
core-web-vitalsLargest Contentful Paint, Interaction to Next Paint, and Cumulative Layout Shift.
performanceLoading speed, runtime efficiency, and resource optimization.
seoMeta tags, structured data, sitemaps, and technical SEO.
best-practicesSecurity, browser compatibility, and code quality.

Adding your own

Both layers are yours to extend once you fork the project.

Add a CLAUDE.md to any directory whose rules do not belong in the root file. A team that owns one feature area can keep its conventions next to the code, and only sessions working in that directory pick them up.

Add a skill by creating .claude/skills/<name>/SKILL.md with a name and a description in its frontmatter. The description is what an agent matches your request against, so write it as the trigger: name the task, and name the phrases someone would use to ask for it. Longer reference material goes in a references/ directory next to the SKILL.md, which the agent reads only when it needs it. See Claude Code's Skills documentation for the full format.

A good rule for deciding where something goes: anything you find yourself repeating in prompts is a missing line in a CLAUDE.md, and anything you repeat as a multi-step procedure is a missing skill.

Using another assistant

The instruction files and skills in the project are written for Claude Code. Other assistants read other files. Many read a project-wide AGENTS.md, an open format for plain markdown instructions. Check which files your team's assistant reads in its documentation, for example the Cursor rules, the Cursor skills, the OpenCode instructions, and the OpenCode skills. Claude Code's memory documentation shows how to share one instruction file with other tools. Their behavior changes often, so follow their documentation for the details.