Files
coder/AGENTS.md
T
Danielle Maywood 5d048998b5 docs: correct FE1 and agent guidance on Storybook and Vitest roles (#29016)
Storybook in this repository is visual regression only. The storybook CI
job runs pixel-storybook, which loads each story, runs its play
function, waits for the DOM to settle, and screenshots it.

FE1 stated the opposite: it demanded interaction coverage in play
functions and called RTL interaction tests a violation, so agents kept
producing assertion-heavy play functions that duplicate what Pixel
already captures.

The corrected contract, in every document that restates it:

- **Visual regression is Pixel's job.** What the DOM renders, shows, or
hides is verified by the story's screenshot, not by an assertion. That
applies in both places: a `play` function must not assert at all (it
only drives state setup the screenshot needs), and a Vitest test must
not use `toBeVisible`/`toBeInTheDocument`/geometry as its outcome
assertion.
- **Vitest is the behavior check.** A test drives the real interaction
with `userEvent`, uses semantic queries to locate the element it
interacts with, and asserts the non-visual outcome: the callback
payload, the API request, the attribute value, the state change.

Files updated:

- `.claude/docs/FRONTEND_PATTERNS.md`: FE1 rewritten with both incorrect
examples (assertions in a play function, and visibility as a test's
outcome) plus a correct example asserting `onValueChange`'s payload.
- `site/AGENTS.md`: FE1 one-line summary and the Testing section.
- `AGENTS.md`: the frontend repository guardrail.
- `.claude/skills/frontend-review/SKILL.md`: the FE1 checklist now flags
visibility/presence outcome assertions in tests as a FAIL, alongside
assertions in play functions.

Follow-ups in this stack remove the assertion-only play functions and
duplicate stories that the old guidance produced.

Generated by Coder Agents on behalf of @DanielleMaywood.
2026-09-09 09:19:38 +01:00

6.7 KiB

Coder Development Guidelines

Make the smallest correct change, follow existing patterns, and verify the result. Ask only when the request is unclear, a meaningful design choice remains, or the action is destructive. If you want an exception to any rule in these documents, stop and get explicit permission first.

Prioritize correctness over agreement. State uncertainty instead of guessing, and push back on technically unsound requests with evidence.

Task-specific guidance

Load only the guidance relevant to the task:

Scope Guidance
Development servers, Git, hooks, and routine checks WORKFLOWS.md
API endpoints and Swagger WORKFLOWS.md
Go GO.md
Tests and concurrency TESTING.md
Database and SQLC DATABASE.md
OAuth2 and authorization OAUTH2.md
Architecture ARCHITECTURE.md
Troubleshooting TROUBLESHOOTING.md
Observability OBSERVABILITY.md
Isolation, ports, and cleanup DEV_ISOLATION.md
Failure reports AGENT_FAILURES.md
PR descriptions PR_STYLE_GUIDE.md
Existing docs prose docs style guide
Docs scope and routing content guidelines
Docs structure and research DOCS_STYLE_GUIDE.md
New, moved, or restructured docs write-docs skill
Frontend site/AGENTS.md

For changes under site/src/, also read FRONTEND_PATTERNS.md. For chatd work, read coderd/x/chatd/ARCHITECTURE.md. When the docs style guide and the content guidelines conflict, the content guidelines govern scope and routing.

Workflow

  • Inspect the working tree before editing. For an existing PR, check out its branch first.
  • Discuss architectural decisions such as framework changes, major refactoring, and system design before implementing them. Routine fixes and clear implementations do not need discussion.
  • When asked a question, answer the question instead of jumping to implementation.
  • Install and use the repository Git hooks. Never bypass them with --no-verify. Wait for slow first runs while caches warm.
  • Prefer targeted tests and checks while iterating. Run the broader checks required by the affected area before handoff.
  • Do not force-push unless explicitly requested.
  • Commit and PR titles use type(scope): message. A scope must be a real path containing every changed file. Use a broader scope or no scope for cross-cutting changes.

Essential commands

Task Command
Develop ./scripts/develop.sh
Build make build
Build slim make build-slim
Test make test
Test one make test RUN=TestName
Race test make test-race
Lint make lint
Generate make gen
Format make fmt
Pre-commit checks make pre-commit
Pre-push checks make pre-push

Docs use pnpm run format-docs and pnpm run lint-docs. Frontend commands live in site/AGENTS.md.

Repository guardrails

  • Database changes: edit coderd/database/queries/*.sql, run make gen, update enterprise/audit/table.go for audit errors, then run make gen again.
  • New resources: scope every new resource to an organization (organization_id column, organization-scoped RBAC and routes), never deployment-wide.
  • OAuth2: return RFC-compliant errors such as writeOAuth2Error(...). Public endpoints that need system access use dbauthz.AsSystemRestricted.
  • Chatd: when a change affects the documented architecture, do not edit the architecture document yourself. Leave TODO items in the affected sections; the human PR author writes the actual updates.
  • Public API: add the required Swagger annotations for new public HTTP endpoints.
  • Transactions: keep InTx work on the transaction handle. Prefer explicit database-to-SDK converters.
  • Concurrent tests: call t.Parallel(), use unique identifiers, and do not use time.Sleep to mask timing problems.
  • Frontend: reuse shared UI primitives. Cover visual states with Storybook stories; Pixel screenshots them in CI. Cover component behavior with Vitest, React Testing Library and userEvent tests that assert the non-visual outcome of the interaction (callback, request, state); extend existing coverage instead of adding a new test when equivalent coverage already exists.
  • GitHub Actions: set top-level permissions: {} and grant only required permissions per job.

Code and writing style

  • Follow the Uber Go Style Guide for Go code.
  • Use language-server navigation when available.
  • Name code for what it does, not its implementation or history. Wrap errors with context.
  • Document exported symbols with idiomatic Go doc comments or JSDoc.
  • Avoid unrelated edits. Preserve comments that explain non-obvious behavior.
  • Comments must be concise and substantive. Explain behavior, constraints, or rationale, not the history of the edit.
  • Do not use em dashes, en dashes, or spaced double hyphens as punctuation in code, comments, strings, or documentation.
  • Ensure files end with a newline.

Local configuration

Read AGENTS.local.md when present. It may be gitignored and is not imported automatically.