For AgenciesHow It Works

Documenting your Claude setup so the client can maintain it

In brief

Client handoff is where most consultants lose the long-term value of what they built. The five things to write down, the format that works, and what to test before you leave.

7 min read·

Contents

♡Sign in to save

You set up Claude Projects, wrote the system prompts, configured the connectors, built the workflows. The client paid for the work. Six months later they email you: "Hey, Claude isn't doing the thing you set up. Can you take a look?"

What they actually need is not for you to take a look. They need to be able to maintain what you built. If your handoff didn't include the documentation to do that, the setup will degrade until they turn it off — and the next consultant gets the work.

This is distinct from delivering the client's deliverable (covered in client-handoff-with-claude). This is about the system you built inside Claude becoming maintainable by someone who didn't build it.

The five things to document (and the order)

Write these in this order, because each one depends on the previous one being clear.

1. The inventory

List every Claude artifact you created for the client, with the name, owner (which Claude user created it), and a one-line purpose.

Minimum inventory:

Projects — name, purpose, who should have access, what the shared system prompt does
System prompts — where used (Project? individual prompts? API?), full text saved to a document the client owns
Connectors — which connectors are enabled, what data sources they point to, which Projects use them
Skills — which Skills are enabled at the workspace or Project level
Claude Code setup (if any) — repos with .claude/ folders, what hooks are configured, what's in CLAUDE.md
Hook scripts (if any) — where they live, what they do, what breaks if they stop running

One person on the client's side should be named as the owner of each item. Without an owner, nothing gets maintained.

2. The "why" for each piece

For every artifact in the inventory, write one or two sentences about why it exists. Not what it does — the client can read the system prompt to see what it does. Why you chose this approach over alternatives.

Example:

Project: Customer Support Drafts
Why: We chose a single shared Project instead of individual user prompts because support responses need consistent tone across the team. If one rep writes more formally than another, customers notice. The shared system prompt enforces the tone; individual reps add case-specific context in each chat.

The "why" is what lets the client's next consultant (or the client themselves) decide whether to keep your approach when requirements change.

3. The maintenance schedule

Tell them when things need attention. This is the part most consultants skip.

Minimum maintenance schedule:

Artifact	Check every	What to look for
Project system prompts	Quarterly	Has the team's process changed? Are there examples in the prompt that are now stale?
Connectors	Monthly	Are the data sources still current? Did anyone rotate credentials?
Skills	Quarterly	Did Anthropic update the Skill? Does a new one replace it?
Claude Code hooks	When any script it depends on changes	Does the hook still exit 0 on normal conditions?
Usage + cost	Monthly	Are the numbers in the ballpark you set up? Any user spiking unexpectedly?

This document gets added to the client's existing recurring-task list (calendar, Asana, whatever). If it only lives in your handoff PDF, no one will remember to do it.

4. The failure modes

For each artifact, what's the single most likely way it breaks in the first 6 months, and what's the first step to debug?

Example:

System prompt for Customer Support Drafts
Likely failure: the team's tone guidelines change (e.g., "be more concise" becomes new guidance from leadership). The system prompt still reflects the old guidance, so drafts sound off.
First step: open the Project, read the system prompt, compare to current tone guidelines. Update the prompt directly — no other files need to change.

You're not writing a full runbook. You're writing the "start here when it breaks" pointer. The single most common failure and the first thing to check.

5. The escalation path

When something is beyond the client's ability to maintain, where do they go? Three tiers:

Tier 1 (self-service): the maintenance schedule above
Tier 2 (the client's internal team): who in the client's org can make edits? Name them. Give them edit access to the Projects.
Tier 3 (you or a replacement consultant): what's your retainer rate for this? What triggers bringing you back — "we want to add a new workflow" vs. "something is broken"?

Be explicit about tier 3 pricing. If you don't want to be the long-term maintainer, say so and name someone who is.

The format that actually works

One document, not five. Nobody reads five separate documents.

The format:

One-pager at the top — the inventory, one line per artifact
Then a section per artifact — following the same template each time (purpose, why, maintenance, failure modes, escalation)
Appendix: full text of every system prompt — copy-pasted, so if Claude changes how Projects work tomorrow, the client still has the prompts

PDF is the wrong format for this. It ages. Markdown in a Google Doc or Notion page that the client owns is right. You transfer the file at handoff and they can edit it.

Test it before you leave

The one test that separates a good handoff from a bad one: before you finish the engagement, sit down with the person on the client side who will own the setup. Ask them to walk through a "change the tone of the support drafts to be more formal" request, using only your documentation. If they can't do it in 15 minutes, your documentation has a gap.

Run this test twice:

The change request: can they find the right artifact, make the change, and verify it worked?
The failure case: hand them a scenario ("imagine the support drafts suddenly sound wrong — too terse"). Can they walk through the failure modes section and identify where to look first?

Both are usable signals. If they can't do one, add an example to that section. If they can't do the other, your failure-modes section is too abstract.

What you don't document (on purpose)

You don't document:

Your prompting choices at the word level. "I chose 'succinct' over 'concise' because..." Too granular, won't age well. They'll rewrite the prompt eventually anyway.
Alternatives you considered and rejected. Briefly, in the "why," is fine. A full decision log is over-engineering for a client handoff.
Your process for building the setup. This is a handoff, not a postmortem. They care about the current state, not the path you took.

If the client wants the decision log, that's a separate deliverable and a separate line item.

Try this today

If you're mid-engagement right now: open the Claude workspace you've built for your current client. Open a blank doc. Spend 20 minutes writing the inventory — just the five rows: Projects, system prompts, connectors, skills, any Code setup. Don't write the "why" or maintenance yet. Just name what exists.

If you can't write the inventory from memory in 20 minutes, your setup is more complex than your client realizes. That's the handoff problem in miniature: you know the shape of it, they don't, and that's the gap the documentation has to fill.

For client-facing deliverable handoff (not system setup), see client-handoff-with-claude. For pricing the work itself — including maintenance retainers — see pricing-claude-consulting-work.