Nice post, Shrivu! I learned a few new things, but I am not sure I agree all of them. Happy to be the first committer. I’ll just respond in the order you laid things out
1. “AI Cannot Read Your Docs” — catchy title, but not fully true. AI can read docs if you wire it up right: Context7 MCP, llmstxt, or even just letting an LLM search or fetch content. The bigger point, which I agree with, is that we should think about redesigning the software itself
2. Showing CLI output with object details and next steps is super useful. Not just for AI but for beginners trying to understand what’s happening or track the execution history
3. Error messages should always explain what went wrong and how to fix it, not just say “something went wrong”
4. With AI agents, good code comments are critical. The harder part is keeping them fresh when you refactor or redesign. Some people even go all the way, treating prompts as the only real “source” and having LLMs generate the actual Java/C/TypeScript code
5. CLI really is a great interface. That’s basically why Claude Code exists as a terminal tool instead of a web UI or IDE plugin. Even macOS apps are increasingly scriptable — maybe that’s a growing trend
6. Building interfaces that feel familiar, like pytest or pandas, helps adoption. Reinventing syntax for no reason is usually a barrier
7. Not sure about organizing code strictly by feature. In practice, backends might be Java/Go/Rust, frontends TypeScript, middleware in Go. You wouldn’t put those in the same folder like “addEmail.” Maybe with LLM coding, microservices could make more sense to have feature-oriented structure but today it feels messy
Overall, great post and worth a wide read. Would you be ok if I put together some visuals or infographics to share it further?
(1) Have to have catchy titles nowadays (: but I do mean it in the sense that sure you can wire up various retrieval systems or even use 1M context models but this in reality is far from what you'd expect of a human eng how has "read" the docs and accurately applies them. To say AI truly read docs it's not just context, but also instruction following.
(7) Totally agree and it does depend for different stacks where the optional path lies. It could be as simple as naming (parallel folder structured for features in different parent folders) or picking the same language for FE+BE (e.g. part of why Next.js can be very AI friendly as a full-stack library).
Feel free to share as long as we are linking back somewhere to this one!
Nice post, Shrivu! I learned a few new things, but I am not sure I agree all of them. Happy to be the first committer. I’ll just respond in the order you laid things out
1. “AI Cannot Read Your Docs” — catchy title, but not fully true. AI can read docs if you wire it up right: Context7 MCP, llmstxt, or even just letting an LLM search or fetch content. The bigger point, which I agree with, is that we should think about redesigning the software itself
2. Showing CLI output with object details and next steps is super useful. Not just for AI but for beginners trying to understand what’s happening or track the execution history
3. Error messages should always explain what went wrong and how to fix it, not just say “something went wrong”
4. With AI agents, good code comments are critical. The harder part is keeping them fresh when you refactor or redesign. Some people even go all the way, treating prompts as the only real “source” and having LLMs generate the actual Java/C/TypeScript code
5. CLI really is a great interface. That’s basically why Claude Code exists as a terminal tool instead of a web UI or IDE plugin. Even macOS apps are increasingly scriptable — maybe that’s a growing trend
6. Building interfaces that feel familiar, like pytest or pandas, helps adoption. Reinventing syntax for no reason is usually a barrier
7. Not sure about organizing code strictly by feature. In practice, backends might be Java/Go/Rust, frontends TypeScript, middleware in Go. You wouldn’t put those in the same folder like “addEmail.” Maybe with LLM coding, microservices could make more sense to have feature-oriented structure but today it feels messy
Overall, great post and worth a wide read. Would you be ok if I put together some visuals or infographics to share it further?
Thanks!
(1) Have to have catchy titles nowadays (: but I do mean it in the sense that sure you can wire up various retrieval systems or even use 1M context models but this in reality is far from what you'd expect of a human eng how has "read" the docs and accurately applies them. To say AI truly read docs it's not just context, but also instruction following.
(7) Totally agree and it does depend for different stacks where the optional path lies. It could be as simple as naming (parallel folder structured for features in different parent folders) or picking the same language for FE+BE (e.g. part of why Next.js can be very AI friendly as a full-stack library).
Feel free to share as long as we are linking back somewhere to this one!