Interesting article, and I generally agree! And I'm just thrilled it's being discussed at all, as a MyST superfan. That said, a few quibbles I'd be curious to hear thoughts on:
First, none of this changes the need for a separate `/docs` dir, also checked into git. Wikis are fun, but docs are essential!
Second, I personally think the new paradigm will be putting all of this into tons of new README.md files, which I'm kinda baffled aren't more common deep into dir hierarchies already. That intuitively tells the human authors and the artificial readers that;
A) it toes a similar "for technical people but not necessarily just our dedicated engineering team" line as the root README --more formal than an ephemeral "prompt" and less formal than a user-facing doc,
B) this isn't the AGENT.md file so should remain human-authored only,
C) this is only an overview with a strong preference for brevity & clarity, and
D) this is focused on this specific directory (along w/ the other benefits of locality, as the author extolls already).
Have I cracked the code? Is there a Turing award for inventing the concept of using a tool we already use but just a bit more extensively -- or at least a YC slot?
bbor · · focus · HN ↗
First, none of this changes the need for a separate `/docs` dir, also checked into git. Wikis are fun, but docs are essential!
Second, I personally think the new paradigm will be putting all of this into tons of new README.md files, which I'm kinda baffled aren't more common deep into dir hierarchies already. That intuitively tells the human authors and the artificial readers that;
A) it toes a similar "for technical people but not necessarily just our dedicated engineering team" line as the root README --more formal than an ephemeral "prompt" and less formal than a user-facing doc,
B) this isn't the AGENT.md file so should remain human-authored only,
C) this is only an overview with a strong preference for brevity & clarity, and
D) this is focused on this specific directory (along w/ the other benefits of locality, as the author extolls already).
Have I cracked the code? Is there a Turing award for inventing the concept of using a tool we already use but just a bit more extensively -- or at least a YC slot?
*P.S.* OP you dropped this: )