6 ms·

Ummm… sounds like that directory should have a readme. And Claude should read readme files.

by sroussey 11mo ago

stingraycharles 11mo ago
READMEs are written for people, CLAUDE.mds are written for coding assistants. I don’t write “CRITICAL (PRIORITY 0):” in READMEs. The benefit of CLAUDE.md files is that they’re pulled in automatically, eg if Claude wants to read “tests/foo_test.py” it will automatically pull in “tests/CLAUDE.md” (if it exists).
- adastra22 11mo ago
  Is this documented anywhere? This is the first I have ever heard of it.
  - grumbelbart 11mo ago
    Here: https://www.anthropic.com/engineering/claude-code-best-practices https://www.anthropic.com/engineering/claude-code-best-pract... claude.md seems to be important enough to be their very first point in that document.
    - ffsm8 11mo ago
      Naw man, it's the first point because in April Claude code didn't really gave anything else that somewhat worked. I tried to use that effectively, I even started a new greenfield project just to make sure to test it under ideal circumstances - and while it somewhat worked, it was always super lackluster and way more effective to explicitly add the context manually via prepared md you just reference in the prompt. I'd tell anyone to go for skills first before littering your project with these config files everywhere
- llbeansandrice 11mo ago
  If AI is supposed to deliver on this magical no-lift ease of use task flexibility that everyone likes to talk about I think it should be able to work with a README instead of clogging up ALL of my directories with yet another fucking config file. Also this isn’t portable to other potential AI tools. Do I need 3+ md files in every directory?
  - stingraycharles 11mo ago
    It’s not delivering on magical stuff. Getting real productivity improvements out of this requires engineering and planning and it needs to be approached as such. One of the big mistakes I think is that all these tools are over-promising on the “magic” part of it. It’s not. You need to really learn how to use all these tools effectively. This is not done in days or weeks even, it takes months in the same way becoming proficient in eMacs or vim or a programming language is. Once you’ve done that, though, it can absolutely enhance productivity. Not 10x, but definitely in the area of 2x. Especially for projects / domains you’re uncomfortable with. And of course the most important thing is that you need to enjoy all this stuff as well, which I happen to do. I can totally understand the resistance as it’s a shitload of stuff you need to learn, and it may not even be relevant anymore next year.
    - giancarlostoro 11mo ago
      Yeah I feel like on average I still spend a similar amount of time developing but drastically less time fixing obscure bugs, because once it codes the feature and I describe the bugs it fixed them, the rest of my times spent testing and reviewing code.
    - tsimionescu 11mo ago
      While I believe you're probably right that getting any productivity gains from these tools requires an investment, I think calling the process "engineering" is really stretching the meaning of the word. It's really closer to ritual magic than any solid engineering practices at this point. People have guesses and practices that may or may not actually work for them (since measuring productivity increases is difficult if not impossible), and they teach others their magic formulas for controlling the demon.
      - gtaylor 11mo ago
        Most countries don’t have a notion of a formally licensed software engineer, anyway. Arguing what is and is not engineering is not useful.
- brigandish 11mo ago
  I often can't tell the difference between my Readme and Claude files to the point that I cannibalise the Claude file for the Readme. It's the difference between instructions for a user and instructions for a developer, but in coding projects that's not much different.
  - waldir 11mo ago
    > It's the difference between instructions for a user and instructions for a developer Sounds like a job for a CONTRIBUTING.md :)
- pmarreck 11mo ago
  > “CRITICAL (PRIORITY 0):” There's no need for this level of performative ridiculousness with AGENTS.md (Codex) directives, FYI.

Ummm… sounds like that directory should have a readme. And Claude should read readme files.

READMEs are written for people, CLAUDE.mds are written for coding assistants. I don’t write “CRITICAL (PRIORITY 0):” in READMEs. The benefit of CLAUDE.md files is that they’re pulled in automatically, eg if Claude wants to read “tests/foo_test.py” it will automatically pull in “tests/CLAUDE.md” (if it exists).

adastra22 11mo ago
Is this documented anywhere? This is the first I have ever heard of it.
- grumbelbart 11mo ago
  Here: https://www.anthropic.com/engineering/claude-code-best-practices https://www.anthropic.com/engineering/claude-code-best-pract... claude.md seems to be important enough to be their very first point in that document.
  - ffsm8 11mo ago
    Naw man, it's the first point because in April Claude code didn't really gave anything else that somewhat worked. I tried to use that effectively, I even started a new greenfield project just to make sure to test it under ideal circumstances - and while it somewhat worked, it was always super lackluster and way more effective to explicitly add the context manually via prepared md you just reference in the prompt. I'd tell anyone to go for skills first before littering your project with these config files everywhere
llbeansandrice 11mo ago
If AI is supposed to deliver on this magical no-lift ease of use task flexibility that everyone likes to talk about I think it should be able to work with a README instead of clogging up ALL of my directories with yet another fucking config file. Also this isn’t portable to other potential AI tools. Do I need 3+ md files in every directory?
- stingraycharles 11mo ago
  It’s not delivering on magical stuff. Getting real productivity improvements out of this requires engineering and planning and it needs to be approached as such. One of the big mistakes I think is that all these tools are over-promising on the “magic” part of it. It’s not. You need to really learn how to use all these tools effectively. This is not done in days or weeks even, it takes months in the same way becoming proficient in eMacs or vim or a programming language is. Once you’ve done that, though, it can absolutely enhance productivity. Not 10x, but definitely in the area of 2x. Especially for projects / domains you’re uncomfortable with. And of course the most important thing is that you need to enjoy all this stuff as well, which I happen to do. I can totally understand the resistance as it’s a shitload of stuff you need to learn, and it may not even be relevant anymore next year.
  - giancarlostoro 11mo ago
    Yeah I feel like on average I still spend a similar amount of time developing but drastically less time fixing obscure bugs, because once it codes the feature and I describe the bugs it fixed them, the rest of my times spent testing and reviewing code.
  - tsimionescu 11mo ago
    While I believe you're probably right that getting any productivity gains from these tools requires an investment, I think calling the process "engineering" is really stretching the meaning of the word. It's really closer to ritual magic than any solid engineering practices at this point. People have guesses and practices that may or may not actually work for them (since measuring productivity increases is difficult if not impossible), and they teach others their magic formulas for controlling the demon.
    - gtaylor 11mo ago
      Most countries don’t have a notion of a formally licensed software engineer, anyway. Arguing what is and is not engineering is not useful.
brigandish 11mo ago
I often can't tell the difference between my Readme and Claude files to the point that I cannibalise the Claude file for the Readme. It's the difference between instructions for a user and instructions for a developer, but in coding projects that's not much different.
- waldir 11mo ago
  > It's the difference between instructions for a user and instructions for a developer Sounds like a job for a CONTRIBUTING.md :)
pmarreck 11mo ago
> “CRITICAL (PRIORITY 0):” There's no need for this level of performative ridiculousness with AGENTS.md (Codex) directives, FYI.