supabase / supabase / 30065586109

74%

push

github

chore(claude): improve CLAUDE.md files and skill triggering (#48261)

Improves the repo's agent guidance: distills the always-required
`studio-best-practices` skill into `apps/studio/CLAUDE.md`, tunes every
skill description for reliable triggering, and mechanically enforces the
generated-files rule. Grounded in Anthropic's official CLAUDE.md
guidance (see justifications below).

## The main change: Studio CLAUDE.md gets a Code style section

**Why:** `studio-best-practices` was a skill that instructed agents to
*always* load it before any Studio code work. Anthropic's guidance draws
the line as: sometimes-relevant guidance → skill (loaded on demand);
always-relevant guidance → CLAUDE.md. A skill that must always load has
failed the test for being a skill — it costs a tool-call round trip and,
worse, silently does nothing in sessions that forget to load it. Since
`apps/studio/CLAUDE.md` is lazy-loaded only when an agent touches Studio
files, inlining is properly scoped: non-Studio sessions never pay for
it.

**Why not verbatim:** the skill was 175 lines, mostly ❌/✅ worked
examples teaching practices models already know. Inlining it whole would
push the file past the ~200-line point where Anthropic warns rules start
getting lost. Instead each section was distilled to the rule it exists
to enforce — e.g. the loading/error/success section kept its code block
because the *shape* (early returns at top level, flat `&&` chains
inline) is the prescription, and prose loses it.

**The framing that makes the generic rules earn their place:** models
default to matching surrounding code, and not all existing Studio code
follows these practices. The section opens with "older Studio code
predates some of these conventions — follow them rather than mirroring
nearby legacy patterns," which converts otherwise-redundant React advice
into an explicit instruction to break from local precedent. One rule was
added that the old skill lacked: `useEffect` is for external-syste... (continued)

1232 of 1702 branches covered (72.39%)

Branch coverage included in aggregate %.

1838 of 2437 relevant lines covered (75.42%)

235.76 hits per line