Custom instructions in Claude Projects are one of those features that immediately feel useful — but when you actually sit down to write them, it's easy to wonder how specific to get or where to start.
I went through a fair bit of trial and error. My early attempts were minimal: "Please answer thoroughly" or "Avoid jargon." Technically valid instructions, but they didn't change much. Claude was already trying to do those things.
What actually made a difference was shifting from vague preferences to structured context. Here's what I've learned from building out custom instructions across several projects.
Why Custom Instructions Matter
Each new Claude conversation starts completely fresh. Claude doesn't know whether you're a developer, a writer, a marketing manager, or a student. It doesn't know your preferred style, your tech stack, or the vocabulary specific to your project.
Custom instructions solve this by providing persistent context tied to a project. Think of them less as commands and more as shared background: "Here's who I am, what I'm working on, and how I'd like us to work together."
That framing matters. Instructions written as commands ("Always do X") tend to feel brittle and are easy to override by accident. Instructions written as context ("You're working with someone who prefers...") tend to stick more reliably.
Three Elements That Actually Work
After testing a lot of variations, three elements consistently make the biggest difference.
1. Role and Context Definition
Tell Claude who it's working with and what the work is for.
Less effective:
You are a professional writer.
More effective:
You're the editorial assistant for a technical blog aimed at indie developers.
Readers are mid-level engineers in their 30s–40s — experienced generalists,
not deep specialists. The goal is to deliver practical know-how in a usable form,
not comprehensive coverage.
The more specific the context, the better Claude can calibrate tone, depth, and assumptions.
2. Output Constraints — Especially What NOT to Do
Specifying what you don't want is surprisingly effective.
Response style:
- No preambles or summaries announcing what you're about to say
- Prefer prose over bullet lists; use lists only when genuinely necessary
- Match length to the question — short answers are fine when appropriate
- Show complete, runnable code examples rather than isolated snippets
The "no preambles" instruction alone makes a noticeable difference. Claude's default behavior includes a lot of "Great question! Here are a few perspectives..." style openings. Removing those streamlines the conversation significantly.
3. Shared Vocabulary and Domain Context
Project-specific terms and assumptions you'd otherwise have to re-explain constantly.
Project terminology:
- "article" = an MDX blog post (mixed code and markdown)
- "push" = the full commit + git push workflow
- "site" = claudelab.net or gemilab.net
Common tools in use: Claude Code, Next.js, Cloudflare Workers, GitHub Actions
This is especially useful for projects with non-obvious constraints. "Cloudflare Workers" tells Claude a lot — no Node.js-specific APIs, limited execution time, specific environment patterns.
A Working Instruction Structure
Here's a template based on what I use for my coding assistant project:
## Your Role
Act as a technical partner for a solo developer — support code, architecture,
and writing tasks.
## Reader/User Profile
- Mid-level engineer working daily with Next.js and TypeScript
- Cloudflare Workers for infrastructure
- Solo developer, so values speed of implementation alongside maintainability
## Response Style
- Japanese preferred, polite but concise
- Prioritize working code over lengthy explanation
- Add a 1–2 sentence "why" for each non-obvious choice
- Skip preambles, summaries, and recaps
## Decision Priorities
1. Correct (type-safe, proper error handling)
2. Simple (avoid over-abstraction)
3. Works on Cloudflare Workers (no Node.js-specific APIs)
## Project Context
- Repo: masakihirokawa/claudelab.net
- Stack: Next.js, TypeScript, Cloudflare Workers, next-intl
- Deploy target: Cloudflare Pages
The "Decision Priorities" section is what I added late — and it made the biggest difference. Explicitly putting "Works on Cloudflare Workers" as criterion #3 almost eliminated suggestions that would break in the edge runtime.
When Instructions Aren't Working
If your instructions don't seem to be taking effect, the issue is usually one of these:
Too long. Once you're past roughly 400–500 characters per section, later instructions tend to fade. Pare down to the 3–5 things that matter most.
Mixing mandatory and contextual behavior. "Show code examples when needed" isn't an instruction — it's a description of what you'd probably do anyway. Reframe: "When code is relevant, always provide a complete, runnable example."
Vague adjectives. "Clear," "concise," "appropriate" — Claude is already optimizing for these. Specific constraints like "three sentences maximum" or "no bullet points" are what actually change behavior.
The Value of Separate Projects
Custom instructions work best when a project has a single, clear purpose. I maintain separate projects for:
- Article writing: tone, voice, article structure conventions
- Coding help: tech stack, constraints, code style preferences
- Idea exploration: instructions that favor divergent thinking over critical analysis
When everything goes into one project, the instructions become a compromise. Focused projects with focused instructions give more consistent results.
Keep Iterating
The best custom instructions aren't written all at once — they're built up gradually as you notice what works and what doesn't.
I revisit each project's instructions roughly every two weeks: trim anything that didn't seem to do much, add new constraints I discovered I cared about. Over time, each project's instructions become a fairly accurate model of how I want to work — and that's when they become genuinely valuable.