DEV Community: Mares Popa

The Markdown Engineer

Mares Popa — Wed, 09 Sep 2026 10:48:28 +0000

My own task has been substantially altered in the last few months, and I now spend most of my time writing down my specifications in a markdown format, writing prompt constraints, defining bounds, and checking architectures. I find myself writing far less actual TypeScript and JSX than I used to.

A few years ago, if you had told me that my main tool for coding would be a text file, I would have been unable to believe you. But lately I have come to see the task of coding as less a question of raw code and more of orchestration. We are becoming AI Orchestrators.

But this transition comes with a hidden cost, one that nobody seems to talk about: the steady dilution of our code literacy.

The Illusion of Output and the Blind Spot

When modern AI tools are used to generate complex UI components, async hooks, and state persistence logic, the effect is almost magical. The code arrives in seconds, looking very nice, nicely formatted, and passing basic tests on the first try.

But the danger comes when the generated code is accepted too quickly: the mental model is lost. If you don't have to step through the logic yourself, line by line, you miss all the subtleties that lie embedded in the implementation.

How does this state hook behave during rapid offline re-renders? What happens when two writes arrive at IndexedDB at the same time? Will this component produce a sudden thrashing of the layout thread without being notified by the main thread?

When you do not completely understand the program you are running, you are not an engineer; you're a gambler, gambling on production.

Pressure-Testing Ideas: The /quiz-me Skill

To help me fight against this entangling attitude, I've developed several local skills for my local AI workflow.

The most important one, one I call /quiz-me, reverses the normal role of the LLM from code-generator to merciless interviewer, so when I have a proposed architectural change or refactoring, I force the model to examine it before writing any lines of code:

It seeks hidden failure modes and unhandled edge cases.

It challenges my state management and trade-offs.

It forces me to justify why a particular abstraction makes sense.

Since I have to answer and defend these questions, I must indeed build a complete mental model of the solution. The AI ceases to be a shortcut that makes me lazy and becomes a sparring partner that trains my critical thinking.

Do Human Code Reviews Even Make Sense Anymore?

The shift forced me to consider one of the most sacred practices in modern software engineering: the traditional code review on pull requests. In a world where an LLM can generate 500 lines of plausible code in ten seconds, a review in the form of a visual line-by-line examination by another human engineer is fast becoming an obsolete procedure.

Human eyes are notoriously bad at catching subtle async race conditions, missing edge-case fallbacks, or memory leaks during a superficial PR review—especially when the diff is huge. The true code review does not happen after the code has been written, in a static diff; it takes place before, at the specification and architectural level, with questioning, explicit constraints and targeted interrogation.

The review has shifted from whether the syntax was written correctly to asking whether the architectural boundary is sound.

The Hidden Cost: Token Overhead & Context Bloat

This kind of work doesn't come for free. The more context you feed into your artificial intelligence, the more your API costs will increase, and your token budget will gobble up faster. Large, unstructured contexts not only cost more money; they also degrade the intelligence of the model, which will cause hallucinations and omissions. Here are some practical tips to keep the context small and costs down:

Provide an Explicit File List: Never tell an agent to look across the project if it can be avoided. Explicitly pass a targeted list of files (e.g., src/features/auth/useSession.ts, src/types/user.ts). Restriction of scope reduces input token bloat dramatically.

Before invoking any high-cost model or running any complex terminal commands, I outline the context, the objectives, and the file structure locally in Markdown. Tools like my own Hermes Markdown were designed for this exact state of flux—a simple, local-first place to get ideas organized without tracking or cloud friction.

Fail Fast with Pre-Flight Guards: Use small, targeted checks (like a /smart-commit check) to catch basic errors, like debug statements or broken TypeScript signatures, before launching expensive, multi-file context audits.

Are We Ready to Be Orchestrators?

We are, no doubt, entering the era of the Markdown engineer. Writing programs is becoming less a question of syntax and more a matter of system design, domain knowledge, and interrogation skills. The future of software engineering is not to write faster, but to ask better, more difficult questions before there is any code.

