I've been going back and forth on the same problem for months: how to manage the context rules you give AI coding tools. If you use Claude Code, you write a CLAUDE.md. If you use Cursor, a .cursor/rules. If you use Gemini CLI, a GEMINI.md. If you use all three — like I do — you have the same content in three different places, with three slightly different formats, and the certainty that at some point they'll get out of sync.
The problem is real. The solution took me longer to find than it should have.
Two projects, zero products
For weeks I was working on two things in parallel:
DevContext AI was a webapp. It had an MCP server, rule versioning, a Supabase database, auth, Vercel deploy. It was functional. It was deployed. It had an MVP. And nobody used it, starting with me, because it was too much for what I actually needed.
dev-workflows was a CLI. The idea was simpler: define rules in YAML, compile for each editor. But it only existed as documentation. Folders of docs, specs, architecture diagrams, documented decisions. Zero code.
One project with too much code and no focus. Another with too many documents and nothing executable. Both solving exactly the same thing.
Documentation paralysis
I have to be honest about something: I got stuck documenting. I had a VISION_GENERAL.md, an ARCHITECTURE.md, a ROADMAP.md, a DECISIONS.md, and a CLI_SPEC.md. Five documents for a CLI that didn't exist.
The documentation felt productive. I was "making progress." But I was really just putting off the moment of writing the first line of code. It's a trap I think more of us fall into than we'd like to admit.
The clarity came when I realized that if I couldn't explain what I was building in a paragraph, the problem wasn't lack of documentation — it was lack of clarity.
The merge
I decided to keep one. The CLI won for several reasons:
- The underlying problem (duplicated rules across editors) is structural. It's not going away soon — each editor uses its own format.
- A webapp competes with native editor features. A CLI complements them.
- Validating a CLI is immediate: if it works on your project, it works. A webapp needs users, onboarding, retention.
The webapp doesn't get thrown away. The infrastructure (MCP, Supabase, versioning) becomes the future Pro tier. But that doesn't matter now. What matters now is having something that works and that someone can install.
I cut the five documents down to two: CLI_SPEC.md (the implementation contract) and DECISIONS.md (decision log). Everything else got deleted.
One day with Claude Code
This is where it gets interesting. With a clear spec, I handed the document to Claude Code and started building.
Sprint 1 — Core (morning)
I told it to scaffold the CLI: package.json, tsconfig, commander with commands registered as stubs. Done in minutes. Then the logic for devw init — tool detection, interactive prompts, .dwf/ structure generation. Worked on the first try.
Then devw compile — the heart of the product. A parser that reads the YAML files, three bridges (Claude, Cursor, Gemini) that translate to native format. Each bridge is one file. And devw doctor to validate everything is in order.
Sprint 2 — Blocks (noon)
Pre-baked block system: devw add typescript-strict installs strict TypeScript rules into your YAML files. Registry, installer, 6 content blocks, add/remove/list commands. 17 tests.
Sprint 3 — Ship (afternoon)
README, npm config, CI with GitHub Actions, changesets for automated releases. And the dogfooding: using dev-workflows on the dev-workflows repo itself.
The dogfooding was the most valuable part. I found three bugs the tests didn't catch:
devw compilewas overwriting the entireCLAUDE.md— if you had manual content, you'd lose it. Fix:<!-- BEGIN/END dev-workflows -->markers that delimit the generated section.devw initwas adding all of.dwf/to.gitignore— but.dwf/contains your source rules, which you do want to version. Only.dwf/.cache/should be ignored.Invalid input in prompts crashed the CLI with a stack trace — instead of showing a friendly error and asking again.
Three bugs I found in 5 minutes of real usage. Three bugs that wouldn't have surfaced without using the product myself.
The result
By the end of the day I had a CLI published on npm with:
- 6 commands:
init,compile,doctor,add,remove,list - 3 bridges: Claude Code, Cursor, Gemini CLI
- 6 pre-baked rule blocks (TypeScript, React, Next.js, Tailwind, testing, Supabase)
- 54+ tests passing
- Automated CI with GitHub Actions
- Automated releases with changesets
npx dev-workflows init # creates .dwf/ with config and empty rule files
npx dev-workflows add typescript-strict # installs a rule block
npx dev-workflows compile # generates CLAUDE.md, .cursor/rules, GEMINI.md
Define rules once in YAML, compile for each editor. Change a rule, recompile. Something's off, doctor tells you.
What I learned
Documentation before code is procrastination disguised as productivity. A concise spec is necessary. Five documents with vision, architecture, and a roadmap for something that doesn't exist yet is creative resistance.
A good spec is enough for AI to implement. I gave Claude Code the CLI_SPEC.md and it generated correct code on the first try in almost every case. The key isn't writing more documentation — it's writing the right documentation.
Dogfooding finds what tests don't. Tests verify what you thought could break. Using your own product reveals what you never even considered.
Ship first, polish later. The CLI has hardcoded values, the prompts could be better, and the block system is basic. None of that matters if nobody uses it. Publishing is the fastest way to find out if the product makes sense.
Current status and what's next
dev-workflows is at v0.1 — functional and I use it on my own projects, but it's an early version.
What's on my radar:
- More bridges — Windsurf, Copilot, and other editors adopting context files
- Remote block registry — so the community can contribute their own
-
Watch mode — auto-recompile on
.dwf/changes - Custom scopes — categories beyond the 5 built-in ones
- Pro webapp — visual interface for teams, with versioning and sync
If you use multiple AI coding tools and you're tired of keeping duplicate rules across them, give it a try:
npx dev-workflows init
- npm: npmjs.com/package/dev-workflows
- GitHub: github.com/gpolanco/dev-workflows
- License: MIT
If you find bugs or have ideas, open an issue. I'm building this in the open.
Requires Node.js >= 22.
Top comments (3)
This hits way too close to home. I think we’ve all been in that "documentation paralysis" loop where writing another ARCHITECTURE.md feels like work, but it’s actually just sophisticated procrastination.
The move to pivot from a full-blown SaaS/webapp back to a lean CLI is a masterclass in pragmatic engineering. We’re currently in this "Wild West" phase of AI coding where every tool (Cursor, Claude, Gemini) is trying to stake its claim with a different config file, and having a "Single Source of Truth" via YAML is the only way to stay sane. It’s the docker-compose moment for AI rules.
Also, that bit about the `` markers? Pure gold. That’s the kind of "battle-scar" feature you only find when you actually sit down and dogfood your own tool for five minutes.
It’s wild that with a solid spec and the right AI orchestration, you turned months of "thinking" into a published NPM package in 24 hours. Definitely going to give npx dev-workflows a spin—my .cursorrules and CLAUDE.md have been drifting apart for weeks and it’s been driving me crazy.
Yeah, that docker-compose for AI rules line is painfully accurate. Stealing it.
The documentation paralysis bit resonated too, at some point you realize you’re writing ARCHITECTURE.md for tools that don’t even read the same file, and something’s clearly broken.
And yep, the markers thing was pure dogfooding pain. Tests all green, first real compile wiped some hand-written CLAUDE.md notes. Lesson learned fast.
If you end up trying it, I’m genuinely curious how it behaves with your .cursorrules drift. That exact frustration is what pushed me to build this.
dev-workflows.com
The documentation paralysis section hit close to home. I have a whole folder of planning docs for projects that never shipped.
The YAML-to-native-format approach is smart. I've been maintaining separate .cursorrules files per project and the drift between them is real. Having a single source of truth that compiles to each editor's format would save a lot of copy-paste.
Curious about the block system - do you see people contributing community blocks, or is it more of a personal/team thing?