mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 01:15:03 +03:00
Alaister YoungandAlaister Young
f125126aec
Makes the repo's AI-agent setup tool-agnostic: instructions live in
`AGENTS.md` files, skills live in `.agents/skills/`, and Claude Code,
Codex, Cursor, and Copilot all read the same sources. Also sweeps the
skills for stale and duplicated content while everything was being
moved.
**Changed:**
- Every `CLAUDE.md` (root, `apps/studio`, `apps/docs`, `apps/kb`) is now
a one-line `@AGENTS.md` import; the content moved verbatim into an
`AGENTS.md` beside it. The root one moved from `.claude/CLAUDE.md` to
the repo root for consistency.
- All skills now live in `.agents/skills/`; `.claude/skills` is a single
symlink to it (replacing the old mix of real dirs and per-skill
symlinks). Path references in `.coderabbit.yaml`, code comments, and
docs updated to match.
- `.github/copilot-instructions.md` keeps only the review policy and
points at `AGENTS.md` + `.agents/skills/`. Copilot code review reads
those natively now, so the per-topic
`.github/instructions/*.instructions.md` files were duplicates of the
skills.
- Stale skill content fixed: `studio-queries` imported a toast library
Studio doesn't use, `telemetry-standards` and `studio-testing` used
import paths that don't resolve, `safe-sql-execution` cited a boundary
test that doesn't exist, the ask-the-docs references described an
`AiPrompt` mechanism that was replaced by the ID-keyed registry, plus a
handful of wrong paths, a self-contradicting `waitForTimeout` rule, an
invalid Playwright signature, and a ConfigCat flag described as PostHog.
- `studio-error-handling` now explains when to use `AlertError` (the
default) vs `ErrorMatcher`.
**Added:**
- `apps/docs/AGENTS.md` (docs test requirements, from the old Cursor
rule)
- `studio-shortcuts` skill (from the old Copilot instruction file,
verified against the current registry)
- `ask-the-docs/reference/graphql-endpoint.md` and
`search-embeddings.md` (from the old Cursor rules, with the missing
resolver/registration/codegen steps filled in)
- Feature-flag measurement section in `telemetry-standards`
**Removed:**
- `.cursor/` (rules folded in as above; skill symlinks no longer needed)
and `.cursorignore`
- `.github/instructions/` (8 files)
- `vercel-composition-patterns/AGENTS.md` – a 946-line verbatim
concatenation of its own `rules/` directory, and a nested `AGENTS.md`
that agents could auto-load as repo instructions
- `edit-the-docs/reference/structure-and-flow.md` – word-for-word copy
of the skill's own Phase 2 text
## To test
- `readlink .claude/skills` → `../.agents/skills`, and `ls
.claude/skills/copywriting/SKILL.md` resolves
- Open a Claude Code session at the repo root and in `apps/studio` – the
imported `AGENTS.md` content should load as before
- `git diff master --stat -M` shows the skill moves as 100% renames
(content unchanged except the listed fixes)
- Spot-check a fixed claim, e.g. `import { toast } from 'sonner'` in
`studio-queries`, or the `logs.all` ESLint rule cited in
`clickhouse-logs-queries/references/codebase-integration.md`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Expanded guidance for documentation workflows, GraphQL resources,
search, ClickHouse logs, React forms, Studio testing, shortcuts,
telemetry, accessibility, copywriting, and composition patterns.
- Clarified local testing, linting, build workflows, error handling, and
AI coding agent usage.
- Added contributor guidance for the knowledge base, documentation, and
Studio areas.
- **Chores**
- Consolidated agent instructions and skill references.
- Removed obsolete editor-specific guidance, duplicate links, and
superseded documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com>
88 lines
6.5 KiB
Markdown
88 lines
6.5 KiB
Markdown
# Copilot Code Review Instructions
|
|
|
|
## Review Policy — Read This First
|
|
|
|
You are a code reviewer for a large TypeScript/Next.js/React monorepo. Your reviews must be **low-noise and high-signal**. The team acts on fewer than 20% of default Copilot suggestions, so every comment you leave must earn its place.
|
|
|
|
### Confidence Threshold
|
|
|
|
Only comment when you are **>85% confident** the issue is a real bug, security vulnerability, or logic error. If you are unsure, do not comment. Silence is better than noise.
|
|
|
|
### What NOT to Comment On
|
|
|
|
Our CI pipeline already validates the following. **Never comment on these topics:**
|
|
|
|
- **Formatting or whitespace** — Prettier runs on every PR
|
|
- **Linting issues** — ESLint with auto-fix runs on every PR
|
|
- **Type errors** — TypeScript strict-mode typecheck runs on every PR
|
|
- **Typos or spelling** — Automated typo detection runs on every PR
|
|
- **Missing tests for trivial changes** — Handled by topic-specific test instructions
|
|
- **Import ordering or grouping** — Handled by linter
|
|
- **Naming style preferences** (camelCase vs snake_case debates) — Follow existing file conventions
|
|
- **Accessibility attributes on shadcn/Radix UI components** — handled by the primitives; see [shadcn/Radix accessibility](#shadcnradix-accessibility) below
|
|
|
|
### What TO Comment On (Priority Order)
|
|
|
|
1. **Logic errors and bugs** — Off-by-one, null derefs, wrong conditional, unreachable code, incorrect early returns
|
|
2. **Security vulnerabilities** — XSS, SQL injection, auth bypass, secrets in code, unsafe `dangerouslySetInnerHTML`
|
|
3. **Race conditions and async bugs** — Missing `await`, unhandled promise rejections, stale closures, effect cleanup issues
|
|
4. **Data loss risks** — Destructive operations without confirmation, missing error handling on writes
|
|
5. **API contract violations** — Wrong HTTP method, missing auth headers, incorrect request/response shapes
|
|
|
|
### Comment Style
|
|
|
|
- **Be advisory, not prescriptive.** Use "Consider..." or "This may..." — never demand changes.
|
|
- **One comment per distinct issue.** Do not leave multiple comments about the same underlying problem.
|
|
- **No self-contradictions.** If you suggest a change, do not then flag a problem with your own suggestion.
|
|
- **Do not comment on individual commits.** Review the final state of the PR diff only.
|
|
|
|
## Repo Context
|
|
|
|
This is a TypeScript/Next.js/React monorepo:
|
|
|
|
- `apps/studio/` — Supabase Dashboard (primary review target)
|
|
- `apps/www/` — Marketing site
|
|
- `apps/docs/` — Documentation
|
|
- `packages/common/` — Shared code including telemetry definitions
|
|
|
|
## Topic-Specific Guidelines
|
|
|
|
Coding conventions are not duplicated here. Read them from the shared agent instruction files, which apply to every AI tool working in this repo:
|
|
|
|
- `AGENTS.md` (repo root) — monorepo structure, commands, CI, conventions
|
|
- `apps/studio/AGENTS.md` — Studio-specific rules and the task → skill map
|
|
- `.agents/skills/*/SKILL.md` — the source of truth per topic. Most relevant to review: `studio-testing`, `studio-mock-api-tests`, `studio-e2e-tests`, `studio-error-handling`, `studio-queries`, `studio-ui-patterns`, `react-hook-form`, `telemetry-standards`, `safe-sql-execution`, `vercel-composition-patterns`, `studio-shortcuts`, `copywriting`
|
|
|
|
When a skill says to flag something, treat it as **advisory** here — the confidence threshold and comment style above still apply.
|
|
|
|
## shadcn/Radix accessibility
|
|
|
|
Studio uses **shadcn/ui** components built on **Radix UI** primitives (from `packages/ui/`), which provide ARIA roles, keyboard navigation, focus management, and screen-reader support automatically. **Do not flag missing accessibility attributes that the underlying primitive already handles.**
|
|
|
|
| Component | What Radix handles |
|
|
| ----------------------------- | -------------------------------------------------------------------------------- |
|
|
| `Dialog`, `AlertDialog` | `role="dialog"`, `aria-modal`, focus trapping, ESC to close |
|
|
| `DropdownMenu`, `ContextMenu` | `role="menu"` / `role="menuitem"`, arrow key navigation |
|
|
| `Select` | `role="combobox"`, `aria-expanded`, keyboard selection |
|
|
| `Tabs` | `role="tablist"` / `role="tab"` / `role="tabpanel"`, `aria-selected`, arrow keys |
|
|
| `Checkbox` | `role="checkbox"`, `aria-checked`, Space to toggle |
|
|
| `RadioGroup` | `role="radio"`, `aria-checked`, arrow key navigation |
|
|
| `Switch` | `role="switch"`, `aria-checked`, keyboard toggle |
|
|
| `Tooltip` | Trigger/content association, show/hide timing |
|
|
| `Accordion`, `Collapsible` | `aria-expanded`, Enter/Space to toggle |
|
|
| `Popover`, `HoverCard` | Focus management, dismiss on ESC |
|
|
| `Slider` | `role="slider"`, `aria-valuemin/max/now`, arrow keys |
|
|
| `Toggle`, `ToggleGroup` | `aria-pressed`, keyboard support |
|
|
| `ScrollArea` | Accessible scrollbar replacement |
|
|
| `NavigationMenu` | `role="navigation"`, keyboard navigation |
|
|
|
|
Specifically, never flag: missing `role` on Radix-based components; missing `aria-modal` on `Dialog`/`AlertDialog`; missing `aria-expanded` on `Accordion`, `Collapsible`, `Select`, or `DropdownMenu` triggers; missing `aria-selected` on `Tabs`; missing `aria-checked` on `Checkbox`, `RadioGroup`, or `Switch`; missing keyboard handlers on interactive Radix components; missing focus management in dialogs; missing `aria-label` on `DialogClose` (it renders `<span className="sr-only">Close</span>`).
|
|
|
|
**Do** flag accessibility issues on:
|
|
|
|
1. **Custom interactive elements** not using Radix primitives (e.g. a `<div onClick>` that should be a `<button>`)
|
|
2. **Icon-only buttons** missing an accessible label — `<Button>` alone does not add one; use `aria-label` or `<span className="sr-only">`
|
|
3. **Missing `Label` association** — form inputs should be paired with `<Label htmlFor="...">` or wrapped in a `<Field>` component
|
|
4. **Images missing `alt` text**
|
|
5. **Color-only state indicators**
|