Describe Your Users in CLAUDE.md So Claude Writes Appropriate Copy, Error Messages, and UX
Claude writes code for developers, but your app is used by real people who aren't developers. When Claude generates error messages like "422 Unprocessable Entity" or button labels like "Submit Form Data," it's because it doesn't know who's reading them. Fix that with a Users section in your CLAUDE.md.
# Users
Our users are small business owners, mostly non-technical.
They manage inventory and process orders through this app.
- Tone: friendly, plain English, no jargon
- Error messages: tell them what went wrong AND what to do next
- Labels: use business terms (e.g. "Products" not "Items",
"Orders" not "Transactions")
- Don't assume they know what a "slug", "webhook", or
"cache" is — explain in human terms if referencing
technical concepts in the UI
Now when Claude writes a validation error, instead of:
❌ "The email field must be a valid email address."
It writes:
✅ "That doesn't look like an email address — check for typos
and make sure it includes an @ symbol."
And when it writes a success message, instead of:
❌ "Record created successfully."
It writes:
✅ "Your product has been added! It'll show up in your store
within a few minutes."
This changes everything Claude generates for user-facing surfaces:
- Form labels match your industry vocabulary
- Error messages are actionable, not just informative
- Empty states are helpful, not blank
- Confirmation dialogs explain consequences in user terms
- Notification text is clear to non-technical users
You can also specify different audiences for different parts of your app:
# Users
- Public site: consumers browsing products, non-technical
- Admin panel: store owners, semi-technical, know business terms
- API: developers integrating with our platform, technical
Code is for computers. Copy is for people. Tell Claude who the people are and it writes for them.
via Claude Code
Log in to leave a comment.
Use the --agent flag with custom markdown files in .claude/agents/ to launch purpose-built Claude sessions with restricted tools and scoped system prompts.
Every project has traps — the billing module that silently fails if you forget to queue the job, the legacy table with column names that don't match the model, the config value that must be set before tests run. Document these gotchas in your CLAUDE.md so Claude avoids the same mistakes your team spent days debugging.
Stop passing the same flags every time you launch Claude Code. Use claude config to set your preferred model, permission mode, and other defaults — at user level for personal preferences or project level for team-wide settings that everyone inherits automatically.