3 ms·

Why is the vibecoding crowd still holding onto the idea that markdown (or here yml) is a better spec then code? Seriously, it's just not Write your code like

• anonzzzies 6mo ago
  Most 'programmers' cannot read or write code very well (or reason about structure or architecture) and so they want to 'program in english'.
  • yuye 6mo ago
    This has been attempted for as long as programming has existed.
    • anonzzzies 5mo ago
      Sure but now it actually works somewhat.
• deleted 6mo ago
  [deleted]
• zbyforgotp 6mo ago
  The idea is that the spec is somehow compressed in comparison to the code.
• brendanmc6 6mo ago
  I think you are confusing the spec as "this is how it must be built", as opposed to, "this is what the software must do and must not do to be acceptable". To me saying "the code is the spec" is like saying "the business wants it this way because that's how the code is written". Which is obviously backwards. Does the business mandate we use a cache for this hot path? No, but the business set performance targets, and the cache was a sensible way to satisfy them. See the difference? I believe that the 'musts' and 'must nots' deserve special attention, and need to be recorded well before I decide on the 'how'. Every team does this differently. I find that writing itemized, functional acceptance criteria is practical way to marry the two domains. I also think the process matters a lot more now, because the temptation to let an agent ship it is increasing and the tedium of maintaining these specs is decreasing.
  • deleted 6mo ago
    [deleted]
  • kibwen 6mo ago
    > Does the business mandate we use a cache for this hot path? No, but the business set performance targets, and the cache was a sensible way to satisfy them. See the difference? This seems confused. Specs are free to include as much or as little detail as they deem necessary. If a spec only wants to suggest vague performance goals and handwave the details, that's permitted. But if specs want to specify the exact means by which performance will be guaranteed, that's also permitted. And this isn't an anti-pattern, this is often very useful. For example, plenty of APIs in the real world specify algorithmic upper bounds for time and space consumption, which is useful in that they allow downstream consumers to have a greater understanding of what sort of performance their own systems will exhibit despite the API itself being a black box in other respects. So the answer to the original question definitely isn't "no", it's "maybe, depending on the sort of guarantees we want to provide to our users".
    • brendanmc6 6mo ago
      I think we are actually saying the same thing! We could think of situations where the cache would be verboten (sensitive info), or where it would be mandatory, like in your example, or optional like in my example. My aim was to voice disagreement with the "code is spec" crowd, whom I think are using a different (and in my opinion tautological / useless / counterproductive) definition of spec. Probably because they are mad that I use trigger words like Vibe and Maxxing, and they assume I can't even read the code I'm shipping. I digress. In your "time complexity is a downstream requirement" example, which is a great one, I think you would prefer to have well-maintained written documentation of that criterion that lives outside of the procedural code itself, would you not? How much attention that doc gets is a matter of process and preference, but I'm advocating it should get more (spec-first).
      • Yokohiii 6mo ago
        > In your "time complexity is a downstream requirement" example, which is a great one, I think you would prefer to have well-maintained written documentation of that criterion that lives outside of the procedural code itself, would you not? How much attention that doc gets is a matter of process and preference, but I'm advocating it should get more (spec-first). That is a huge mixed bag. It helps to have an high level overview of an algorithm. If you want to be very accurate about an algorithm, then that documentation is potentially harder to digest then the actual code. I personally don't even know how to express an sophisticated algo in natural language without falling back to pseudo code. Then you also have to verify a purely natural language defined algo with a very slow feedback loop (agentic PR cycle) against a test. Which seems to be a guarantee for myself to get sloppy because it's annoying. There are a lot of reasons to theorize about algos in spoken or written natural language. For me it's questionable why you'd prefer the natural language to be the reference implementation when all you want is the code. That only makes sense if you never want to look at code.
