标签：#darkfactory

Everyone's writing specs for AI now. We hand the model a markdown file, tell it what we want, and hope it builds the right thing. It mostly works — until it doesn't. Markdown has quietly become the spec language. People reach for it as the DSL for their AI-driven workflows — headings, bullet lists, the odd table — and treat that loose structure as if it were a contract. The thing is, it isn't a DSL. It's markdown. It's prose formatting with no grammar to enforce, no structure you can execute, no shared vocabulary, and no way to tell whether the spec and the code still agree. You're leaning on a document format to do a job it was never built for, and you hit the limit the moment you want the spec to actually mean something a machine can check. Before you go down that road, I want to make a small, slightly absurd suggestion. Eat a cucumber. What I actually mean Gherkin is the plain-text language behind Cucumber , a tool that's been around for years in the behavior-driven development (BDD) world. It looks like this: Feature : User login Scenario : Successful login with valid credentials Given a registered user "ada@example.com" When she logs in with the correct password Then she should land on her dashboard And she should see a welcome message Scenario : Rejected login with wrong password Given a registered user "ada@example.com" When she logs in with an incorrect password Then she should see an "invalid credentials" error And she should remain on the login page That's it. Feature , Scenario , Given / When / Then . Structured enough that a machine can parse it, loose enough that a product manager can write it. The gap it bridges Most specs live at one of two extremes. On one end you have written specs : docs, tickets, markdown files. Readable by anyone, but inert. Nothing checks whether they're still true. They rot the moment the code moves on. On the other end you have tests : precise, executable, always honest — but written in code, illegible to half the people who a