I spent a few years building my own markdown editor

Mares Popa — Thu, 23 Jul 2026 20:05:04 +0000

I started HermesMarkdown back in 2023 as a personal tool — I just wanted a plain Markdown editor for my own notes, nothing more ambitious than that.

I'm a software engineer by trade, and this was very much a side project: something to write in during evenings, not a product.

It kept changing shape as my own habits changed. I rewrote the editor engine more than once, dropped features I'd added and regretted, and settled — slowly, not in one flash of insight — on a smaller idea than I started with: keep everything a plain file, keep the frontmatter predictable, and don't make the app the smart thing in the loop.

That's the version of HermesMarkdown that exists today, three years and a lot of rewrites later. I wanted to talk about a few of the architectural decisions and trade-offs behind it.

1. It runs in the browser but never touches a server

This was the part I was most stubborn about. The editor uses the native File System Access API (showDirectoryPicker()) to read and write a folder directly from Chromium-based browsers — no upload step, no account, and no third-party sync service in the middle.

You open a folder, you're editing the actual files on your disk, and closing the tab doesn't lose anything because nothing was ever "in" the app to begin with.

The trade-off: Firefox and Safari don't implement the File System Access API, so the vault picker is simply disabled there. I went back and forth on whether that was an acceptable cost for the architecture and decided it was — a tool that's local-first "most of the time" isn't really local-first.

2. Frontmatter as a strict contract, not a feature

The metadata schema is deliberately tiny:

---
title: "Dev.to Draft"
status: draft
tags: [architecture, webdev]
---

That's it. No custom fields, no per-vault configuration. Every extra field is one more thing to fill in before you can start writing, and that's exactly the friction I was trying to remove.

The status key cycles through draft → review → active → archived and stays in sync with a lifecycle tag inline in the document, so you can update it either from the frontmatter panel or by clicking the tag directly in the text.

3. AI, only when you ask for it

There's no default model baked in, and no AI running ambiently in the background. AI is an opt-in chat interface connected strictly to your own API key (Anthropic or Google Gemini) — nothing more, nothing less.

A lot of modern tools default to the AI layer being always-on. For something that holds personal notes, I wanted the opposite: invisible until summoned. Without an API key configured, zero note content ever touches a network request.

4. Built to never need a mouse

The editor opens full-screen by default — no toolbar, no sidebar, and no clutter:

Slash commands: typing /table, /code, /math, or /link lets you insert elements quickly without touching a formatting bar
Global palette (CTRL+SHIFT+P): a fuzzy-searchable list of every app-level action
Keyboard-driven tables: sorting columns, inserting rows, and exporting as CSV all work purely through Tab, Shift+Tab, and arrow keys

5. Dictation with a safety buffer

Pressing CTRL+SHIFT+V triggers speech input. Speech lands in an editable preview first — not directly into the note file — so you can fix misheard words before committing them.

Say "insert this" (or hit Enter) to commit text at the cursor
Say "new paragraph" for line breaks, or "scratch that" to undo the last phrase
It's transcription-only, keeping the focus entirely on plain text without unexpected formatting glitches

6. Minimal on purpose

Dual views: switch seamlessly between rendered and source views — both editable, writing directly to the same file
Live inline rendering: Mermaid diagrams and LaTeX math render live inline, but round-trip cleanly as plain fenced code and $...$ syntax on disk
Vault task management: a centralized view aggregates every Markdown checkbox across your vault by status

None of this is groundbreaking on its own — keyboard-first editors and voice dictation both exist elsewhere. What I was chasing was the combination: a clean writing surface that gets out of the way, stays a plain file on disk, and only adds AI when you explicitly ask for it.

What's in your ideal Markdown setup?

If you spend time in Markdown vaults and care about staying keyboard-first, I'd love to hear your thoughts:

What shortcuts do you find missing in web-based editors?
How do you handle sync or local file conflicts in your own workflow?

Feel free to check out HermesMarkdown and let me know what you think!