• brap 6mo ago
  Software engineering is different from other engineering disciplines in that the most explicit spec of the thing you’re building is the actual thing itself. When you want to build a bridge you finalize all the blueprints and then someone goes and actually pours concrete, in software the blueprint is the code, and the code is also the bridge. However there are different levels of abstraction for writing specs and code is just the most explicit form. With LLMs more of our time can be spent in those higher levels of abstraction and free us from work that is often repetitive and mundane. I think the (distant) future of software engineering is not code writing but mostly requirements writing, and so it makes sense to build frameworks, “IDEs”, etc. around this new form of “programming”. I don’t know if ACAI is the right one but the direction is interesting.
  • oblio 6mo ago
    > When you want to build a bridge you finalize all the blueprints and then someone goes and actually pours concrete Construction has plans "as designed" and "as built".
    • brap 6mo ago
      Fair enough, but “as built” is usually not the original intent
      • oblio 6mo ago
        I'd argue code frequently isn't the original intent, either :-D
• adipose 6mo ago
  i think it's the same reason where if you fail to produce the amazing results a scammer/guru/MLM promised you, they can always respond with: > "we never said this would work for everyone, it depends on the effort you put into it!" it's perfect for extending the lifespan of a scam on someone because yes, obviously it's true that in general you can improve results by working harder, being more disciplined, whatever... same here, functionally. of course there are better and worse ways of writing a spec, a prompt, etc. but i honestly think a lot of the focus on this is a way to divert attention from the overall ceiling of these tools in general. in other words yes, it's not all bullshit, but there's a huge aspect of this "prompt/spec engineering" that in my view is a way to unconsciously buttress the "LLMs are going to 10x our GDP" mindset -- if those high expectations aren't panning out, there's always: > "we never said this would work for everyone, it depends on the effort you put into the spec!"
• rogermarley 6mo ago
  Exactly. There's little gap between a spec that's been written to the level of detail needed and just code. There's some, but it's not a big gap after decades of umpteen new frameworks and languages and new forms of abstraction. The core of the misunderstanding is between new builds and making changes to existing builds (where most software dev work actually happens). Yes, you'll get a great headstart with a detailed spec for a new build. The issue is in the hundreds of changes that'll follow that. Do people think that the desire to make shortcuts and do minimum effort changes is going to stop just because you've got a bit-more-natural-language-looking spec? And then with an AI underneath making probabilistic changes to code that's now basically a compile target - they really think the dev pace isn't going to collapse, but just faster and with a big ongoing inference bill? The LLM's do not form mental models. You are not going to get a better results from an LLM vibe coding against spec diffs vs a dev prompting it from a position of understanding the codebase and the requested change.
• brentcrude 6mo ago
  [dead]
• musebox35 6mo ago
  Not all parts of the code is equal in this respect. Those parts pertaining to the user visible portion (API of a library, command args of a CLI, UI of a GUI/TUI app, endpoints in a web service, etc.) are closely related to the spec. The rest is more fluid as long as it does not change user visible behavior. The choices still affect maintenance and debugging costs, so there is some pressure to not YOLO these portions. I think the most difficult design decisions relate to how to separate the two and how to ensure a smooth evolution of both user facing and programmer facing design decisions. What is different now is that maintainability and debugging design decisions were made w.r.t. human coders or teams in the past which is not necessarily the case anymore. Should we just specify the API and let agents figure the rest or do we still want to control the rest to ensure maintenance and security? A year ago I definitely thought so. Now it is more murky as the agents are faster browsers of codebases and can explore runtime effects faster than I can type and parse output. Strongest empirical observations depend on the runtime behavior so they have an edge there.
• smokel 6mo ago
  No, code is not the same as a specification. There are a lot of accidental implementation details that the customer may not require. By making the code the specification, you end up with those details becoming requirements, and you can then no longer change that implementation. Having functional behavior and implementation details separate can be really useful, even though it is typically a pain to keep them in sync.
  • ffsm8 6mo ago
    Your comment reads like you haven't understood my point. I'm not saying that you can just take any code out there and call it your spec. I even pointed out in my last paragraph that code not written as a spec is garbage for LLM driven development - precisely because you end up with unintended implementation details becoming your spec. There are a lot of ways to address this, but ultimately it is down to how you structure your code, where you place your comments, and what you write into your agents.md in the modules and what kind of QA agents you configure to go through your code before reviewing the code changes/spec adjustments yourself A more heavy handed approach could also be domain driven design, where your domain/core package becomes the spec, and the unspecified parts get extracted to less specified modules with less explicit structuring.
