Foundations

Writing effective prompts

Maven Tech builds Clarity — a modular, multi-container clinical AI platform where every agent runs in its own isolated ephemeral sandbox. We use Claude across three surfaces, and this guide teaches the prompt craft for all of them.

Claude Code

Agentic building inside the monorepo. Auto-loads CLAUDE.md every turn, so architectural context travels with every prompt.

Claude chat

Research, drafting, analysis, and brainstorming at claude.ai — desktop and mobile.

Claude Projects

Persistent role workspaces with standing instructions. One per role, synced from this repo’s Tier 3 prompts.

The four ingredients of a strong prompt

Ingredient	What it is	Example
Persona	Who Claude should be, or who you are.	”You are a hostile security auditor for a multi-tenant healthcare platform…”
Task	The verb. Draft, review, generate, red-team, summarize. The most important component of any prompt.	”Flag every violation”
Context	The files, invariants, constraints, and audience that shape the output.	”Check it against the CLAUDE.md invariants — RLS scoping, supervisor surface, orchestrator purity”
Format	Table, diff comments, go/no-go, 150-word email, pgTAP tests.	”Output a BLOCKER / WARN / NIT list with file:line references”

Example — all four Claude Code Copy

You are reviewing this diff as a security auditor (Persona). Check it against the CLAUDE.md invariants — RLS scoping, supervisor surface, orchestrator purity (Context). Flag every violation (Task). Output a BLOCKER / WARN / NIT list with file:line references (Format).

You don’t need all four every time. But you always need a verb.

Quick tips before you start

1. Use natural language. Write like you’re briefing a sharp new teammate. Full thoughts, complete sentences.
2. Be specific, and iterate. The first output is a draft, not a deliverable. Refine it in follow-ups.
3. Reference your files. In Claude Code, point at real paths (“per ARCHITECTURE.md §5”). In chat, paste or attach. Context beats cleverness.
4. Make Claude your prompt editor. “Improve this prompt before answering it: […]” — then run the improved version.
5. Break big asks into steps. One prompt per task. Chain them.
6. Review before you act. Claude’s output goes through the same gates as human work — CI, PR review, your own eyes. The final output is yours.

The rule above all rules — No PHI in prompts. Ever.

Never paste patient data, case files, or anything PHI-adjacent into any Claude surface — chat, Code, or Projects. Use the synthetic fixtures in fixtures/synthetic/. This mirrors the platform’s own invariant: PHI stays inside the sandbox boundary. No exceptions, no “just this once.”