Tanish heeft zelfs een tool geschreven om deze direct vanuit de AST (Abstract Syntax Tree) te berekenen: https://x.com/tanishqk/status/2085800689129935342.

Diagrammen

Een klassieker. Als je chatinterface inline Mermaid ondersteunt, kunnen deze enorm helpen. Soms zijn ze nog steeds onhandig, maar meestal is het beter dan alleen tekst lezen. We hebben een voorkeur voor toestandsdiagrammen (state diagrams) en sequentiediagrammen.

Bestandsstructuren (File layouts)

Een ondiepe boomstructuur, waarbij elke entry één regel verantwoordelijkheid heeft. Handig voor de vraag "waar staat dit?" en voor het bepalen van de reikwijdte van een refactor.

src/
├── commands/           # parseert acties van gebruikers naar intents
│   ├── registry.ts     # naam -> handler, centrale plek om commando's toe te voegen
│   └── show-me.ts      # breidt het slash-commando uit
├── sessions/           # beheert sessie-status en lifecycle
│   ├── store.ts        # SessionStore - insert / list / open
│   ├── worker.ts       # AgentWorker.run - load context, call model
│   └── events.ts       # publiceert session.created en aanverwanten
├── transport/          # communiceert met de API, weet niets over sessies
│   ├── client.ts       # mapping van request / response
│   └── stream.ts       # SSE decoding, reconnect, backoff
└── config.ts           # env + feature flags

Pseudocode

Vooral voor algoritmische zaken kan pseudocode beknopter zijn:

capture()                                   // alleen als dit oppervlak focus heeft
  target = keyboard focus
  ? focusedBlock
  : firstBlockIntersectingViewportTop
  anchor = wholeBlockAnchor(blocks, target)  // type + tekst + naburige tekst
  offset = targetRect.top - scrollRect.top   // getekend: positie binnen een hoog blok
  publish({ anchor, offset, scrollTop, revision + 1 })

restore(snapshot)                           // na creatie editor + blocks
  placement = resolveAnchor(blocks, snapshot.anchor)
    exact text match
    -> normalized-whitespace match, gescoord op naburige context
    -> 'outdated'
  if resolved
    scrollTop += targetRect.top - scrollRect.top - snapshot.offset
  else
    scrollTop = snapshot.scrollTop           // failure path

Types en signatures

De vorm van de code voordat deze daadwerkelijk bestaat — details die te intern zijn voor een architectuurdocument, maar die een agent nog steeds fout kan begrijpen.

interface Item {
  id: ItemId
  parentId: ItemId | null
  // ...
}

interface Cursor {
  position: ItemId
  direction: 'up' | 'down'
  // ...
}

resolveTarget(items: Item[], cursor: Cursor) -> ItemId | null

Diff-syntaxis

Je kunt ook diff-syntaxis gebruiken als het grootste deel van de inhoud ongewijzigd blijft.

Voor een componentwijziging:

<SessionPage>
  useSessionEvents()
  <SessionToolbar>
+    <RunSkillButton />
  <SessionTimeline>
+    <SkillResultCard />

Voor een wijziging in de call-tree:

handleCreateSession
  validateRequest
+   enforceQuota
  SessionStore.insert
  publish(session.created)
  AgentWorker.run
    loadContext
+     fetchPriorTurns
    callModel
    persistResult
+     emitUsageEvent

Voor een wijziging in de bestandsstructuur:

src/
├── commands/
+│   └── show-me.ts       # breidt het slash-commando uit
├── sessions/
-└── transport.ts
+└── transport/
+    ├── client.ts
+    └── stream.ts

Voor een wijziging in status of control-flow (pseudocode):

on(save)
-  write content
+  if content is unchanged
+    return cached result
+  write new content
+  invalidate cache

HTML Mockups & Diagrammen

HTML heeft voor veel van ons prototypewerk de plek van Figma ingenomen. Soms heb je simpelweg een diagram of uitleg nodig; in HumanLayer laten we de agent direct HTML opnemen in de antwoorden, maar je kunt dit ook gewoon in je browser openen.

Andere inspiratie

Ik wil ook Matt Pocock noemen voor de HTML-uitleggen die worden gegenereerd door zijn /teach skill — zeer goed uitgevoerd.

Probeer het uit

Installeer de skill via: npx skills add humanlayer/skills --skill show-me

Na installatie kun je /show-me aanroepen of de agent vragen de show-me skill te gebruiken. Richt het op een route, service, feature, pull request of het huidige onderwerp. Je kunt het ook gebruiken om het model een vraag of bewering opnieuw te laten formuleren.

Voorbeelden:

• "Dit is teveel content. show me."
• "/show-me as an html explainer"