CRM Data Cleanup on a Schedule: A Claude Agent That Proposes, You Approve

Write the rulebook before you touch a record

The agent is only as good as the definitions you give it, so start with the arguments RevOps has been having in Slack for years and settle them in a file. What makes two companies the same: same domain, or same domain plus a name similarity above a threshold, and what about subsidiaries with a shared parent domain? What are the canonical values for job level, industry, country, and state? Which fields are required on a contact before it can be routed, and which are nice to have? When is an open deal dead: no activity in 90 days, or 120, and does the rule change by stage?

Write it as a spec the agent reads at the start of every run, and keep it in version control next to the brief. The rulebook below is the one I start from; the canonical lists are the part every team rewrites, because your industry taxonomy and your seniority ladder are yours.

Decide the confidence tiers now. A merge candidate with the same domain and a 0.95 name match is a different proposal than one with a similar name and no domain. The list should show the score and the evidence for every line, so the reviewer can approve the obvious ones in a second and spend their attention on the ones that deserve it.

Connect the CRM over MCP and run the audit read-only

Connect HubSpot or Salesforce to Claude Code through its MCP connector, using an account whose permissions match the job. For the first several runs, only allow the read tools. The agent should be able to search and fetch contacts, companies, deals, and owners, and it should not yet be able to create, update, merge, or delete anything.

Run the audit once by hand and read the counts. How many companies share a domain? How many distinct values does the industry field hold, and how many of them are spelling variants? How many records point at deactivated owners? How many open deals have had no activity in 90 days? Those numbers are the baseline you will show the CRO in a quarter, and they are usually worse than anyone guessed.

Name your custom properties and pipeline stages explicitly in the brief. An agent that assumes the standard HubSpot fields will miss the 'Account Tier' property your routing depends on, and will treat your custom 'Legal Review' stage as unknown. Ten minutes listing the fields saves a run's worth of wrong proposals.

• Reads: companies (name, domain, industry, size, country, state, owner, created, last modified)
• Reads: contacts (name, email, title, company association, owner, lifecycle stage, last activity)
• Reads: deals (name, stage, amount, close date, owner, last activity, stage history)
• Reads: owners and their active status
• Never writes, in the audit phase: anything

Write the brief so every proposal carries its evidence

The brief turns the rulebook into a run. Read everything, apply the rules, sort candidates into the five buckets, and for each candidate write one line: what changes, on which record, from what to what, why, and how confident. The 'why' is the two records side by side for a merge, the raw value and the canonical value for a normalization, the enrichment source for a fill, the last-activity date for a dead deal. A proposal without evidence is an opinion, and opinions are what the spreadsheet purge already had.

Tell it what to leave alone. Records modified in the last 48 hours are in use; skip them. Deals with an amount above a threshold get flagged, never auto-proposed as dead. Anything the subsidiary rule catches goes to a 'needs a human' section instead of the merge list. The brief should make the agent conservative by default, because a conservative proposal list is one the reviewer can trust enough to approve quickly.

Fix the output as a checklist. Every line starts with an unticked box. The executor, later, treats an unticked line as a no-op. That single convention is the safety model for the whole play: the agent can propose a thousand changes and write zero of them until a person ticks.

Every Sunday at 9:00pm {{TIMEZONE}}, run the CRM hygiene audit against {{CRM}} using the rulebook in rules/crm-hygiene.md.

Read all companies, contacts, deals, and owners via the {{CRM}} connector. Skip any record modified in the last 48 hours.

Find candidates in five buckets:
1. DUPLICATES: companies sharing a domain, or name similarity >= {{NAME_MATCH}} with matching country; contacts sharing an email, or same name at the same company. Never propose a merge across different company names on a shared parent domain; put those under NEEDS A HUMAN.
2. NON-STANDARD VALUES: any industry, job level, country, or state value not in the canonical lists. Map to the canonical value; if no confident mapping exists, list it under NEEDS A HUMAN.
3. GAPS: contacts missing title or company; companies missing industry, size, or country. Fill from {{ENRICHMENT_SOURCE}} up to a budget of {{CREDIT_BUDGET}} credits per run, highest-value accounts first (open deals, then customers, then ICP tier).
4. ORPHANS: records with no owner or an inactive owner. Propose the owner from the territory rules; if none applies, propose the round-robin default.
5. DEAD DEALS: open deals with no logged activity in > {{DEAD_DAYS}} days. Propose closed-lost with reason 'No activity'. Deals above {{FLAG_AMOUNT}} are flagged, never proposed.

