Map
Claude Code for the Rest of Us
The Ultimate Playbook for Non-Coding Tasks and Workflows
by Krishna Veera Vanamali Y
Map Starter Kit
ESC
Start typing to search across all chapters
22 min read

Chapter 4: How to Give Better Instructions

Why Instruction Quality Matters More Than Tool Sophistication

Here is a counterintuitive truth: the quality of your results from Claude Code depends more on how you give instructions than on which plugins you have installed or which model you are running.

I have seen people with the full plugin stack and the most powerful model get mediocre results because they give vague instructions. I have also seen people with a minimal setup get extraordinary results because they are precise, context-rich, and strategic in how they communicate with Claude.

Claude Code is not a search engine. It does not reward keywords. It rewards clarity, context, and specificity. The more clearly you can describe what you want, why you want it, and what constraints exist, the better your results will be.

The “Working Directory First” Principle

Before every instruction, make sure you are in the right folder. This sounds trivial but it eliminates the most common source of errors for new users.

Bad workflow:

claude
> Analyze the survey data

(Claude cannot find the file because you launched from your home directory)

Good workflow:

cd ~/Desktop/Survey-Project
claude
> Analyze the survey-responses.csv file and give me a breakdown by respondent role

File Path Discipline: Always Give Exact Paths

When referencing files, use specific paths. Do not make Claude guess which file you mean.

Vague: “Read the PDF and summarize it” Specific: “Read /Users/krishna/Desktop/Reports/industry-report-2025.pdf and summarize the key findings in three bullet points”

Vague: “Analyze my data” Specific: “Read the CSV file at /Users/krishna/Desktop/Data/linkedin-posts-2025.csv and classify each post by sector and content type, using these categories: [list categories]”

This is especially important when you have multiple files of the same type. If your folder has six PDFs, Claude needs to know which one you mean.

Context Loading: When to Drop Files, Screenshots, and References

Claude Code can process many types of context:

Files: You can reference any file on your computer by its path. Claude will read it on demand. “Read /path/to/file.pdf and tell me what it contains.”

Screenshots and images: You can include images by providing their file path. “Look at the image at /Users/krishna/Desktop/screenshot.png and describe the layout.”

Pasted content: You can paste text directly into your instruction. For short pieces of content, this works well.

Previous outputs: You can reference files that Claude created in a previous step. “Take the chart you just created and add a title.”

The principle: Load the context Claude needs to do its job, and nothing more. Do not dump ten files into a prompt if Claude only needs two. Do not provide your entire background when the task only requires a specific data file. More context is not always better — relevant context is better.

Plan Mode: When to Use It

Plan mode is one of Claude Code’s most underused features, and it is one of the most valuable for complex tasks.

In plan mode, Claude can read files, explore your project, search the web, and formulate a strategy — but it cannot make any changes. It is a “look but do not touch” mode. You activate it by pressing Shift+Tab twice (cycling through permission modes) or by starting a session with --permission-mode plan.

When to use plan mode:

My workflow for major tasks:

  1. Start in plan mode
  2. Describe the task and ask Claude to create a plan
  3. Review the plan — adjust, add constraints, clarify requirements
  4. Exit plan mode and tell Claude to execute the plan

This approach prevents wasted work. If Claude’s proposed approach is wrong, you catch it before any files are created or modified.

As a Claude prompt (plan mode):

I need to [describe the overall task]. Before we start, I want you to:
1. Read the relevant files in this project
2. Understand the current state
3. Propose a step-by-step plan for how to accomplish this

Do not make any changes yet — just present the plan for my review.

The Research-Plan-Execute Framework

Plan mode is powerful, but for serious projects — anything that will take more than thirty minutes or involve multiple deliverables — I use a more rigorous framework that I call Research-Plan-Execute. This is the single most important methodology in my entire Claude Code practice, and it is what separates “trying things and hoping for the best” from consistently producing excellent work.

