How to Write Claude Projects Instructions That Actually Work

Generic project instructions fail. They fail because they treat Claude like a search engine—you feed it a question, it spits out an answer. Claude Projects aren't questions. They're persistent relationships. Your instructions define the rules of that relationship. This guide shows you how to write instructions that actually stick.

1. Start with Role, Not Task

The biggest mistake: describing what you want Claude to do. The right move: describing who Claude is in your project. Wrong:

You are an AI that writes code reviews.

Right:

You are a principal engineer doing code review for a team using Cursor + Claude.
Your job is to catch logic bugs, security issues, and performance problems.
You assume the author is competent and learning. Be direct, not condescending.

Role-first instructions work because they anchor Claude to an identity, not a task. Identity persists. Tasks change.

Example: For a finance automation project: 'You are a finance operations lead building a compliance-first accounting automation system. You think in terms of audit trails first, efficiency second.'

2. Explicit Format Requirements

Claude will output beautifully formatted responses by default. But if you need a specific format—JSON with exact keys, structured tables, decision trees—you need to show it. Show, don't tell:

{
  "review_type": "logic|security|performance",
  "severity": "critical|high|medium|low",
  "location": "file.js:line_number",
  "issue": "What's wrong",
  "fix": "How to fix it",
  "reasoning": "Why this matters"
}

Then say: 'Always respond in this JSON format. Always include all fields.' Claude will follow. The structure in your instructions IS your specification.

Example: For a meeting note project: Show Claude a 3-meeting example with your exact YAML frontmatter format, bullet-point depth, and attendee tagging style. Claude will replicate it.

3. Constraints Are Your Friends

Constraints feel restrictive. They're actually liberating—they tell Claude exactly where the boundaries are. Good constraints: - 'Always cite the function name and line number for code issues.' - 'Never apologize. Be direct.' - 'If you don't know, say "unknown" instead of guessing.' - 'Prioritize security over convenience.' - 'Keep explanations under 3 sentences unless asked.' Claude respects constraints because they're predictable. Predictability = consistency. Consistency = trust.

Example: For a customer support bot: 'If the user asks about billing, always offer the refund policy link. If they ask about a feature you don't know, escalate to support@. Never make promises about timelines.'

Claude Projects instructions are code. Treat them like code. Role definitions are your classes. Format requirements are your types. Constraints are your assertions. Examples are your tests. The better your instructions, the better your partner. Build it right.