Scrum4Me Agent a7cc48a230 docs(PBI-49): add debug-id pattern doc + CLAUDE.md reference

Adds docs/patterns/debug-id.md documenting the named-component boundary
rule (6 punten), helper-voorbeeld, skip-criteria en motivatie voor
handmatige pad-argumenten. Voegt verwijzing toe aan CLAUDE.md
patterns-tabel.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-09 20:42:20 +02:00

2.3 KiB

Raw Blame History

title

status

audience

language

last_updated

when_to_read

Debug-id op component-root

active

ai-agent

contributor

2026-05-09

Wanneer je een named-component aanmaakt of aanpast.

Patroon: Debug-id op component-root

Regel: named-component boundary

Elk named-component plaatst data-debug-id en data-debug-label via de debugProps-helper op zijn root JSX-element. Zes concrete regels:

Import debugProps uit @/lib/debug — geen inline attribuut schrijven.
Spread het resultaat op het root element: {...debugProps(id, component, file)}.
id is kebab-case van de componentnaam, bijv. sprint-board.
component is de PascalCase naam zoals die geëxporteerd wordt, bijv. SprintBoard.
file is het relatieve pad vanaf de repo-root, bijv. components/sprint/sprint-board.tsx.
Root = het buitenste JSX-element dat de component rendert — niet een wrapper div die je extra toevoegt.

In productie (NODE_ENV=production) retourneert debugProps een leeg object {} zodat er geen debug-attributen in de gebundelde HTML staan.

Helper-voorbeeld

import { debugProps } from '@/lib/debug'

export function SprintBoard({ ... }: SprintBoardProps) {
  return (
    <div
      className="..."
      {...debugProps('sprint-board', 'SprintBoard', 'components/sprint/sprint-board.tsx')}
    >
      {/* inhoud */}
    </div>
  )
}

Skip-criteria

Voeg geen debugProps toe aan:

Categorie	Reden
`components/ui/*`	shadcn-primitives — ongebrand, niet onze componenten
Bridges / mounts	Niet-renderende wrappers zoals `notifications-bridge`, `realtime-bridge`, `sync-active-sprint-cookie`
Hooks-only files	Files die alleen hooks exporteren en niets renderen

Motivatie: geen build-time injectie van pad

Een alternatief is het bestandspad automatisch injecteren via een Babel/SWC-plugin of een ESLint-codefixin. Dit is bewust niet gekozen omdat:

de plugin afhankelijk wordt van de build-toolchain-configuratie (Next.js, Turbopack),
bij rename/move van een bestand de injectie verouderd raakt zonder dat de compiler waarschuwt,
expliciete argumenten in de broncode reviewbaar en grep-baar zijn.

Het handmatig meegeven van id, component en file maakt de intentie zichtbaar en voorkomt verborgen afhankelijkheden.

2.3 KiB Raw Blame History