AGENTS.md · storybookjs/storybook

Sections

1. Always
2. Never Run
3. Read Before You Start
4. Code Review
5. Maintaining These Instructions

First lines (shown under the repo's MIT license)

# Storybook Agent Instructions

This file is the canonical instruction source for coding agents; other entrypoints point here.
Storybook is a TypeScript monorepo: code lives in `code/`, build tooling in `scripts/`, and every PR targets `next`.

## Always

- Run commands from the repository root unless stated otherwise.
- After editing, format with `cd code && yarn fmt:write`.
- Test React components with stories and `play` functions, never `*.test.tsx`.
- Log through `storybook/internal/node-logger` or `storybook/internal/client-logger`, not `console.*`.
- Use explicit extensions on relative TS imports (`./foo.ts`), except framework component files such as `.vue` and `.svelte`.
- Prefer `pathe` over `node:path`. It normalizes separators to `/`, so path code should not rewrite slashes itself.
- Do not commit incidental changes to generated files such as `code/core/src/manager/globals/exports.ts`.

## Never Run

- `yarn task dev` without an explicit sandbox template
- `yarn start`

Both start long-running dev servers.
`.github/workflows/claude.yml` `--disallowed-tools` mirrors this list; update both together.

## Read Before You Start

| Before you...                                                         | Read                                                                                                                      |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| install, compile, lint, run commands, or debug a build                | [Development workflow](.agents/guidelines/development.md)                                                                 |
| write or edit code                                                    | [Code authoring](.agents/guidelines/code-authoring.md) and [Comments and JSDoc](.agents/guidelines/comments-and-jsdoc.md) |
| write or run tests                                                    | [Testing](.agents/guidelines/testing.md)                                                                                  |
| open or update a PR                                                   | [Pull requests](.agents/guidelines/pull-requests.md)                                                                      |
| touch `code/core` internals, presets, open services, or the tools CLI | [Architecture](.agents/guidelines/architecture.md)                                                                        |
| do sandbox, E2E, or CI-parity work                                    | [NX and `yarn task`](.agents/guidelines/nx-and-yarn-task.md) and [Sandboxes](.agents/guidelines/sandboxes.md)             |
| call a Chromatic tool or debug a Chromatic build                      | [Chromatic projects](.agents/guidelines/chromatic-projects.md)                                                            |
| add or change an automigration                                        | [`code/lib/cli-storybook/src/automigrate/README.md`](code/lib/cli-storybook/src/automigrate/README.md)                    |

Contributor skills live in `.agents/skills/`.
Claude Code does not read `.agents/`, so each skill has a symlink in `.claude/skills/`; add one when you add a skill.

## Code Review

Before reviewing a pull request or a diff, read [`.agents/guidelines/code-review.md`](.agents/guidelines/code-review.md) and follow it.

## Maintaining These Instructions

- Keep this file to the always-on rules and pointers. Put detail in the linked document that owns the topic, and update that document when its topic changes.
- If a topic disappears, remove its document and its pointer together.
- Do not add a `CLAUDE.md`: Claude Code reads this file only when no `CLAUDE.md` exists. Keep other agent entrypoints as thin references to this file.
- Turn recurring corrections into enforceable checks with [principle-encode-lessons-in-structure](.agents/skills/principle-encode-lessons-in-structure/SKILL.md).