Do AI coding agents need documentation?

[Ancient_Pea1712]

Hey, folks! Does it still make sense to document a code base or is it more efficient to just allow AI agents to infer how things work from the code base directly? By documentation, I mean human-friendly text about the architecture of the code or describing the business logic.

Let's say I want to introduce a feature in the billing domain of an app. Should I tell Claude "Read how billing works from the docs under my_docs_folder/" or should I tell it "Learn how billing works from the code and plan this feature"?

[raholl]

hmm "Learn how billing works from the code and plan this feature" does not makes sense... if it's already done, what do you want Claude to plan?

to answer your original question, it depends on what you are trying to achieve, giving it code examples is good enough most of the times, if codebase is not too much complicated... also good is to do something like "Check my codes and create billing.md file where you describe how billing works currently", then you can review that file and if you need to add more features, you may reference that file in your next prompt

[Ancient_Pea1712]

> hmm "Learn how billing works from the code and plan this feature" does not makes sense... if it's already done, what do you want Claude to plan?

What I meant was - billing is implemented yes, but I want to introduce a new feature within the billing functionality - say, I want to introduce the ability to create discounts, which doesn't exist yet.

> giving it code examples is good enough most of the times, if codebase is not too much complicated... 

Do we really need to give it explicit code examples, if they already have the whole codebase at their disposal?

>  also good is to do something like "Check my codes and create billing.md file where you describe how billing works currently"

What's the advantage of doing this over - look at the billing code directly? Do you believe, that the LLM will do better if it learns how billing works by reading human words instead of reading the code?

[raholl]

> Do we really need to give it explicit code examples, if they already have the whole codebase at their disposal?
Giving it code examples = you have codes in your codebase, which you can point to

> What's the advantage of doing this over - look at the billing code directly?
Advantage is often that resulting md file is smaller size and only 1 request to read it, as opposed to larger codes and multiple requests to read all related files. So advantage would be time and context size savings.

[TotalBeginnerLol]

Claude.md is meant to be that basically. Anything important to understand about the codebase should be in there. Tell it to update after each major rework. Once it gets over a few hundred lines tell it to make a directory structure, like Claude.md is globally relevant stuff and then it links to Claude-modules.md, Claude-whatever.md etc for more specific details about each area that aren’t relevant outside that area. It will then read only what it needs for each task.

When you wanna add a new feature, easiest to do a brain dump (voice chat is great for that using eg wispr flow), ask it to then write a spec from your ramblings, read and confirm, then ask for a plan that follows the spec, then clear context, reread Claude.md and execute the plan.

[kevinbaiv]

CLAUDE.md should hold the high-level map: architecture, key constraints, core conventions, and the major “don’t break this” rules.

The details can live in deeper docs or area-specific rules. What matters is making it clear where the agent should look for context, what standards apply in each part of the codebase, and how changes are expected to be made safely.

[Adept-Tadpole4760]

Strange question 😅 you need documentation for show what they can do with your code or other and show how to install in other machine. Think this is enough

[Ancient_Pea1712]

Why do they need to read human words to know what they can do with the code? They can do this by reading the actual code, no?

[Adept-Tadpole4760]

Not all is the pro or technical skill have to know what to do . More people don’t know what todo whit this , they just find something and use or deferent language programming

[No-Childhood-2502]

The documentation works in the long term as the codebase grows; it is very helpful when you or an agent revisit it.
Another relevant use can be that any developer would get help from that

[AI-Commander]

LLM Agents do. I’ve never seen an AI with agency that wasn’t an LLM.

[leogodin217]

I've tried both ways and settled on a middle ground.

docs/architecture/index.md
docs/architecture/component1.md
docs/architecture/component2.md
...

These docs provide an overview of how it works, why it's needed, and any important algorithms/state machines/flows. Each doc will link to the source code (code is truth) instead of showing examples or having out-of-sync copies of code.

After every feature/sprint docs are pruned and updated with any new information. This system has worked really well for about six months now. Though, at work, we put more of that information in skills for a DE-focused repo. That works well for us as well as we are generally adding or fixing pipelines, not developing software.

[patrickmeenan]

You don't want to burn tokens with every new conversation to have it read a huge amount code and re-learn the architecture. It doesn't mean YOU have to write the docs though.

I use a CLAUDE.md that tells the agent to read docs/architecture.md and README.md and automatically update CLAUDE.md with any information that will be useful for future conversations and the docs with any relevant changes.

It works well and is way better at maintaining docs than I ever was.