AddThisFeature

Internal Notes

Give staff a place to write things the customer must never see.

moderate Collaboration

What it adds

Notes attached to a record that are readable only by internal roles, and that never appear in any export, feed, or API response.

What your agent is told to do

5
  1. 1

    Model an internal note as a distinct visibility state on the server, not a flag the client filters on. Every read path — record view, search, digest emails, exports, webhooks, API serializers — must exclude internal notes for anyone without the internal role.

  2. 2

    Give internal notes a visual treatment that cannot be confused with a public comment: different surface, a persistent label, and a warning that survives collapse or truncation. If a user has to remember which box is which, this feature has failed.

  3. 3

    Decide explicitly what an impersonating admin or a support session sees, and state the rule in the UI. Support staff reading internal notes is usually fine; a support session rendering them inside a screen the customer is watching is not.

  4. 4

    Audit every create, edit, and delete of an internal note with actor and timestamp, and keep the audit record when the note itself is deleted.

  5. 5

    Do not build a second commenting system. Threading, @-mentions, notification delivery and body sanitization are owned by Comments and Mentions; extend that rather than duplicating it.

Edge cases it handles

6
  • A record export, print view, or PDF must omit internal notes even when the exporter is internal — decide the rule once and apply it to every format.
  • Search must not match on internal note text for external users. A zero-result search that becomes a hit is a leak.
  • Changing a user's role must immediately change what they can read, including anything already cached or open in another tab.
  • An @-mention of an external collaborator inside an internal note must not deliver a notification containing the note body.
  • Deleting the parent record must not orphan internal notes into a state where they are still readable but no longer permission-checked.
  • Copying or duplicating a record must not carry internal notes across unless the actor is internal and explicitly asks.

Definition of done

8
  • Internal notes are filtered on the server; no client-side check is the only guard.
  • No export, API response, webhook, or email contains an internal note for an external recipient.
  • Internal notes are visually distinct from public comments at a glance, including on mobile.
  • Impersonation and support-access behaviour is defined and documented in the UI.
  • Every edit and delete is audited with actor and timestamp, and the audit survives deletion.
  • Threading and mentions reuse the existing comment system rather than a parallel one.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.