Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Programmers will document for Claude, but not for each other

blog.plover.com

Post reply on HN
Print view View original

161–166 of 166 posts

Re: Programmers will document for Claude, but not for each other

#161

Post by sermakarevich »

Time vs effort balance is very different for the two cases.

-- writing documents for each other takes weeks - write the document, give people time to review the document, discuss, update on review.

-- writing documents for Claude takes minutes rather than hour - AI is used to assist in writing specs, personal instead of collective review/approval process.

Also beneficiaries are different:

-- when you write spec for Claude - you benefit personally, you have higher chance of getting code you need from ai coder

-- when you write spec for the company - the company is the main beneficiary, it get higher chances to get teams on the same page with the change

Re: Programmers will document for Claude, but not for each other

#162

Post by coldtea »

>I review these overviews carefully and make edits as necessary before I check them in. It's my signature on the commit, and my bank account receiving the paycheck, so nothing goes into the repository that I haven't read carefully and understood, same as if Claude were a human programmer under my supervision.

Commit enough of this documentation, and your bank account wont be receiving the paycheck anymore ("position eliminated, they AI can now do his job").

Re: Programmers will document for Claude, but not for each other

#163

Post by coldtea »

noncoml wrote: post #148
chocrates wrote: post #146

Earlier quoted context omitted.

Asking it why it did something will not get you usable data. It will read what it did in the context and hallucinate a reason.

You are right on that, but my point was how it just ignores what it read, even if it is in its context

It read the context and randomly picked a way around what it asked. That's just how it works. Other times, it will follow it.

Re: Programmers will document for Claude, but not for each other

#164

Post by coldtea »

pixl97 wrote: post #147
qsera wrote: post #125

Earlier quoted context omitted.

This is not very surprising. The docs you write can only help if the person who is reading it have the same mental model of what ever thing that is being documented. Because the questons they want answered arises from what ever little subset of understanding they have of the thing. And this could be different for different people. And this is why LLMs are great for looking up docs. It makes any docs work for any one…

Adding to this, if an LLM can't get the right answer from your docs, its your docs that are bad.

Nah, it's also just as well the LLM that's not smart enough/hallucinates.

You can see it often reading the code wrongly (and the code is the canonical description of the program, no room for interpretation). Or inventing non-existent APIs. Or not being able to count the "r" in bluberries.

And suddenly, the only way for it to get the wrong idea from your docs is the docs themselves being bad?

Re: Programmers will document for Claude, but not for each other

#165

Post by zahlman »

p1anecrazy wrote: post #160
zahlman wrote: post #134

> I'm a little slow so it took me until this week to think of a better version of this: at the end of the project I now ask Claude to write up from scratch a detailed but high-level explanation of what problem we were solving and what changes we made, and I commit that. Not just running notes, but a structured overview of the whole thing. I feel like the right place for this information is in the Git history itself.…

I understand the author wants to add it every time as a signature, and having claude do it doesn‘t fulfill the purpose

I meant: why tell Claude to edit CLAUDE.md to add the "don't add a signature" rule, instead of just writing a "don't add a signature" rule into CLAUDE.md directly? The necessary rule can't be much longer than the prompt generating it, surely.
Post reply on HN