tools-only Project Instructions Guide
Guidance for creating Claude.ai Project instructions - the custom instructions that apply to all conversations within a Project workspace.
What Are Project Instructions?
Project instructions are ADDITIVE to Claude's base system prompt. They customize Claude's behavior for a specific project workspace while all conversations in that project inherit these instructions.
Critical understanding: Don't duplicate what's already in the system prompt. Focus ONLY on project-specific behavioral deltas.
System Prompt Boundary
Claude already has extensive capabilities in its system prompt:
- Citation and attribution protocols
- Copyright and safety guidelines
- General web_search and tool usage patterns
- Artifact creation logic
- Conversational tone defaults
- Basic accuracy and helpfulness standards
Your job: Specify ONLY what's different for THIS project.
Core Optimization Principles
1. Imperative Language
Frame as direct commands, not suggestions:
- ❌ "Consider analyzing data" → ✅ "Analyze data using"
- ❌ "You might want to search" → ✅ "Search for"
- ❌ "Try to be concise" → ✅ "Provide concise responses"
2. Positive Framing
State what TO do, not what NOT to do:
- ❌ "Don't use bullet points"
- ✅ "Write in flowing paragraph form because prose is more conversational for learning contexts"
Always explain WHY when framing requirements.
3. Context and Motivation
Explain reasoning behind requirements:
- ❌ "Use formal tone"
- ✅ "Use formal tone because documentation targets enterprise clients expecting authoritative voice"
4. Strategic Over Procedural
Provide goals and decision frameworks, not step-by-step procedures:
- Specify: Success criteria, constraints, decision frameworks
- Minimize: Sequential steps Claude can infer from goals
Model-Aware Project Instructions
Project instructions may be executed by different Claude models. Calibrate accordingly:
If project primarily uses Sonnet:
- Include explicit decision frameworks with clear conditions
- State fallback behaviors for edge cases
- More examples demonstrating expected patterns
- Concrete constraints over abstract principles
If project primarily uses Opus:
- Lead with goals and success criteria
- Provide rich context about WHY—Opus uses this for autonomous judgment
- Fewer procedural steps, more strategic direction
- Can include: "Apply judgment for situations not explicitly covered"
- Principles and reasoning over exhaustive rules
Model-agnostic baseline:
- Imperative language (works for both)
- Positive framing with context (both benefit)
- No system prompt duplication (universal)
- Extended thinking suggestions (model-agnostic UI feature)
If you don't control which model executes: Write for Sonnet (more explicit), with strategic context Opus will leverage.
Structure Guidance
Default: Simple and Clear
Start with headings and paragraphs:
Role: Senior data analyst specializing in healthcare metrics
Analysis approach:
Prioritize statistical significance and clinical relevance. Present findings
with confidence intervals and practical implications for clinicians.
For complex multi-variable analyses or when comparing treatment outcomes
across multiple studies, suggest enabling Extended thinking.
When to Add Structure
Use XML or structured formats ONLY when:
- Separating distinct content types in complex scenarios
- Absolute boundaries between data sources required
- API-driven workflows need structured parsing
Decision rule: Can this be organized with headings? → Do that first.
Project-Specific Elements
Role Definition
Specify expertise level and domain focus:
Role: Technical writer for developer documentation with 10+ years API experience
Quality Standards
Define what "good" means for THIS project beyond base standards:
Code quality:
All examples must be runnable without modification. Include error handling
that demonstrates production practices, not just happy path scenarios.
Decision Frameworks
Provide conditional logic for ambiguous situations:
When documentation references external APIs:
- Version 2.0+: Link to official docs
- Versions <2.0: Include inline examples (deprecated, docs may disappear)
- Upcoming features: Mark clearly as beta with stability warnings
Domain Tool Patterns
Specify ONLY if project needs DIFFERENT tool usage than defaults:
For regulatory analysis: Search official .gov sources first, then industry
bodies, because only primary sources are citable in compliance reports.
For code review: Use web_fetch to retrieve full repository context after
initial search, as snippets miss architectural patterns.
Complexity Indicators
When to suggest Extended thinking for project domains:
For security audits involving cryptographic implementations or multi-step
attack vectors, suggest enabling Extended thinking, explaining that
systematic threat modeling benefits from deeper analysis.
Project Constraints
Specific limitations or requirements with reasoning:
Maximum response length: 500 words for initial analyses because stakeholders
scan for key insights before deep dives. Offer detailed follow-up analysis
on request.
Example Patterns
Document Analysis Project
Role: Legal document analyst specializing in contract review
Analysis approach:
Extract obligations, deadlines, and liability terms with explicit line
references. Distinguish between mandatory requirements ("shall") and
optional provisions ("may").
Quality standards:
- Cite specific clause numbers for all findings
- Flag ambiguous language requiring legal interpretation
- Identify missing standard provisions (force majeure, indemnification)
For contracts with complex contingency structures or multi-party obligations,
suggest Extended thinking for thorough obligation mapping.
Technical Implementation Project
Role: Senior Python engineer specializing in data pipeline development
Implementation approach:
Write production-ready code with comprehensive error handling and logging.
Prioritize maintainability over cleverness - explicit is better than implicit.
Domain standards:
- Type hints for all function signatures
- Docstrings following Google style
- pytest fixtures over unittest classes
For architectural decisions involving distributed systems tradeoffs or when
optimizing for both latency and reliability, suggest Extended thinking.
Project constraints:
Python 3.11+, pandas 2.0+, no external API dependencies without approval.
Using Apache Airflow for orchestration - DAG patterns must follow team conventions.
Research Analysis Project
Role: Research analyst with expertise in competitive intelligence
Research strategy:
For competitor analysis: Prioritize primary sources (company blogs, SEC filings,
technical documentation) over secondary sources (news articles, analyst reports).
This is critical because competitive positioning requires exact claims, not
interpretations.
Synthesis requirements:
Present findings in comparative matrix format with evidence links. Distinguish
between verified facts, company claims, and market speculation.
For research requiring synthesis across 10+ sources with conflicting claims
or when evaluating technical feasibility of competitor features, suggest
Extended thinking toggle.
Conversational Assistant Project
Role: Learning coach for mathematics with emphasis on conceptual understanding
Interaction approach:
Use conversational paragraph form rather than bullet lists because flowing
prose better supports building mental models. Students learn better when
concepts connect naturally in narrative form.
Response adaptation:
When students struggle: Return to prerequisites before advancing, using
concrete examples before abstraction.
When students succeed quickly: Introduce extensions and applications to
maintain engagement and deepen understanding.
For proof-based topics or multi-step problem solving requiring careful
reasoning, suggest Extended thinking to students, explaining it helps
work through logical chains systematically.
Common Mistakes to Avoid
❌ System Prompt Duplication
Use web_search for current information. Create artifacts for long content.
Always cite sources accurately.
Impact: Wastes tokens, adds no value Fix: Omit entirely unless project has SPECIFIC deviations
❌ Negative Framing Without Context
Do NOT use bullet points. Never create lists. Don't be verbose.
Impact: Forces Claude to guess desired alternative Fix: "Present in natural prose paragraphs because flowing text is more conversational"
❌ Fake Thinking Triggers
Use "think carefully" for moderate thinking.
Use "think hard" for deep thinking.
Impact: Misleading - phrases don't control Extended thinking Fix: "For [specific complexity], suggest Extended thinking toggle, explaining why"
❌ Verbose Updates
Explain your reasoning at each step. Keep me updated throughout.
Impact: Slows execution, contradicts terse default Fix: "Execute efficiently. Update only when blocked or at major milestones"
❌ Procedural Micromanagement
Step 1: Analyze query
Step 2: Determine approach
Step 3: Execute search
Step 4: Synthesize findings
Impact: Restricts natural optimization Fix: "Research goal: X. Quality standard: Y. Present findings in Z format because [reason]"
❌ Tool Over-Specification
When user asks about time: call user_time_v0
When scheduling: call user_time_v0 then event_create_v1
Impact: Duplicates system prompt logic Fix: Only specify if DIFFERENT: "For legal research, prioritize web_fetch for full text because snippets miss precedent context"
❌ Contextless Requirements
Always use formal tone. Responses must be under 200 words.
Impact: No reasoning, limiting generalization Fix: "Use formal tone for audit reports because regulators expect authoritative voice. Aim for 200 words initially to respect executive time, expanding when complexity requires"
Quality Checklist
Before finalizing project instructions:
Strategic completeness:
- Role clearly defines expertise level
- Goals and quality standards are project-specific (not base behavior)
- Context explains WHY requirements exist
- Decision frameworks address realistic ambiguities
- Constraints use positive framing with reasoning
Technical optimization:
- Imperative language throughout
- Positive directives preferred over negatives
- Structure matches complexity (simple by default)
- Tool guidance only for project-specific patterns
- Extended thinking indicators for domain complexity
- No system prompt duplication
Execution readiness:
- Instructions immediately actionable
- Success criteria clear and measurable
- Silent execution enabled by default (updates only when needed)
When Project Instructions Aren't Enough
Consider Skills instead when:
- Same capabilities needed across multiple projects
- Instructions becoming very long (>1000 words)
- Procedures should load on-demand, not always present
- Want portable expertise beyond single workspace
Consider adding Skills to Project when:
- Project has persistent context (documents, data)
- Skills provide reusable methods (analysis frameworks)
- Project approaching context limits but needs capabilities
See: skill-vs-project.md for detailed comparison.
Testing Your Instructions
After creating project instructions:
- Test with 3+ realistic scenarios (simple, complex, edge case)
- Verify Claude follows project-specific behavior
- Check that instructions don't conflict with system prompt
- Confirm tone and style match project needs
- Validate Extended thinking suggestions appear appropriately
Iterate based on actual usage, not assumptions.