I used to type out complex refactoring tasks to Claude Code interactively through the chat interface, and I’d constantly lose my train of thought halfway through explaining what I needed. Then I had a realization that completely changed my workflow: Claude can read markdown files and execute every instruction contained in them, which is an absolute game changer. Now I plan all my complex operations in well-structured markdown files before I ever talk to Claude, whether I’m refactoring 15 files at once, setting up entire project structures, or anything else complicated. I write the instructions once in markdown format, and Claude executes them perfectly every single time without me fumbling through explanations.
Table of contents
Open Table of contents
Why Markdown?
The power of planning ahead: Executing complex multi-file changes through interactive chat is genuinely terrible because you constantly forget stuff, lose track of where you are in the process, and realize halfway through that you should have approached things completely differently. Markdown completely fixes this problem by letting you plan once and execute perfectly every time. You can even commit your instruction files to version control with git add instructions/setup-auth.md so they become part of your repository, and reuse them for similar projects later by running claude < new-project/api-setup.md.
What makes instructions actually good: The single most important quality is specificity in your instructions. Bad instructions look like “Update the API to handle errors better” which is way too vague. Good instructions are like “In src/api/users.js, wrap the fetch call in a try/catch block and return {error: message} on failure” which tells Claude exactly what to do. You should also include explicit file paths rather than referring to “the config file,” arrange tasks in logical order like creating directories before the files that go in them, add verification steps that explain how you’ll know if it worked, and provide context about why you’re making the change.
Basic Structure
The standard template to follow: Start with a clear title, then add an overview section explaining what you’re building and why it matters, include prerequisites that list what must already exist before starting, write out your tasks as numbered steps with explicit file paths and specific changes for each step, add verification instructions that explain how to confirm success, and finish with a troubleshooting section covering common issues you might encounter.
Here’s a minimal working example: Title your file “Add Authentication to API” and then write three simple steps: create src/middleware/auth.js containing JWT verification logic, update src/routes/api.js to apply the auth middleware on protected routes, and create tests/auth.test.js with 4 test cases covering success, failure, missing token, and invalid token scenarios. That’s all you need to write because Claude already knows how to implement JWT authentication and what those test cases should look like.
Patterns for Different Operations
Creating multiple related files: Start by listing out the directory structure you want to create, then specify each file individually with its purpose and key functions it should contain. For example, if you’re building an analytics feature, you’d specify index.js for exports, tracker.js containing trackPageView and trackEvent functions, config.js holding your API keys and endpoints, and utils.js with any helper functions you need.
Refactoring code across multiple files: Begin with an overview explaining what change you’re making and why, then list all the files that will be affected with specific updates required for each one. For example, if you’re replacing axios with fetch across your codebase, you’d specify the exact changes needed in api.js, users.js, and posts.js, include instructions to remove the axios dependency from package.json, and add verification steps to confirm all your endpoints still work correctly after the change.
Building a feature that spans multiple layers: Organize your instructions by architectural layer rather than by file, like Backend, Frontend, Database, and Config sections. For example, if you’re adding search functionality, your Backend section covers the search endpoint and search service, Frontend covers the search component and adding it to the header, Database covers adding appropriate indexes for performance, and Config specifies parameters like debounce timing of 300ms and a maximum of 50 results per query.
Setting up new projects and configuration: Follow a clear progression from initialization through to working code. For example, when setting up an Express API, you’d start with npm init, then install your required packages, create the src/ directory structure, set up your .env and .gitignore files, add necessary middleware, and finish with a basic health check endpoint to verify everything works.
Fixing bugs that affect multiple files: Start with a clear problem statement describing the bug and its impact, list the files that need fixes with specific changes required in each, add safeguards to prevent the bug from recurring, and include testing instructions. For example, when fixing a memory leak, you’d clean up event listeners in Dashboard.jsx, Chart.jsx, and DataTable.jsx, update the useWebSocket.js hook to handle cleanup properly, add a lint rule to catch similar issues in the future, and include verification steps to confirm the cleanup actually happens.
Advanced Techniques
Handling conditional logic for different environments: Use clear “If X, then Y” structures when you need environment-specific instructions. For example, you might write “If using PostgreSQL, implement this with JSONB columns; if using MySQL, use JSON columns plus triggers; if using SQLite, store as TEXT and handle computation at the application layer.” Make sure to note which environment variable or configuration setting determines which path Claude should follow.
Creating reusable patterns across similar features: Define a template structure with clear placeholders, then list all the places where you want to apply this pattern. For example, you could define a CRUD pattern that includes a Model with schema definition, a Controller with getAll, getById, create, update, and delete functions, Routes configured with REST endpoints, and comprehensive Tests covering all operations. Then specify that you want to apply this exact pattern to Users, Posts, Comments, and Categories, which saves you from writing the same instructions four separate times.
Including verification after every major step: After each significant command or operation, explicitly specify what Claude should verify to confirm it worked correctly. For example, after running the build command, verify that the dist/ directory exists and contains files; after deploying, verify that files actually exist on the server; after restarting services, verify the health endpoint returns 200; and after checking logs, verify there are no error messages present. This makes failures immediately obvious rather than letting them hide until much later in the process.
Planning for progressive enhancement: Structure your instructions in phases where Phase 1 provides basic functionality that works for everyone, Phase 2 adds enhanced UX with JavaScript for modern browsers, and Phase 3 implements advanced features for cutting-edge browsers, with each phase working completely independently. For example, you might implement search first as a plain HTML form that works everywhere, then enhance it with AJAX for a better experience, and finally add infinite scroll plus localStorage caching for the best possible experience.
Common Pitfalls
Writing instructions that are too vague: Bad instructions look like “Make the homepage look better” which gives Claude almost nothing useful to work with. Good instructions are specific like “In homepage.css, set hero section padding to 80px, add box-shadow of 0 2px 8px to all cards, set button transitions to 200ms, and change body font size to 16px” which tells Claude exactly what changes to make.
Leaving out critical context about the problem: Bad instructions just say “Fix the bug” without any details. Good instructions provide full context like “Fix the race condition where clicking the checkout button rapidly creates duplicate charges, which happens about 5 times per day. Root cause is missing debouncing and no idempotency checks. Solution is to disable the button immediately after first click and add idempotency key verification on the backend before processing any charge.”
Arranging tasks in the wrong dependency order: Bad instructions might say to seed data first, then create tables, then install the database, which will obviously fail. Good instructions follow dependency order by installing the database first, then creating the tables within it, then finally seeding those tables with initial data.
Forgetting to include verification steps: Bad instructions just provide a list of commands to run without any way to verify they worked. Good instructions include verification after each step, like “Run build command, then verify dist/ directory exists and contains compiled files” and “Deploy to server, then curl the health endpoint and verify it returns 200 status.” You should also include rollback instructions in case something fails.
Tips for Success
Always start with a simple outline: Write a basic outline first that covers what needs to happen, which files are involved, and what order things should occur in, then go back and add all the specific details like exact code changes, terminal commands, and verification steps. Spending just 5 minutes on a good outline saves you an hour of Claude executing the wrong instructions because you weren’t clear about what you wanted.
Use clear visual separators throughout your document: Use proper markdown headers for major sections like ## Main Topic and ### Subtopic, use bold formatting when referring to specific file names so they stand out visually, and use code formatting for all file paths and terminal commands. This visual structure makes your instructions dramatically easier for both you and Claude to parse and follow.
Include concrete examples showing before and after: When you’re changing data structures or formats, show both the old and new versions explicitly. For example, show that the API response is changing from {"data": [...]} to {"data": [...], "meta": {"total": 100, "page": 1}} which leaves absolutely zero ambiguity about what the new structure should look like.
Estimate the scope upfront to prevent surprises: Include an estimate of complexity (Low, Medium, or High), expected time to complete (like 2-6 hours), roughly how many files will be modified (around 15), how many new files you’ll create (around 8), and any new dependencies you’ll need to install like Elasticsearch. This prevents those “quick” projects that somehow end up consuming your entire weekend.
Document all your assumptions about what already exists: List everything that must already be set up before you can start, like SSH access being configured, DNS records pointing to the right servers, SSL certificates obtained and installed, and databases already created. If any assumption turns out to be false, you need to do those prerequisite tasks first before executing your main instructions.
Conclusion
The three most important principles for writing effective markdown instructions are to be specific with exact details like “change button padding to 20px” instead of vague directions like “update the styling,” be organized with tasks in logical dependency order rather than random order that confuses both Claude and yourself, and include verification steps so you actually know whether each operation worked correctly.
The first time I used this approach, I successfully refactored 20 files in a single operation. It took me 15 minutes to write the markdown file with all my instructions, and Claude executed the entire thing perfectly in just 2 minutes. Doing this same refactoring manually would have easily taken me an hour of tedious work, and I definitely would have missed updating at least a few files.
Now I maintain an entire folder of reusable instruction files for common operations I perform regularly. Need to set up a new API from scratch? I’ve got a markdown file for that. Adding authentication to an existing project? Got one ready to go. Refactoring from axios to fetch across the codebase? Yep, that’s in there too.
My workflow is now as simple as vim instructions/whatever.md to write or update the instructions, then claude < instructions/whatever.md to execute them perfectly.
Write the instructions once in markdown format, and use them forever whenever you need that operation again. This approach absolutely beats typing out the same instructions to Claude for the third time this month when you’re setting up yet another similar project.