Stop Terminal Prompting: A Markdown-First AI Workflow
Quick Answer: Relying on interactive terminal prompts for slow AI agents forces us into constant, exhausting context-switching. To reclaim your flow state, don't code in the terminal. Instead, draft your thoughts, specs, and feedback in a local Markdown file first, using it as an offline scratchpad to keep your thinking deliberate.
Is anyone else's brain just completely fried?
Seriously. If you've been spending most of your week working with autonomous developer agents like Claude Code or Aider, you know exactly what I'm talking about.
You kick off a task, the agent spins up, and it's doing its thing. While it's spending five or ten minutes running, you think, "Well, I should probably be doing something productive." So you open a new tab and start on another task.
Before you know it, you've got six or seven different things on the go at once. It's like spinning plates, and the constant context-switching is absolutely exhausting. We've traded our old "compiling" coffee break for a frantic, reactive feedback loop. Here's how I broke out of that trap.
Why do AI agents make us feel so exhausted?
Working with autonomous agents is draining because their slow runtimes tempt us to multitask, which completely destroys our flow state. Instead of thinking deeply, we get stuck in a reactive loop of chasing terminal outputs across six different tabs.
Imagine you're building a complex schema migration. In the past, you wrote the migration, ran the test suite, and had a clear, linear path of thought. With an agent, you write a quick prompt, and then you wait. That waiting period is where the trouble starts.
Because the terminal is interactive, we treat it like a real-time chat app. We feel the urge to respond immediately to whatever partial solution or gibberish the agent spits back. This constant disruption prevents us from entering a true flow state. We stop being software architects and become reactive prompt managers.
How does a "Markdown-first" workflow solve agent fatigue?
A Markdown-first workflow replaces frantic terminal prompting with a slow, local scratchpad inside your IDE. Instead of reacting instantly to whatever the agent spits out, you brain-dump your thoughts into a file first, letting you process everything at your own pace.
You treat the markdown file as a buffer. You write down what you want to achieve, analyze what the agent did, and draft your corrections offline before the agent even sees them.
Here's an example of the scratchpad structure I keep open in my editor:
# Refactoring JWT Auth Middleware
## Agent Output Analysis
- The agent successfully updated the token validation.
- It missed handling the expired token database cleanup.
## Next Prompt Instructions
1. Keep the current middleware logic.
2. Add an automated cron cleanup function in `cron/cleanup.go`.
By keeping your thoughts in a file, you don't lose your place when you inevitably have to step away or wait for a long agent execution run.
How do you transition from terminal prompting to Markdown files?
Stop typing complex prompts directly into your CLI. Write them in a local scratchpad.md file first, then feed that file to your agent when you're ready, keeping your focus inside your IDE and away from terminal-induced panic.
This approach fundamentally changes how you interact with AI. Here's how the two workflows stack up:
| Feature | Terminal-First Prompting | Markdown-First Prompting |
|---|---|---|
| Pacing | Fast, reactive, and urgent | Deliberate, offline, and controlled |
| Cognitive Load | High (constant context-switching) | Low (single source of truth) |
| Focus | Fragile (distracted by execution logs) | Deep (focused on system architecture) |
| Output Quality | Messy, iterative trial-and-error | Structured, high-context instructions |
Writing things down gives your brain the space to actually think about the engineering problem rather than just reacting to the screen.
FAQ
How do I feed the Markdown file back to the AI agent?
Most modern agent CLIs allow you to pass files as context. You can either reference the markdown file directly in your command (like claude-code -f scratchpad.md), or simply copy and paste your structured "Next Instructions" section straight into the prompt when the agent finishes its run.
Doesn't writing Markdown slow down the development process?
Yes, it slows you down, and that's precisely the point. By forcing yourself to write a couple of paragraphs explaining your thoughts before running a command, you avoid sending the agent down hallucinated rabbit holes that take thirty minutes to debug.
Should I commit these Markdown scratchpads to git?
I don't recommend it. I add *.scratchpad.md or a dedicated .prompts/ directory to my global .gitignore. These files are meant to be temporary, highly personal cognitive buffers to help you think through a task, not permanent project documentation.
