It's been pretty great for ramping up into codebases too. "Give me a summary of project in current checkout in markdown form."

It lets you understand the code base at reduced granularity when you want. Or zoom in beyond the written lines to explain _why_ some code is the way it is.

    # Comments

    Keep existing comments unless they're wrong
    or stale. Err slightly toward adding short
    explanatory comments for non-obvious code.

I like to constrain it as much as possible to ignore variables and function names; the human stuff.

With a new code base my first goal understand how it CRUDs state. What structures and what operations?

Less concerned at the outset if its sorting carrots or processing orders for shirts.

AI seems to work way better for me when I tell it to ignore the use case and focus on surfacing runtime and mathematical operations embedded in the code.

Constraints on new abstraction and telling it to stick to math terms and types and objects also seems to help avoid hallucinations and layers of useless indirection.

The "It’s harder to read code than to write it." was always silly. the example spolsky gives to support it is basically "devs like to rewrite other devs code, therefore reading is hard" which is obviously bunch of nonsense. Now that you can recruit LLM to explain any complicated codebase to you it's even less true.

Isn't one of the common criticisms of AI code that it's a bit too keen to write extensive comments - even when they probably aren't needed?

The AI can't really describe its reasoning, though. It can only look at its context history and find a justification (which it will then present as reasoning). In my experience asking the model "why did you do that" carries substantial hallucination risk.

Perfectly possible IME, it just requires more time. Even if you understand all the (important) parts of your code and validate it, Ai still helps with productivity a lot. It's just not as fast as blindly vibe coding - not at first at least. Agents on their own without checks, and superficial prompts without understanding, result in agents either introducing bugs, or if you have an appropriate test harness, painfully slow, in my experience. It requires skill to use an agent effectively.

I think the issue that majority of agentic developers don't understand their design fully. Those holes, perviously, were have to be closed by a person eventually, and inherently you gain understanding in the process.

This is not the case eny more. I never thought LLMs write bad solutions, but when you let it think for you you loose something important, understanding. And when something brekas, some people consider this being a proof that the llm is the problem. And in a sense it is. But you are also to blame. And that's exactly the issue with this all industry - in order to move faster you don't need to "type" faster. A person bashing his hands on the keyboard randomly at top velocity can get pretty high wpm. In order to move master you need to _think_ faster, be _snappier_ and _sharper_ and most people aren't.

I like how one of my colleagues phrased it in a company meeting. He asked one of the c levels "for llm s to 10x me, I need to let them make all decitions and dictate intentions. By percentage, how much of the code you want me to _know_?"

By default, Claude is set to avoid comments. Eventually I got tired of it deleting my own explanatory comments and overrode the behavior with an addition to CLAUDE.md.

I think Claude is just behaving like all those programmers who make a VERY BIG DEAL about how much they HATE HATE HATE comments that might reiterate what the code does so will go to extreme measures to avoid them.

Very few developers do that especially on early / key parts of the codebase.

Isn't this what good commit messages are intended to address? If a person has gone so far as to allow an agent to write all their code, they're likely having it commit on their behalf too.

Writing a skill / set of rules around what makes a good commit message would encourage the LLM to record it's reasoning (however much we truly consider it to be "reasoning").

Have you tried the "use red/green TDD" trick?

I believe that increases the chances of one-shot code working, though it's also possible that it did that against Opus 4.5 and isn't necessary against Opus 4.7 but I haven't spotted the difference yet.

Personally, guiding junior teammates down the path away from purely "Writer of Code" to "Implementer of Functionality" has been working well for me.

If you get them involved in the design process, they feel heard. Feeling heard is one surefire way to have a person feel involved. Feeling involved fosters a sense of ownership and pride which in turn helps keep a person engaged.

More AI is always the answer.

Self generating docs based on docstring comments are great. LLMs are capable of generating architectural overview docs from these. What more do you need?

i disagree and even if assisted the points are still valid

Maybe it's just because I grew up spending way too much time on the internet, but I write like that and have since well before LLMs. As much as people like to attribute that style to AI, I don't think it's the dead giveaway that people act like it is.

Like clockwork, every single thread about something AI-related has someone expressing their disgust at passages of LLM-written text. In many cases by the same people who are enthusiastically embracing LLM-generated software. Why don't we show the same level of contempt for LLM-authored software as we do for even the slightest hint of LLM-authored text in a blog post?

The link in the article that is right near the words you're talking about links to a wikipedia page that says the book is from 2005. So I conclude it was 2005 or soon after

To me, design files living in the repo are what captures these high and low level decisions. They should express intent which is paramount for automation.

Where are you keeping your design? If it's a WYSIWYG doc like word, what would it take for you to switch to a more text driven world?

The structure https://acai.sh/ uses feels to me like a decent starting point for this kind of thing that avoids the "single giant file" issue.