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.

> 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

This is inefficient. If quality matters at all, you’re going to miss things in your English design doc and/or use 100 words where 1 line of code will do.

If quality (as in product, not code) doesn’t matter then sure, do whatever. LLM will fill in the gaps.

> world where $20 quartz-movement watches have appeared

Much like in real life, if you’re paying for a cheap knock off you get what you pay for. Also much like real life, plenty of people will pay for $20 knock offs and be content.

I keep meeting ex software developers that changed careers to watchmaking by the way. Clockmakers that survived the quartzopocalypse have more work than they can handle, 6 month to 1 year turn around times.

Check out Hodinkee and Monochrome Watches to see all the hand built watches announced everyday. $100,000 and up. People appreciate craft, beauty, tradition, and are willing to pay.

He's saying that as a language of prompting, English won't scale properly, and that a well scaffolded codebase is also part of the prompt.

I think it makes sense. You're in a company full of many teams and people are building things, some manual, some autogenerated, some hybrid. When you notice that people are rebuilding many of the same things, of course you're not going to keep using LLMs to regenerate the basics of the universe. So you pick the very best and use that as the starting point, not tabula rasa markdown file.

>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",

Your AI fix it, and you take it your users. Users come back with a new bug. You ask your AI about it. AI says, "Sure, I didn't handle it because you didn't say so!"

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.

Yeah, this is where I’ve landed after trying to painfully construct a markdown plan and hope it’d be implemented to spec the first time through. I’d review, find mistakes, get annoyed and then realize it was simpler to just build iteratively. And just have it give me code when possible, since that cut through the middleman, so to speak.

I’ll get a rough markdown plan to start but don’t treat it as much more than a launch point.

> I’ll get a rough markdown plan to start but don’t treat it as much more than a launch point.

If i am more entrenched in the codebase, i find that to be the case as well. the full on markdown plan structure is more for just trying to keep the more vibey projects in check.

  > "The code is the spec has been a thing for a very long time"

The code is the "what" and the "how", but not the "why".

To manage change, you need the "why" – Chesterton's fence being the classic example.