4 ms·

There is far much easier way to do this and one that is perfectly aligned with how these tools work. It is called documenting your code! Just write what this

by _pdp_ 11mo ago

There is far much easier way to do this and one that is perfectly aligned with how these tools work. It is called documenting your code! Just write what this file is supposed to do in a clear concise way. It acts as a prompt, it provides much needed context specific to the file and it is used only when necessary. Another tip is to add README.md files where possible and where it helps. What is this folder for? Nobody knows! Write a README.md file. It is not a rocket science. What people often forget about LLMs is that they are largely trained on public information which means that nothing new needs to be invented. You don't have to "prompt it just the right way". What you have to do is to use the same old good best practices.

dhorthy 11mo ago
For the record I do think the AI community tries to unnecessarily reinvent the wheel on crap all the time. sure, readme.md is a great place to put content. But there's things I'd put in a readme that I'd never put in a claude.md if we want to squeeze the most out of these models. Further, claude/agents.md have special quality-of-life mechanics with the coding agent harnesses like e.g. `injecting this file into the context window whenever an agent touches this directory, no matter whether the model wants to read it or not` > What people often forget about LLMs is that they are largely trained on public information which means that nothing new needs to be invented. I don't think this is relevant at all - when you're working with coding agents, the more you can finesse and manage every token that goes into your model and how its presented, the better results you can get. And the public data that goes into the models is near useless if you're working in a complex codebase, compared to the results you can get if you invest time into how context is collected and presented to your agent.
- theshrike79 11mo ago
  > For the record I do think the AI community tries to unnecessarily reinvent the wheel on crap all the time. On Reddit's LLM subreddits people are rediscovering the very basics of software project management as some massive insights daily or very least weekly. Who would've guessed that proper planning, accessible and up to documentation and splitting tasks into manageable testable chunks produces good code? Amazing! Then they write a massive blog post or even some MCP mostrosity for it and post it everywhere as a new discovery =)
  - dkubb 11mo ago
    I can totally understand where you are coming from with this comment. It does feel a bit frustrating that people are rediscovering things that were written in books 30/40/50 years ago. However, I think this is awesome for the industry. People are rediscovering basic things, but if they didn't know about the existing literature this is a perfect opportunity to refer them to it. And if they were aware, but maybe not practicing it, this is a great time for the ideas to be reinforced. A lot of people, myself included, never really understand which practices are important or not until we were forced to work on a system that was most definitely not written with any good practices in mind. My current view of agentic coding is that it's forcing an entire generation of devs to learn software project management or drowning under the mountain of debt an LLM can produce. Previously it took much longer to feel the weight of bad decisions in a project but an LLM allows you to speed-run this process in a few weeks or months.
bastawhiz 11mo ago
This is missing the point. If I want to instruct Claude to never write a database query that doesn't hit a preexisting index, where exactly am I supposed to document that? You can either choose: 1. A centralized location, like a README (congrats, you've just invented CLAUDE.md) 2. You add a docs folder (congrats, you've just done exactly what the author suggests under Progressive Disclosure) Moreover, you can't just do it all in a README, for the exact reasons that the author lays out under "CLAUDE.md file length & applicability". CLAUDE.md simply isn't about telling Claude what all the parts of your code are and how they work. You're right, that's what documenting your code is for. But even if you have READMEs everywhere, Claude has no idea where to put code when it starts a new task. If it has to read all your documentation every time it starts a new task, you're needlessly burning tokens. The whole point is to give Claude important information up front so it doesn't have to read all your docs and fill up its context window searching for the right information on every task. Think of it this way: incredibly well documented code has everything a new engineer needs to get started on a task, yes. But this engineer has amnesia and forgets everything it's learned after every task. Do you want them to have to reonboard from scratch every time? No! You structure your docs in a way so they don't have to start from scratch every time. This is an accommodation: humans don't need this, for the most part, because we don't reonboard to the same codebase over and over. And so yes, you do need to go above and beyond the "same old good best practices".
- _pdp_ 11mo ago
  You put a warning where it is most likely to be seen by a human coder. Besides, no amount of prompting will prevent this situation. If it is a concern then you put a linter or unit tests to prevent it altogether, or make a wrapper around the tricky function with some warning in its doc strings. I don't see how this is any different from how you typically approach making your code more resilient to accidental mistakes.
  - mvkel 11mo ago
    Documenting for AI exactly like you would document for a human is ignoring how these tools work
johnfn 11mo ago
So how exactly does one "write what this file is supposed to do in a clear concise way" in a way that is quickly comprehensible to AI? The gist of the article is that when your audience changes from "human" to "AI" the manner in which you write documentation changes. The article is fairly high quality, and presents excellent evidence that simply "documenting your code" won't get you as far as the guidelines it provides. Your comment comes off as if you're dispensing common-sense advice, but I don't think it actually applies here.
0xblacklight 11mo ago
I think you’re missing that CLAUDE.md is deterministically injected into the model’s context window This means that instead of behaving like a file the LLM reads, it effectively lets you customize the model’s prompt I also didn’t write that you have to “prompt it just the right way”, I think you’re missing the point entirely
datacynic 11mo ago
Writing documentation for LLMs is strangely pleasing because you have very linear returns for every bit of effort you spend on improving its quality and the feedback loop is very tight. When writing for humans, especially internal documentation, I’ve found that these returns are quickly diminishing or even negative as it’s difficult to know if people even read it or if they didn’t understand it or if it was incomplete.
avereveard 11mo ago
Well, no. You run pretty fast into context limit (or attention limit for long context models) And the model understand pretty well what code does without documentation. Theres also a question of processes. How to format code what style of catching to use and how to run the tests, which human keep on the bacl of their head after reading it once or twice but need a constant reminder for llm whose knowledge lifespan is session limited
- uncletaco 11mo ago
  I’m pretty sure Claude would not work well in my code base if I hadn’t meticulously added docstrings, type hints, and module level documentation. Even if you’re stubbing out code for later implementation, it helps to go ahead and document it so that a code assistant will get a hint of what to do next.

by _pdp_ 11mo ago

dhorthy 11mo ago

For the record I do think the AI community tries to unnecessarily reinvent the wheel on crap all the time. sure, readme.md is a great place to put content. But there's things I'd put in a readme that I'd never put in a claude.md if we want to squeeze the most out of these models. Further, claude/agents.md have special quality-of-life mechanics with the coding agent harnesses like e.g. `injecting this file into the context window whenever an agent touches this directory, no matter whether the model wants to read it or not` > What people often forget about LLMs is that they are largely trained on public information which means that nothing new needs to be invented. I don't think this is relevant at all - when you're working with coding agents, the more you can finesse and manage every token that goes into your model and how its presented, the better results you can get. And the public data that goes into the models is near useless if you're working in a complex codebase, compared to the results you can get if you invest time into how context is collected and presented to your agent.

theshrike79 11mo ago
> For the record I do think the AI community tries to unnecessarily reinvent the wheel on crap all the time. On Reddit's LLM subreddits people are rediscovering the very basics of software project management as some massive insights daily or very least weekly. Who would've guessed that proper planning, accessible and up to documentation and splitting tasks into manageable testable chunks produces good code? Amazing! Then they write a massive blog post or even some MCP mostrosity for it and post it everywhere as a new discovery =)
- dkubb 11mo ago
  I can totally understand where you are coming from with this comment. It does feel a bit frustrating that people are rediscovering things that were written in books 30/40/50 years ago. However, I think this is awesome for the industry. People are rediscovering basic things, but if they didn't know about the existing literature this is a perfect opportunity to refer them to it. And if they were aware, but maybe not practicing it, this is a great time for the ideas to be reinforced. A lot of people, myself included, never really understand which practices are important or not until we were forced to work on a system that was most definitely not written with any good practices in mind. My current view of agentic coding is that it's forcing an entire generation of devs to learn software project management or drowning under the mountain of debt an LLM can produce. Previously it took much longer to feel the weight of bad decisions in a project but an LLM allows you to speed-run this process in a few weeks or months.

