Storybook Agent Rules

Workshop for building, documenting and testing UI components in isolation.

Overview

Storybook covers repository structure, architecture, commands, pull requests, and tests. Two sections govern the guide itself: one requires updates when the project changes, and another records maintainer preferences learned during earlier work.

Documents

├── 
├──  · imports AGENTS.md
├── .agents
│   ├── guidelines
│   │   └── 
│   └── skills
│       ├── canary
│       │   └── 
│       └── principle-encode-lessons-in-structure
│           └── 
├── code
│   └── core
│       └── src
│           ├── cli
│           │   └── tools
│           │       ├── 
│           │       └── 
│           └── shared
│               └── open-service
│                   └── 
└── CONTRIBUTING
    └──

Patterns in this file

Behavioral framing Pointing at the source of truth Hard prohibitions Verification by change type Nested instruction files

A section of accumulated corrections

Learned User Preferences records maintainer corrections about worktrees, premature helpers, readable interaction tests, story-description placement, and stable telemetry strings.

417- Keep e2e and long interaction tests as a readable continuous flow; do not force DRY with loops or heavy helpers when repetition is clearer.

02 / Pointing at the source of truth

The file names itself as canonical

Other agent entrypoints reference this file instead of copying it. A maintenance section also requires updates when architecture, commands, versions, or release flows change.

5This file is the canonical instruction source for coding agents. Files like `CLAUDE.md` should point here instead of duplicating instructions.

03 / Behavioral framing

Principles labelled as observed failure modes

Code Authoring Principles records failures seen in agent changes. It calls for throwaway probes before encoding environment assumptions, prefers static checks, and avoids testing guarantees enforced elsewhere.

389These are recurring failure modes in agent-authored changes to this repo. Apply them when writing or reviewing code, not just when asked.

An inverted default for component tests

For React components the file directs behavior, accessibility and interaction assertions into stories with play functions, and reserves unit test files for pure utilities, hooks and non-React modules.

05 / Hard prohibitions

A ban on direct global assignment in tests

Direct global assignment is forbidden because Vitest does not restore it, causing order-dependent leaks across test files. The guide names the replacement API and cleanup call.

321> Under no circumstances may a test mutate a global by assigning it directly (e.g. `globalThis.FEATURES = {...}`, `globalThis.window = ...`, `global.fetch = ...`). Direct assignment leaks across tests and files — Vitest does not restore it — so it silently changes behavior in unrelated tests and creates order-dependent flakiness.

Commands the agent should not run

Two commands are listed under a Commands To Avoid heading, with the reason that they start long-running development servers, which the file describes as the wrong default for an agent.

Ideas for your repo

Keep a section for corrections that came up in review. It is the cheapest way to stop repeating the same feedback.
Name the commands that start long-running processes and tell the agent not to run them.
When framework behavior motivates a test rule, name it. "Vitest does not restore it" makes the rule memorable.
If your repo has several agent entrypoints, name one canonical file and make the rest point at it.