[aiibe]

Writing and updating CLAUDE.md or AGENTS.md feels like pointless to me. Humans are the real audience for documentation. The code changes too fast, and LLMs are stateless anyway. What’s been working is just letting the LLM explore the relevant part of the code to acquire the context, defining the problem or feature, and asking for a couple of ways to tackle it. All in a one short prompt. That usually gets me solid options to pick and build it out. And always do, one session for one problem. This is my lazy approach to getting useful help from an LLM.

[aqme28]

This is true but sometimes your codebase has unique quirks that you get tired of repeating. "No, Claude, we do it this other way here. Every time."

[aiibe]

Quirks are pretty much unavoidable. I tend to get better results using Codex. It sticks to established patterns. Slow, but more deliberate. Claude focuses more on speed.

[samuelknight]

I use .md to tell the model about my development workflow. Along the lines of "here's how you lint", "do this to re-generate the API", "this is how you run unit tests", "The sister repositories are cloned here and this is what they are for".

One may argue that these should go in a README.md, but these markdowns are meant to be more streamlined for context, and it's not appropriate to put a one-liner in the imperative tone to fix model behavior in a top-level file like the README.md

[aiibe]

That kind of repetitive process belongs in a script, rather than baked into markdown prompts. Claude has custom hooks for that.

[arnorhs]

I agree with you, however your approach results in much longer LLM development runs, increased token usage and a whole lot of repetitive iterations.

[aiibe]

I’m definitely interested in reducing token usage techniques. But with one session one problem I’ve never hit a context limit yet, especially when the problem is small and clearly defined using divide-and-conquer. Also, agentic models are improving at tool use and should require fewer tokens. I’ll take as many iterations as needed to ensure the code is correct.

[dncornholio]

Because it's stateless it's not pointless? Good codebases don't change fast. Stuff gets added but for the most stuff, they shouldn't change.

[aiibe]

A well-documented codebase lets both developers and agentic models locate relevant code easily. If you treat the model like a teammate, extra docs for LLMs are unnecessary. IMHO. In frontend work, code moves quickly.

[xpe]

> Humans are the real audience for documentation.

Seeing "real" is a warning flag here that either-or thinking is in play.

Putting aside hopes and norms, we live in a world now where multiple kinds of agents (human and non-human) are contributing to codebases. They do not contribute equally; they work according to different mechanisms, with different strengths and weaknesses, with different economic and cultural costs.

Recall a lesson from Ralph Waldo Emerson: "a foolish consistency is the hobgoblin of little minds" [1]. Don't cling to the past; pay attention to the now, and do what works. Another way of seeing it: don't force a false equivalence between things that warrant different treatment.

If you find yourself thinking thoughts that do more harm than good (e.g. muddle rather than clarify), attempt to reframe them to better make sense of reality (which has texture and complexity).

Here's my reframing: "Documentation serves different purposes to different agents across different contexts. So plan and execute accordingly."

[1]: https://en.wikipedia.org/wiki/Wikipedia:Emerson_and_Wilde_on...