bastawhiz 11mo ago

This is missing the point. If I want to instruct Claude to never write a database query that doesn't hit a preexisting index, where exactly am I supposed to document that? You can either choose: 1. A centralized location, like a README (congrats, you've just invented CLAUDE.md) 2. You add a docs folder (congrats, you've just done exactly what the author suggests under Progressive Disclosure) Moreover, you can't just do it all in a README, for the exact reasons that the author lays out under "CLAUDE.md file length & applicability". CLAUDE.md simply isn't about telling Claude what all the parts of your code are and how they work. You're right, that's what documenting your code is for. But even if you have READMEs everywhere, Claude has no idea where to put code when it starts a new task. If it has to read all your documentation every time it starts a new task, you're needlessly burning tokens. The whole point is to give Claude important information up front so it doesn't have to read all your docs and fill up its context window searching for the right information on every task. Think of it this way: incredibly well documented code has everything a new engineer needs to get started on a task, yes. But this engineer has amnesia and forgets everything it's learned after every task. Do you want them to have to reonboard from scratch every time? No! You structure your docs in a way so they don't have to start from scratch every time. This is an accommodation: humans don't need this, for the most part, because we don't reonboard to the same codebase over and over. And so yes, you do need to go above and beyond the "same old good best practices".

_pdp_ 11mo ago
You put a warning where it is most likely to be seen by a human coder. Besides, no amount of prompting will prevent this situation. If it is a concern then you put a linter or unit tests to prevent it altogether, or make a wrapper around the tricky function with some warning in its doc strings. I don't see how this is any different from how you typically approach making your code more resilient to accidental mistakes.
- mvkel 11mo ago
  Documenting for AI exactly like you would document for a human is ignoring how these tools work

johnfn 11mo ago

So how exactly does one "write what this file is supposed to do in a clear concise way" in a way that is quickly comprehensible to AI? The gist of the article is that when your audience changes from "human" to "AI" the manner in which you write documentation changes. The article is fairly high quality, and presents excellent evidence that simply "documenting your code" won't get you as far as the guidelines it provides. Your comment comes off as if you're dispensing common-sense advice, but I don't think it actually applies here.

0xblacklight 11mo ago

I think you’re missing that CLAUDE.md is deterministically injected into the model’s context window This means that instead of behaving like a file the LLM reads, it effectively lets you customize the model’s prompt I also didn’t write that you have to “prompt it just the right way”, I think you’re missing the point entirely

datacynic 11mo ago

Writing documentation for LLMs is strangely pleasing because you have very linear returns for every bit of effort you spend on improving its quality and the feedback loop is very tight. When writing for humans, especially internal documentation, I’ve found that these returns are quickly diminishing or even negative as it’s difficult to know if people even read it or if they didn’t understand it or if it was incomplete.

avereveard 11mo ago

Well, no. You run pretty fast into context limit (or attention limit for long context models) And the model understand pretty well what code does without documentation. Theres also a question of processes. How to format code what style of catching to use and how to run the tests, which human keep on the bacl of their head after reading it once or twice but need a constant reminder for llm whose knowledge lifespan is session limited

uncletaco 11mo ago
I’m pretty sure Claude would not work well in my code base if I hadn’t meticulously added docstrings, type hints, and module level documentation. Even if you’re stubbing out code for later implementation, it helps to go ahead and document it so that a code assistant will get a hint of what to do next.