Write proposals/{{DATE}}.md as a checklist. One line per change:
- [ ] <bucket> | <record id> | <field> | <before> -> <after> | evidence: <the two records, the source, or the last-activity date> | confidence: <0-1>

Rules:
- Read only. Do not create, update, merge, or delete anything in the CRM.
- Every line must cite evidence a reviewer can check in one click.
- Sort each bucket by confidence, highest first. Put anything below {{MIN_CONFIDENCE}} under NEEDS A HUMAN.
- End with the counts per bucket and the change vs last week's audit.
- Post the counts and a link to the file in #{{REVOPS_CHANNEL}}.

Fill the gaps within a budget, not to completion

Enrichment is where hygiene projects quietly burn money. Run the gap-fill through FullEnrich or Clay with a hard per-run credit budget and an ordering rule: accounts with open deals first, then current customers, then anything in your ICP tier, then everyone else. A contact from a 2023 webinar with no title is a gap; it is also not worth a credit this week, and maybe not ever.

Treat enrichment results as proposals too. The source says the company has 620 employees and the CRM says 40; that is a line in the list with both values, not a silent overwrite. Enrichment vendors are usually right and occasionally spectacularly wrong, and the record you most want to protect is the one where a human typed the real number after a call.

Log the credits spent and the fill rate each run. If a third of the credits go to records nobody ever touches again, the ordering rule needs tightening, and that is a one-line edit in the brief.

Review, tick, and let a separate executor write

The proposal list lands in Slack Monday morning as a file link and the bucket counts. The owner opens it and reads the way a good editor reads: approve the high-confidence normalizations in bulk, scan the merges with the two records side by side, and spend real attention on 'needs a human'. Ticking a line is the approval. A first review of a neglected database takes an hour; by week four it is fifteen minutes, because the backlog is gone and the run only finds the week's decay.

The executor is a second, smaller job with write permissions, and it does one thing: read the ticked lines and apply them, one at a time, logging the record, the field, the before, the after, and the timestamp. It never reads the rulebook, never infers, never writes an unticked line. Separating the proposer from the executor is what lets you give write access to the CRM without giving it to the agent that has opinions.

Post the change log back to the channel. 'Merged 14 companies, normalized 212 industries, filled 61 titles, reassigned 38 orphans, closed 27 dead deals' is a sentence the sales leader reads and trusts, and the log underneath is the audit trail when someone asks in March why a record changed in January.

• Proposer: read-only CRM tools + Write for the proposal file
• Reviewer: a human, ticking boxes in the file or a Slack thread
• Executor: CRM write tools, reads only the ticked lines, logs every change
• Rollback: the change log is the undo list; keep it

Schedule it and watch the counts fall

Run the proposer Sunday night as a scheduled Claude Code job so the list is waiting Monday, and run the executor whenever the review is done, by hand at first, then on a trigger once you trust the pattern. Keep the rulebook, the brief, and the proposal files in a repo; the history of what was proposed and what was approved is the most honest record of your data quality you will ever have.

Track five numbers weekly: duplicate candidates, non-standard values, gap count, orphans, dead deals. Week one is the backlog and the number is embarrassing. By week six the run should find only the week's decay, a few dozen lines, and the review takes a coffee. That trend line is the report for the CRO, and it makes the case for the next play, because routing, scoring, and forecasting all get better on clean data.

Revisit the rulebook quarterly. New canonical values appear when the company enters a new market; a new pipeline stage changes the dead-deal rule; a reorg changes the territory rules. The agent applies the rules exactly, which means the rules have to be right, and the quarterly read is where you keep them right.