Mark Dominus (陶敏修) mjd@pobox.com About me RSS Atom 12 recent entries Update: Here I am at the Sagrada Família Egyptian fractions for 2/105 Did Ahmes find the best expansions for 2/n? Programmers will document for Claude, but not for each other How are John Waters movies like James Bond movies? Documentation is a message in a bottle Bo Diddley Language models imply world models John Haugeland on the failure of micro-worlds Crooked politicians love crab cakes! Almost-trivial theorems An anecdote about backward compatibility Archive: 2026: JFMAMJ 2025: JFMAMJ JASOND 2024: JFMAMJ JASOND 2023: JFMAMJ JASOND 2022: JFMAMJ JASOND 2021: JFMAMJ JASOND 2020: JFMAMJ JASOND 2019: JFMAMJ JASOND 2018: JFMAMJ JASOND 2017: JFMAMJ JASOND 2016: JFMAMJ JASOND 2015: JFMAMJ JASOND 2014: JFMAMJ JASOND 2013: JFMAMJ JASOND 2012: JFMAMJ JASOND 2011: JFMAMJ JASOND 2010: JFMAMJ JASOND 2009: JFMAMJ JASOND 2008: JFMAMJ JASOND 2007: JFMAMJ JASOND 2006: JFMAMJ JASOND 2005: OND Subtopics: Mathematics249 Programming100 Language95 Miscellaneous75 Book50 Tech49 Etymology36 Haskell33 Oops30 Unix27 Cosmic Call25 Math SE25 Law23 Physics21 Perl17 Biology16 Brain15 Calendar15 Food15 Comments disabled Mon, 09 Mar 2026 Programmers will document for Claude, but not for each other A couple of days ago I recounted a common complaint: I keep seeing programmers say how angry it makes them that people are willing to write detailed CLAUDE.md and PROJECT.md files for Claude to use, but they weren't willing to write them for their coworkers. For larger projects, I've taken to having Claude maintain a handoff document that I can have the next Claude read, saying what we planned to do, what has been done, and other pertinent information. Then when I shut down one Claude I can have the next one read the file to get up to speed. Then I have the Claude !!n+1!! update it for Claude !!n+2!!. After seeing the common complaint enough times I had a happy inspiration. I'd been throwing away Claude's handoff documents at the end of each project. Why do that? It's no trouble to copy the file into the repository and commit it. Someone in the future, wondering what was going on, might luckily find the right document with git grep and learn something useful. 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 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. But Claude's explanations haven't required much editing. Claude's most recent project summary was around as good as what I could have written myself, maybe a little worse and maybe a little better. But it took ten seconds to write instead of an hour, and it didn't take anything like an hour to review. The serious thing I had to fix the last time around was that Claude had used a previous, related report as a model, and the previous report had had a paragraph I had added at the end that said: # Approved-by Claude abstracted these notes from our discussions of the issue. Mark Dominus has read, reviewed, edited, and approved these notes. Claude's new document had an identical section at the end. Oops! Fortunately, by the time I saw it, it was true, so I didn't have to delete it. I had Claude add a sentence to CLAUDE.md to tell it not to do this again. My advice for the day: If you have Claude write down notes, check them into the repo when you're done. It probably can't hurt and it might help. Have Claude write a project summary, and then check it into the repo. Maybe this is obvious? But it wasn't obvious to me. I'm still getting used to this new world. [Other articles in category /tech/gpt] permanent link
Mark Dominus (陶敏修) mjd@pobox.com About me RSS Atom 12 recent entries Update: Here I am at the Sagrada Família Egyptian fractions for 2/105 Did Ahmes find the best expansions for 2/n? Programmers will document for Claude, but not for each other How are John Waters movies like James Bond movies? Documentation is a message in a bottle Bo Diddley Language models imply world models John Haugeland on the failure of micro-worlds Crooked politicians love crab cakes! Almost-trivial theorems An anecdote about backward compatibility Archive: 2026: JFMAMJ 2025: JFMAMJ JASOND 2024: JFMAMJ JASOND 2023: JFMAMJ JASOND 2022: JFMAMJ JASOND 2021: JFMAMJ JASOND 2020: JFMAMJ JASOND 2019: JFMAMJ JASOND 2018: JFMAMJ JASOND 2017: JFMAMJ JASOND 2016: JFMAMJ JASOND 2015: JFMAMJ JASOND 2014: JFMAMJ JASOND 2013: JFMAMJ JASOND 2012: JFMAMJ JASOND 2011: JFMAMJ JASOND 2010: JFMAMJ JASOND 2009: JFMAMJ JASOND 2008: JFMAMJ JASOND 2007: JFMAMJ JASOND 2006: JFMAMJ JASOND 2005: OND Subtopics: Mathematics249 Programming100 Language95 Miscellaneous75 Book50 Tech49 Etymology36 Haskell33 Oops30 Unix27 Cosmic Call25 Math SE25 Law23 Physics21 Perl17 Biology16 Brain15 Calendar15 Food15 Comments disabled Mon, 09 Mar 2026 Programmers will document for Claude, but not for each other A couple of days ago I recounted a common complaint: I keep seeing programmers say how angry it makes them that people are willing to write detailed CLAUDE.md and PROJECT.md files for Claude to use, but they weren't willing to write them for their coworkers. For larger projects, I've taken to having Claude maintain a handoff document that I can have the next Claude read, saying what we planned to do, what has been done, and other pertinent information. Then when I shut down one Claude I can have the next one read the file to get up to speed. Then I have the Claude !!n+1!! update it for Claude !!n+2!!. After seeing the common complaint enough times I had a happy inspiration. I'd been throwing away Claude's handoff documents at the end of each project. Why do that? It's no trouble to copy the file into the repository and commit it. Someone in the future, wondering what was going on, might luckily find the right document with git grep and learn something useful. 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 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. But Claude's explanations haven't required much editing. Claude's most recent project summary was around as good as what I could have written myself, maybe a little worse and maybe a little better. But it took ten seconds to write instead of an hour, and it didn't take anything like an hour to review. The serious thing I had to fix the last time around was that Claude had used a previous, related report as a model, and the previous report had had a paragraph I had added at the end that said: # Approved-by Claude abstracted these notes from our discussions of the issue. Mark Dominus has read, reviewed, edited, and approved these notes. Claude's new document had an identical section at the end. Oops! Fortunately, by the time I saw it, it was true, so I didn't have to delete it. I had Claude add a sentence to CLAUDE.md to tell it not to do this again. My advice for the day: If you have Claude write down notes, check them into the repo when you're done. It probably can't hurt and it might help. Have Claude write a project summary, and then check it into the repo. Maybe this is obvious? But it wasn't obvious to me. I'm still getting used to this new world. [Other articles in category /tech/gpt] permanent link
Mark Dominus (陶敏修) mjd@pobox.com
About me
RSS Atom
12 recent entries Update: Here I am at the Sagrada Família Egyptian fractions for 2/105 Did Ahmes find the best expansions for 2/n? Programmers will document for Claude, but not for each other How are John Waters movies like James Bond movies? Documentation is a message in a bottle Bo Diddley Language models imply world models John Haugeland on the failure of micro-worlds Crooked politicians love crab cakes! Almost-trivial theorems An anecdote about backward compatibility
Update: Here I am at the Sagrada Família Egyptian fractions for 2/105 Did Ahmes find the best expansions for 2/n? Programmers will document for Claude, but not for each other How are John Waters movies like James Bond movies? Documentation is a message in a bottle Bo Diddley Language models imply world models John Haugeland on the failure of micro-worlds Crooked politicians love crab cakes! Almost-trivial theorems An anecdote about backward compatibility
Programmers will document for Claude, but not for each other
A couple of days ago I recounted a common complaint:
I keep seeing programmers say how angry it makes them that people are willing to write detailed CLAUDE.md and PROJECT.md files for Claude to use, but they weren't willing to write them for their coworkers.
I keep seeing programmers say how angry it makes them that people are willing to write detailed CLAUDE.md and PROJECT.md files for Claude to use, but they weren't willing to write them for their coworkers.
CLAUDE.md
PROJECT.md
For larger projects, I've taken to having Claude maintain a handoff document that I can have the next Claude read, saying what we planned to do, what has been done, and other pertinent information. Then when I shut down one Claude I can have the next one read the file to get up to speed. Then I have the Claude !!n+1!! update it for Claude !!n+2!!.
After seeing the common complaint enough times I had a happy inspiration. I'd been throwing away Claude's handoff documents at the end of each project. Why do that? It's no trouble to copy the file into the repository and commit it. Someone in the future, wondering what was going on, might luckily find the right document with git grep and learn something useful.
git grep
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 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.
But Claude's explanations haven't required much editing. Claude's most recent project summary was around as good as what I could have written myself, maybe a little worse and maybe a little better. But it took ten seconds to write instead of an hour, and it didn't take anything like an hour to review.
The serious thing I had to fix the last time around was that Claude had used a previous, related report as a model, and the previous report had had a paragraph I had added at the end that said:
Approved-by Claude abstracted these notes from our discussions of the issue. Mark Dominus has read, reviewed, edited, and approved these notes.
Approved-by
Claude abstracted these notes from our discussions of the issue. Mark Dominus has read, reviewed, edited, and approved these notes.
Claude's new document had an identical section at the end. Oops! Fortunately, by the time I saw it, it was true, so I didn't have to delete it. I had Claude add a sentence to CLAUDE.md to tell it not to do this again.
CLAUDE.md
My advice for the day:
If you have Claude write down notes, check them into the repo when you're done. It probably can't hurt and it might help.
If you have Claude write down notes, check them into the repo when you're done. It probably can't hurt and it might help.
Have Claude write a project summary, and then check it into the repo.
Have Claude write a project summary, and then check it into the repo.
Maybe this is obvious? But it wasn't obvious to me. I'm still getting used to this new world.
[Other articles in category /tech/gpt] permanent link
Mark Dominus (陶敏修) mjd@pobox.com
About me
RSS Atom
12 recent entries Update: Here I am at the Sagrada Família Egyptian fractions for 2/105 Did Ahmes find the best expansions for 2/n? Programmers will document for Claude, but not for each other How are John Waters movies like James Bond movies? Documentation is a message in a bottle Bo Diddley Language models imply world models John Haugeland on the failure of micro-worlds Crooked politicians love crab cakes! Almost-trivial theorems An anecdote about backward compatibility
Update: Here I am at the Sagrada Família Egyptian fractions for 2/105 Did Ahmes find the best expansions for 2/n? Programmers will document for Claude, but not for each other How are John Waters movies like James Bond movies? Documentation is a message in a bottle Bo Diddley Language models imply world models John Haugeland on the failure of micro-worlds Crooked politicians love crab cakes! Almost-trivial theorems An anecdote about backward compatibility
Programmers will document for Claude, but not for each other
A couple of days ago I recounted a common complaint:
I keep seeing programmers say how angry it makes them that people are willing to write detailed CLAUDE.md and PROJECT.md files for Claude to use, but they weren't willing to write them for their coworkers.
I keep seeing programmers say how angry it makes them that people are willing to write detailed CLAUDE.md and PROJECT.md files for Claude to use, but they weren't willing to write them for their coworkers.
CLAUDE.md
PROJECT.md
For larger projects, I've taken to having Claude maintain a handoff document that I can have the next Claude read, saying what we planned to do, what has been done, and other pertinent information. Then when I shut down one Claude I can have the next one read the file to get up to speed. Then I have the Claude !!n+1!! update it for Claude !!n+2!!.
After seeing the common complaint enough times I had a happy inspiration. I'd been throwing away Claude's handoff documents at the end of each project. Why do that? It's no trouble to copy the file into the repository and commit it. Someone in the future, wondering what was going on, might luckily find the right document with git grep and learn something useful.
git grep
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 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.
But Claude's explanations haven't required much editing. Claude's most recent project summary was around as good as what I could have written myself, maybe a little worse and maybe a little better. But it took ten seconds to write instead of an hour, and it didn't take anything like an hour to review.
The serious thing I had to fix the last time around was that Claude had used a previous, related report as a model, and the previous report had had a paragraph I had added at the end that said:
Approved-by Claude abstracted these notes from our discussions of the issue. Mark Dominus has read, reviewed, edited, and approved these notes.
Approved-by
Claude abstracted these notes from our discussions of the issue. Mark Dominus has read, reviewed, edited, and approved these notes.
Claude's new document had an identical section at the end. Oops! Fortunately, by the time I saw it, it was true, so I didn't have to delete it. I had Claude add a sentence to CLAUDE.md to tell it not to do this again.
CLAUDE.md
My advice for the day:
If you have Claude write down notes, check them into the repo when you're done. It probably can't hurt and it might help.
If you have Claude write down notes, check them into the repo when you're done. It probably can't hurt and it might help.
Have Claude write a project summary, and then check it into the repo.
Have Claude write a project summary, and then check it into the repo.
Maybe this is obvious? But it wasn't obvious to me. I'm still getting used to this new world.
[Other articles in category /tech/gpt] permanent link