Stop Cleaning Up Your Clickstream Data. Let Claude Ship It Clean.

Every product team has the same recurring nightmare. A PM opens Mixpanel to answer a simple question — how many users completed onboarding last week — and finds three events that could plausibly mean “completed onboarding”: Onboarding Complete, onboarding_finished, and Completed Setup. None of them is documented. Two of them stopped firing in March. The third has a step property that’s sometimes an integer and sometimes the string "done". The answer to a one-line question becomes a half-day archaeology dig.

Clean, consistent, well-documented clickstream data has been one of those longtime dreams — like data reliability — that everyone agrees on and almost no one achieves. The reason is structural: instrumentation is written by application engineers, in the same PR as the feature, under deadline, and the person who has to live with the mess (the analyst) isn’t in the room. Naming conventions live in a wiki nobody reads. The result is event taxonomies that drift a little with every release until the whole thing is untrustworthy.

In our last post, Data trust used to come after the fact. With Claude, it ships with your code., we argued that agentic coding finally makes it possible to embed data reliability into the development workflow rather than bolting it on afterward — through shared skills, guardrails, and a monitoring step enforced on every agentic code review. The same shift applies to the upstream piece of the analytics stack: the events application engineers emit. Agents like Claude are now writing the instrumentation. That’s exactly what makes it possible to govern it — automatically, at the moment the event is created, instead of cleaning it up six months later.

Here’s how our own team is doing it.

One prerequisite underpins everything below: a shared, version-controlled repo of skills and rules, centrally maintained and used by every engineer and agent — the foundation we described in step 2.1 in our previous post. Without it, the conventions, reviewers, and monitoring below are one-off configurations that drift apart between engineers if adopted at all; with it, they’re standards every developer inherits automatically. Everything that follows depends on it.

Make the source of truth machine-readable, agentically

Conventions only help an agent if the agent can see them. The first move is to make your event catalog semantically rich — every event and property described in plain language, with sample values, and stale definitions marked as such rather than left to rot alongside the live ones.

We did this in Mixpanel: project-level business context, every event and property annotated with a description and example values, and anything old hidden from the default view. You don’t have to write all that by hand — point a Claude-like agent at your warehouse data, application code, and existing docs, and have it draft descriptions, infer sample values from real usage, and resolve duplicate or conflicting events before they’re enshrined as the source of truth. The agent does the archaeology once, so analysts don’t repeat it on every query. The payoff: the Mixpanel MCP server performs dramatically better on vague prompts. Ask “how’s activation trending?” and instead of guessing across a soup of similarly named events, the agent can read that activation_completed is the canonical event, that it carries an account_type property with values trial or paid, and that Completed Setup was deprecated last quarter. The metadata is what lets the agent — and the analyst behind it — pick the right event the first time.

Put a conventions reviewer in the loop — at planning and at PR

The highest-leverage change is treating instrumentation the way the previous post treated monitoring: as a required reviewer in the agentic development flow, not a cleanup task.

We added an analytics-instrumentation sub-agent to two gates: plan-review and code-review. At planning time, when an engineer’s agent proposes adding tracking for a new feature, the reviewer checks the plan against our event conventions before a line of instrumentation is written — catching the cheap problems early. At code-review time, it checks the actual implementation.

Two conventions do most of the work:

Naming. Every event follows a consistent object_action shape in snake_case — report_created, dashboard_shared, alert_muted — with a controlled vocabulary of objects and actions. The reviewer rejects Created Report, ReportCreate, and new_report and proposes the canonical form. Properties follow the same discipline: report_id not reportID or report.

Near-dupe detection. This is the one that prevents slow taxonomy rot. Before approving a new event, the sub-agent queries the Mixpanel MCP for semantically similar existing events. A proposed subscription_started gets matched against the existing subscription_created, and the agent flags it: “This looks like a duplicate of subscription_created (fired 412K times in the last 30 days). Reuse it, or justify the distinction.” That single check is the difference between one well-understood event and three half-populated ones that each tell a partial story.

Concretely, the reviewer agent looks something like this — a skill you can drop into your repo alongside your security and testing reviewers:

---
name: enforce-event-instrumentation
description: >
  Reviewer agent. Ensures every new or changed analytics event follows
  our naming conventions, is fully documented, and is not a near-duplicate
  of an existing event. Runs at plan-review and on every code review.
---

# Enforce Event Instrumentation

## Steps
1. Identify analytics changes: events added, renamed, or given new properties.
2. Naming: enforce object_action snake_case using the approved object/action
   vocabulary. Reject and rewrite anything off-pattern.
3. Documentation: require a description and sample values for every new event
   and property. Block undocumented additions.
4. Near-dupe check: query the Mixpanel MCP for semantically similar events.
   If a strong match exists, require reuse or an explicit justification.
5. Gate: leave a blocking review comment for any unresolved naming,
   documentation, or duplication issue. Don't approve until it's clean
   or an owner waives it with a reason.

Because it runs as part of the standard review pass, the fix lands in the same PR that introduces the event — the moment when the engineer still has full context — rather than as a follow-up ticket that never gets prioritized.

Keep it honest after the event ships

A taxonomy that’s clean on release day drifts the same way a pipeline does. So the last piece is ongoing monitoring of new events — exactly what Monte Carlo monitoring does for clickstream. Freshness and volume checks flag an event that quietly stops firing after launch; schema and field-level checks catch properties with inconsistent types. It’s what catches the step property quietly flipping between 3 and "done" before an analyst builds a funnel on it. And because the monitors are monitors-as-code, every PR that adds or materially changes an event will ship with proper monitoring, enforced in the SDLC.

The compounding payoff

Put these together and clean clickstream stops being a yearly cleanup project. The catalog is machine-readable, so agents reach for the right event. A conventions reviewer runs at plan and PR time, so new events are well-named, documented, and de-duplicated before they merge. And ongoing monitoring keeps the taxonomy honest after attention moves on.

The instinct that good analysts develop over years — don’t create a fourth “signup” event, document what you emit, keep property types stable — becomes encoded, shared, and applied on every change, by humans and agents alike. That’s what it looks like when governance ships with the code instead of chasing it.