The core idea: never let Claude act on a project before you have reviewed a written plan. And never let Claude plan before it has done proper research. Every serious piece of work passes through three distinct phases, in order, with your review at each gate.

Phase 1: Research (RESEARCH.md)

Before any planning or execution, Claude researches the problem space and writes its findings to a file called RESEARCH.md in your project directory — not in a hidden folder, not in its internal memory, but right in your project where you can open it in any text editor.

As a Claude prompt:

I need to [describe the project — e.g., "build a landing page for
a new product launch" or "create an analysis of our podcast
performance data"].

Before we plan anything, I want you to research this thoroughly.
Read the relevant files in this directory, search the web if
needed, and write your findings to RESEARCH.md.

Cover:
1. What exists currently (read the files)
2. What approaches or patterns are common for this type of project
3. What tools, dependencies, or setup will be needed
4. Any constraints or considerations I should know about

Write RESEARCH.md and stop. Do not plan or execute anything yet.

Claude produces a research document. Here is the critical step: you open RESEARCH.md in your text editor and annotate it.

The Annotation Cycle

This is where the framework becomes powerful. You do not just read Claude’s research and say “looks good” — you mark it up. Open RESEARCH.md in any editor you are comfortable with, and add your thoughts directly:

As a Claude prompt:

I have annotated RESEARCH.md with my corrections and additions.
Read it again and update the research based on my annotations.
Then we move to planning.

Claude reads your annotated version, incorporates your feedback, and updates the research document. You review again. This cycle repeats until the research accurately reflects reality.

Why this works: Claude is brilliant at gathering and organizing information but it does not know your business context, your constraints, your audience’s preferences, or your unstated assumptions. The annotation cycle lets you inject your knowledge into Claude’s research without having to write it from scratch. You are correcting and directing, not creating.

Phase 2: Plan (PLAN.md)

Once the research is solid, Claude creates a detailed plan — again, as a visible file in your project directory.

As a Claude prompt:

The research is complete. Now create PLAN.md with a detailed
execution plan for this project.

The plan should include:
1. A clear list of deliverables (what we are producing)
2. Ordered steps to get there
3. For each step: what input is needed, what output is produced,
   what decisions I need to make
4. Mark each step with a checkbox: [ ] incomplete, [x] complete
5. Flag any steps where you need my input before proceeding

Write PLAN.md and stop. Do not execute anything yet.

Claude produces the plan. And now — the same annotation cycle repeats. You open PLAN.md, mark it up:

As a Claude prompt:

I have annotated PLAN.md. Read my annotations, update the plan,
and present the final version for my approval.

The plan goes through one or two annotation cycles until it is tight. Now you have a clear, reviewed, annotated plan — sitting in your project directory as a real file you can reference in future sessions.

Phase 3: Execute

Only after research is validated and the plan is approved do you tell Claude to execute.

As a Claude prompt:

The plan is approved. Execute PLAN.md starting from step 1.

Rules:
- Work through the steps in order
- Mark each step [x] as you complete it in PLAN.md
- If you hit a decision point or are unsure about something, stop
  and ask me before proceeding
- After completing each major section, pause for my review

During execution, your role shifts. In the research and planning phases, you were the architect — making design decisions, correcting assumptions, shaping the approach. In the execution phase, you become the supervisor. You watch Claude work, intervene only when something goes off track, and provide quick corrections.

The corrections during execution are short — “No, use a different color palette” or “That section header should be a question, not a statement.” You are not redesigning; you are fine-tuning. The heavy thinking happened in the planning phases.

The todo tracking is key. Because PLAN.md has checkboxes, you can see exactly where Claude is in the process at any time. If a session gets interrupted, the next session picks up from the last unchecked item. The plan is a living document that shows progress.

When Things Go Wrong: The Revert-and-Redo Rule

Sometimes, despite good planning, an execution step goes in the wrong direction. Maybe Claude misinterpreted an instruction. Maybe the output is not what you envisioned. Maybe the approach just does not work once you see it.

The rule: do not try to fix a bad output. Revert and redo.

This is counterintuitive — it feels wasteful to throw away work and start over. But in practice, continuing to fix broken work almost always takes longer and produces worse results than reverting to the last known good state and re-executing with clearer instructions.

As a Claude prompt:

That last step did not go in the right direction. Let us revert
everything from step 4 onwards. Restore the state from before
step 4 and let us redo it.

Here is what I want differently this time:
- [Specific correction 1]
- [Specific correction 2]

Update PLAN.md to reflect the corrected approach, then execute.

The beauty of having RESEARCH.md and PLAN.md: even if you revert execution, your research and plan survive. You are not starting from scratch — you are re-executing from a solid foundation with better instructions.

If you are using git (which Chapter 5 covers), you can literally revert file changes. If you are not, Claude can recreate or restore previous versions of files.

Why One Long Session

I do the entire Research-Plan-Execute cycle in a single Claude Code session whenever possible. The reason: context. When Claude has the full history of the research phase, the annotation cycles, and the planning discussions in its memory, its execution is dramatically better. It remembers why you made certain decisions. It remembers the constraints you flagged. It remembers the correction you made in the second annotation round.

If you split this across sessions, you lose that context. The RESEARCH.md and PLAN.md files preserve the decisions, but they do not preserve the nuance of the discussion. For projects that fit within a session, keep everything together.

For projects too large for a single session, use /compact at natural breakpoints (end of research, end of planning) and rely on the RESEARCH.md and PLAN.md files plus your CLAUDE.md to carry context forward.

Quick Reference: The Framework in Practice

Phase Your Role Claude’s Role Output
Research Annotate, correct, add context Gather information, organize findings RESEARCH.md
Plan Annotate, reorder, approve Design the execution plan PLAN.md
Execute Supervise, course-correct Build, create, process Deliverables

When to use this framework: - Any project lasting more than 30 minutes - Any project with multiple deliverables - Website builds - Data analysis and report writing - Content creation campaigns - Research projects - Any task where “getting it right the first time” matters

When to skip it: - Quick one-off tasks (download a video, convert a file) - Tasks you have done many times before with established workflows - Tasks where the output is easily reversible (you can always redo a chart)

This framework adds ten to fifteen minutes of research and planning time upfront. It saves hours of rework, miscommunication, and frustration. Every major project I have done with Claude Code in the last three months has followed this pattern, and it is the single biggest reason my results have been consistently strong.

The Installable Interview: The Superpowers Plugin

Research-Plan-Execute is a discipline — you have to remember to run it, and on a rushed day you will be tempted to skip straight to building. The superpowers plugin removes that temptation. It packages the same discipline as an enforced workflow.

Inside Claude Code:

/plugin install superpowers@claude-plugins-official

Then say “let’s build X.” Instead of building, Claude interviews you — one question at a time — about what you actually want.

It proposes two or three approaches with the trade-offs spelled out. It writes a short design doc and waits for your approval. Only then does it produce a step-by-step plan.

Here is the part I like most: it refuses to start building until you have approved the design, even for “simple” projects. Those are exactly the ones where skipped planning quietly costs you an afternoon.

I run my big projects through it. The updates to this playbook and my entire advanced-package build went through the same pipeline: brainstorm, then spec, then plan, then execution. The plugin did not slow me down — it slowed the mistakes down.

Get Grilled Before You Build

Superpowers interviews you constructively — it wants to help you design. There is a harsher sibling pattern circulating in the community: a tiny “grilling” skill where Claude interrogates you adversarially about your own plan.

The mechanics: Claude walks through your plan one question at a time, each question paired with its recommended answer, until every open decision is resolved. Anything that is a fact gets looked up. Anything that is a decision gets put to you, and Claude waits for your answer.

I keep this skill in my setup and fire it before committing to any serious plan. It catches the decisions I did not realize I was making by default.

Now the kicker: the entire skill is about ten lines of instructions. So do not install it — create it, and make it your first truly tiny skill. Make the folder, drop this file in, and it is yours:

In ~/.claude/skills/grilling/SKILL.md:

---
name: grilling
description: Grill the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building.
---

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.

If a *fact* can be found by exploring the codebase, look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.

Do not enact the plan until I confirm we have reached a shared understanding.

Next session, say “grill me on this plan” and brace yourself. (Chapter 11 covers skills properly — you do not need any of that theory for this one.)

/compact for Long Sessions: Managing Context Limits

Claude Code has a context window — a limit to how much information it can hold in a single conversation. For very long sessions with many back-and-forth exchanges, you can approach this limit.

When you do, the /compact command is your friend. It tells Claude to summarize the conversation so far, compressing it to free up space for more exchanges. Think of it as Claude making notes and filing away the details so it can continue working.

When to use /compact:

Tip: Pair /compact with a good CLAUDE.md. The CLAUDE.md ensures critical context is reloaded even after compaction, so you never lose your most important project information.

Context Strategy for Large Tasks: Break, Save, Sequence

Compaction is not enough for truly large tasks. There are jobs where even starting with a fresh, empty session, you will hit the context limit before the work is done. When that happens, compaction cannot save you — there is simply too much material for Claude to hold in memory at once.

I learned this the hard way, twice.

The problem with “do it all at once.” I had a list of twenty-one edits to make to this playbook. Twice, I tried giving Claude the full list and saying “implement all of these.” Both times, Claude researched several items, started implementing, and hit the context limit mid-task. The session stopped. Work was lost. I had to start over.

The third time, I changed the approach completely:

  1. Research first, save to files. I had Claude dispatch parallel sub-agents to research all twenty-one items simultaneously. Each agent saved its findings to a separate markdown file in a /research/ folder. This took the research out of Claude’s memory and put it on disk — where it survives compaction, session restarts, and context limits.
  2. Implement one at a time. With all the research saved as files, I asked Claude to implement each edit sequentially — reading the relevant research file, making the edit, and moving on. Before each implementation, I asked clarifying questions to make sure the edit was right.
  3. Delete the scaffolding when done. The research files were temporary scaffolding. Once all twenty-one edits were implemented in the playbook, the research files became deletable.

The key insight: the research files acted as an external memory system. Sub-agents do valuable work — web searches, document analysis, code exploration — but their findings live in the conversation context, which gets compressed or lost during compaction. By saving research to files first, you preserve that work permanently. Claude can read it back whenever needed, even across sessions.

The same pattern applies to document processing. I had fourteen invoices across two months that needed analysis — extracting line items, classifying costs, computing totals. Even starting with zero context, Claude hit the limit because PDF parsing is extraordinarily context-heavy. Every page of a PDF becomes thousands of tokens when Claude reads it. Fourteen multi-page invoices consumed the entire context window before the analysis was complete. Compaction could not help — the raw PDF content was too large to compress meaningfully.

The fix: break by month. Process January’s invoices first, save the analysis to a file. Then process February’s invoices, save that analysis. Then merge the two analyses into the final output. Each batch fit comfortably within the context window. The intermediate files preserved everything.

The principles:

  1. PDFs and large documents are context-heavy. Break processing into batches — by month, by folder, by category. Do not try to read twenty documents in a single pass.
  2. Save intermediate work to files before implementing. Research, analysis, extracted data — anything valuable that Claude produces should be saved to disk, not left floating in conversation context. These files survive compaction and session restarts.
  3. Implement sequentially with checkpoints, not all at once. One task at a time, confirming each is correct before moving on. This is slower per-item but dramatically more reliable end-to-end.
  4. Temp files are disposable scaffolding. Research files, intermediate analyses, extracted data dumps — create them freely, use them as scaffolding, and delete them when the final output is complete.

This pattern — break the work, save intermediate outputs, sequence the implementation — is the difference between a task that crashes at 80% and one that completes cleanly. It applies to any large project: bulk document processing, multi-chapter writing, extensive codebase refactoring, or any task where the input material alone threatens to fill the context window.

/context and the Status Line: Know Your Token Budget

Before you need to compact, it helps to know how much context you have left. The /context slash command shows you exactly how much of your context window is consumed — how many tokens are in use, what is taking up space, and how much room remains.

Get in the habit of checking /context periodically during long sessions, especially after loading large files or when you have many MCPs active. It takes one second and prevents the surprise of hitting context limits mid-task.

The status line at the bottom of your terminal also provides real-time token usage information. In Warp and other modern terminals, you can see at a glance how full your context is, what model you are using, and what git branch you are on. You can customize what appears using the /statusline command.

Between /context for detailed checks and the status line for ambient awareness, you always know where you stand. This matters because context is a finite resource — every file Claude reads, every MCP tool definition loaded, every exchange in the conversation eats into it. Awareness leads to better decisions about when to compact, when to start fresh, and when to keep going.

Fast Mode: Trading Cost for Speed

Claude Code offers a fast mode (toggle it with /fast) that outputs approximately 2.5 times faster at a premium price — currently about twice the standard rate. It is not switching to a weaker model to get that speed; it is prioritizing latency over cost efficiency.

One caveat before you reach for it: fast mode is tied to Opus. If you are on the Pro plan, where Sonnet 5 is the default model, /fast is not a general speed lever for whatever you happen to be running — it is an Opus-only, premium-priced toggle. Treat it as a deliberate splurge for deadline moments, not a default setting.

When fast mode shines: - Iterative design work where you are waiting on Claude frequently (build → review → tweak → review) - Rapid prototyping sessions where momentum matters - Batch processing where each step is quick but you are doing many of them

When to skip it: - Long-form writing or analysis where thinking time improves quality - Sessions where you are not waiting on Claude (you are reviewing outputs between steps anyway) - When you are watching your API costs closely

I toggle fast mode on during intense design iteration sessions and turn it off for writing and research. The speed difference is noticeable enough that it changes the rhythm of how you work.

Rate Limit Management

Depending on your Anthropic plan, you may encounter rate limits — moments when Claude Code pauses because you have made too many requests in a short period.

When this happens:

Rate limits are not a bug. They are a sign you are using the tool intensively, which is good. Plan your work sessions accordingly — front-load your most complex tasks when your rate limit is fresh, and save lighter tasks for when you might be approaching limits.

The Difference Between a Task and a Conversation

One final mindset shift that dramatically improves instruction quality: treat Claude Code as a task executor, not a conversational partner.

With a chatbot, you might say: “I’m thinking about analyzing my LinkedIn posts. What do you think would be interesting to look at?”

With Claude Code, you should say: “Read the file at /path/to/linkedin-posts.csv. Classify each post by sector (Fintech, Consumer, SaaS, Deep Tech, General) and content type (Original Insight, Data-Driven, News Commentary, Personal Reflection). Save the results as a new CSV with two additional columns.”

The first is a conversation. The second is a task. Claude Code excels at tasks. Be specific about:

The more task-like your instructions, the better your results.

The Anatomy of a Great Instruction

After hundreds of sessions, I have noticed that the best instructions share a common structure. Here is the template I use mentally for every non-trivial task:

As a Claude prompt (template):

[CONTEXT: What are we working with?]
Read the file at [PATH]. / Look at the data in [LOCATION].

[TASK: What should Claude do?]
Analyze / Create / Extract / Build / Write / Convert ...

[SPECIFICATIONS: How should it be done?]
Following these rules: ...
Using this format: ...
In this style: ...

[CONSTRAINTS: What are the boundaries?]
Do not include ...
Keep it under ...
Focus only on ...

[OUTPUT: What should be produced and where?]
Save as [FORMAT] to [PATH].
Give me [NUMBER] options.
Present the results as [TABLE/CHART/DOCUMENT].

A good instruction reads like a creative brief, not a conversation. You would not walk up to a designer and say “make something cool.” You would give them a brief with the audience, the message, the format, the constraints, and the timeline. Treat Claude Code the same way.

The BRIEF.md Kickoff

If the best instruction reads like a brief, take the next step: make it an actual file. For any project of substance, I prepare the folder with a BRIEF.md before the first session — all the context, the constraints, and the success criteria in one place.

Then every session, including every restart, opens with exactly one line:

Say to Claude:

Read @BRIEF.md and do what it says.

That is the entire bootstrap. No re-explaining, no scrolling through yesterday’s chat, no “as I mentioned earlier.”

The brief evolves as the project does — requirements change, you edit the file; a new constraint surfaces mid-session, you add it. Nothing important lives only in chat history, because chat history dies and files do not.

The Brain Dump Method: Voice First, Refine Later

The best prompts I write start as brain dumps. Here is the process:

Step 1: Talk it out. I use WisprFlow (a voice-to-text tool that runs on macOS — hold fn once to talk, double-tap fn for hands-free mode) to speak my full thought. I do not edit while talking. I let the ramble flow: context, constraints, what I want, what I do not want, half-formed ideas, everything. WisprFlow transcribes in real time and pastes the text wherever your cursor is.

Step 2: Light cleanup. I scan the transcription for obvious errors but I do not over-polish. Claude Code is remarkably good at parsing messy, verbose instructions. The priority is completeness — capturing every constraint and context point — not elegance.

Step 3: Restate the core ask at the end. After your full context dump, repeat the most important part of what you want Claude to do. One to two sentences at the bottom that clearly restate the actual task.

This “restate at the end” technique has scientific backing. A research paper by Leviathan, Kalman, and Matias (“Prompt Repetition Improves Non-Reasoning LLMs,” arXiv:2512.14982) demonstrated that simply repeating the input prompt improves performance across models including Claude, GPT, Gemini, and Deepseek — with zero additional cost or latency. The study focused on non-reasoning models, but in my experience, this pattern also helps with reasoning models like the ones Claude Code uses. When you dump a long, detailed context and then restate the core task at the end, Claude has a clearer signal about what matters most. Think of it as the difference between a memo that buries the ask in paragraph six versus one that ends with a clear “Action Required” line.

The voice-first approach has an additional benefit: you naturally include context that you would self-censor when typing. When speaking, you tend to say “oh, and also make sure it does not do X, because last time it did Y” — these throwaway additions often contain the exact constraints that make the difference between a good output and a great one.

Common Instruction Patterns That Work

Here are the instruction patterns I reach for most often, distilled from real usage:

The “Step-by-Step Chain” pattern (for multi-step workflows):

Step 1: Read [input] and [analyze/extract/process].
Step 2: Using the results from Step 1, [create/build/transform].
Step 3: Based on Step 2, [write/format/polish].
Step 4: Save all outputs to [location].

The “Options” pattern (for creative work):

[Context and task description].
Give me [3-5] different options for [the creative element].
For each option, explain the angle or approach.
Let me pick before you finalize.

The “Batch Processing” pattern (for processing multiple items):

Go through the folder at [PATH].
For each [file type] in the folder:
1. [Action 1]
2. [Action 2]
3. [Action 3]
Then compile everything into [summary format].

The “Research and Synthesize” pattern (for research tasks):

Research [topic] using web search.
Focus on:
1. [Specific question or angle]
2. [Another question]
3. [Another question]
Save raw findings to [location].
Then write a synthesis that [specifies the format and audience].

The “Transform and Repurpose” pattern (for content adaptation):

Read [source material] at [PATH].
Transform it into [target format]:
- [Formatting rule 1]
- [Formatting rule 2]
- Tone: [specification]
- Length: [specification]
Save as [format] to [location].

These patterns are not rigid templates — they are thinking structures. Once you internalize them, you will naturally construct instructions that give Claude what it needs to produce excellent results.

← Chapter 3: CLAUDE.md — Your AI's Long-Term MemoryChapter 5: Front-End Design and Web Development →