alt Hacker NewsHow is this new? The code is the spec has been a thing for a very long time.
Honestly using markdown is really inefficient. Code is much more expressive and terse. Why do you need all these markdown files when you have code already? I could see markdown if you can’t read code, but otherwise…
Don’t get me wrong docs are useful when code isn’t sufficient (for more esoteric things), but in many cases code is much better.
Replies
i have absurdly lightweight amounts of markdown within my projects that are meant to stay for the long term, a minimal agents.md, which whatever harness im using that day consumes, which maybe has some lines that point at another md file or two or whatever if i deem it vital for rules of a specific section
The real use for markdown for me and why i have a TON of markdown usage, is for planning tasks. these aren't "permanent" or anything but end up in a very much archived section of the repo once concluded but will have commit ids and such attached so intent can be retrieved at a later date if needed, as well as session ids for whatever model/harness i was using for that particular task.
It also serves another purpose of allowing me to nicely chunk up work as i see fit, so if i start a task in CC, and would prefer a section be done with some other model i can easily do so, or if i feel the work is suited to parallel sessions i can spin those up as well, with whatever models/harnesses i want.
Well, you've changed the subject but fine, let's go there.
That's one of the things that has drastically changed, in my opinion. One way to look at it could be: in the past it was okay to have a minimal design spec doc, if your programmer wrote excellent code and comments, and the system wasn't too big.
But now, you can't complete if you try to do it that way while not using AI. You need to take all that effort that used to go into good code and good comments, and put it into a good spec doc, and hand that file to the AI.
So that once the AI has built your system, you can say either "hey AI, a bug just showed up in the widget area, go look at your strange spaghetti code of yours and the design doc and fix it", or, "hey AI, the whole sub-system seems to have gone critical mess, take the code, spec doc, lessons learned, and the following few high-level design decision changes, and re-write the whole thing!"
Apologies for bluntness, but there just isn't going to be much need in this world for people that are excellent at hand-building intricate watches, in a world where $20 quartz-movement watches have appeared.