• bdcravens 6mo ago
  It needn't be an either/or. I find writing pseudocode in a structured, but flexible, manner highly effective.
• soma8088 6mo ago
  This may hold true for greenfields, a little harder to do with a million line, 15 year old legacy code base. Good luck with your credits watching your agent churn those those files over and over and over for each request.
  • ffsm8 6mo ago
    And are you seriously suggesting you'll be able to do spec driven development via markdown files in that? If not, then you're missing the point entirely. I very explicitly stated that if your codebase isn't written like a spec you cannot effectively use it for LLM driven development. You can still edit the code via LLM, it's just always going to be a highly involved process with very careful reviews unless you're happy with regressions.
• locknitpicker 6mo ago
  > Why is the vibecoding crowd still holding onto the idea that markdown (or here yml) is a better spec then code? From your comments it sounds like you are oblivious to the whole problem domain. The whole point of these tools and frameworks is to provide a high level description of not only what features are already implemented in a project but also and more importantly what features you want to implement. To put it in simpler terms, the point is to write down high level specs in a way that coding assistants can parse them and implement them. I recommend you research spec-driven development, a whole set of frameworks designed to put together specs in a way coding agents can roll out plans to implement features in one-shot or few-shot prompts. You know, what specs are used for.
  • ffsm8 6mo ago
    Oh I've researched it and did two projects entirely like that, both scaled to 150k loc and I believe 90k loc last summer to fall. That approach just doesn't scale unless you don't care about your product whatsoever, hence my comment I've successfully been working on various personal projects with highly stable functionality since I stopped that approach and instead focused more into leveraging my codebase to become the spec. Very low maintenance and great to add features after the initial hurdle of structuring your codebase that it's less about implementation detail and more about spec. So a lot less "smart" code and less highly advanced abstraction, and a lot more declaratively structured - boring and potentially repetitive, but easier to place good AGENTS.md and doctexts on areas which have requirements which may be unclear just from looking at the code for example. Then running multiple "QA" agents over the diff before you look at it yourself for the final review So yeah, sorry but your imagination is running wild
    • brendanmc6 6mo ago
      [dead]
    • yaubi 6mo ago
      Could you please expand on the practical ways you leveraged your codebase to become the spec? Very interested in this topic.
• raincole 6mo ago
  Before AI era, specs meant documentations. The specs of jpeg, png, h.264, docx, usbc or whatever format you can think of, are not just a bunch of C++ source files. Compilable source files served as example implementations, complementary to the specs themselves. The idea that code is spec is just agile brainrot, like the idea that clean code means you never need to write documents or comments.
  • raincole 6mo ago
    Edit: it's very interesting that all the other engineering principles know the difference between spec and implementation, except in software engineering the idea that all you need is code got reinvented every few years. Every generation thinks they're the special one, I guess.
• alasano 6mo ago
  Because I don't trust LLMs to fully implement what I want on the first try unless I babysit them. And it's the hand holding that burns people out. I use detailed specs to implement but I don't maintain those specs as the source of truth afterwards, the code is indeed the source of truth. I've built a library (and products on top) that takes in requirements (programmatic or various spec formats) and forces an externally orchestrated implement -> review -> fix loop that doesn't stop until all requirements are met. So I'll write a detailed spec then I'll have GPT 5.5 implementing and a mix of opus 4.7 / GPT 5.5 / DeepSeek v4 pro reviewing at every phase until it produces the quality I want. I can let it run overnight or just during the day while I'm doing stuff that doesn't burn me out and that I actually enjoy. So tldr spec first for me but not as the source of truth afterwards. I'll be open sourcing and launching soon https://engine.build https://engine.build