alt Hacker News> "...or the parts that have never once executed in production because they’re there for a worst case someone sat down and imagined."
Good stuff.
> "It’s the record of what the code was supposed to do ... written down somewhere a human or an agent can read them back. Ours are markdown files in git..."
I keep getting surprised how many quite technical people I know are doing real work with AI but have never touched markdown.
If you are one of those people, allow me to offer a suggestion:
Stop. No more sending questions to ChatGPT or Claude until you do the following:
- Install Typora on your Windows or Mac machine.
- Write a .md (markdown text) file a full page long using Typora (or another editor that understands markdown, but Typora will do just fine). Make use of Heading 1, Heading 2, and underline formatting, at least.
- Make the one page file be a complex request to an AI. Something like "research x, compare it to y, make a guess what will happen in the future, here are some of my opinions and guesses, make your replies short, provide references".
Hand that .md file to your favorite AI. (Bonus points for using drag and drop or pointing the AI at the dir the file is in.) Look at your results. Make a change to your .md file. Hand it to the AI again, see the different results.
In my opinion, if you work on a keyboard and you've been making use of AI for the last 8 months, you should have done the above 4 months ago. Until you do, you will have a hard time understanding how drastically AI has changed almost all developer's lives, and how it is changing more and more fields that are not software development.
Replies
How 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.
Or at least have your LLM generate a context .MD file for you.
> Install Typora on your Windows or Mac machine. - Write a .md (markdown text) file a full page long using Typora (or another editor that understands markdown, but Typora will do just fine). Make use of Heading 1, Heading 2, and underline formatting, at least.
Who's still typing?
> I keep getting surprised how many quite technical people I know ... > > - Install Typora on your Windows or Mac machine.
I keep getting surprised how many people don't realize Linux is a thing.
Every time I see a comment like this I feel like you are only 50% into the transition that is occurring.
The crafting of the requirements is better suited to an interactive process. You will have superior results and a quicker turn around by having the AI research the change implications, what current implementations actually do and where (so you can look at the parts you want to), etc.
When working in a BIG codebase, having it detail up a flow of how all the parts fit together is great and helps get you setup to work. Then work through your planned constraints with the AI and make sure the perception matches your intent (with prevents a lot of issues that a fire and forget document creates).
Then when you are satisfied that it sees the problem as you do, have the model capture it and then let it rip.