Ask HN: Do you still spend time maintaining Claude.md / AGENTS.md files?

9 points by david_d8912 2 days ago | 10 comments

For people using coding agents regularly: do you still invest time in user-level and repo-level instruction files like CLAUDE.md, AGENTS.md, etc.?

It's not a surprise that you don't expect the rules there to be followed even with less than 100 lines of changes. Yet still see folks like Karpathy post rules around with hundreds of stars.

Tell me if you're still spending the effort of trying claude.md, and are they effective, what're you writing in it.

Update: I'm more of talking about behavior rules here (coding standard, comment style, Do this and Don't do that, etc.). For facts like project directories, important doc ref, commands, sure that always helps.

luodaint 23 hours ago |

The difference that affected my approach: CLAUDE.md includes three types of content, which function differently.

Facts (directory organization, commands, references in docs), always work. There’s no discussion here.

Constraints related to regression prevention (specifying certain restrictions based on a particular failure) – work consistently if each individual item doesn’t exceed one sentence and describes a failure I’ve already observed. Example: “Validate JWT at the route level, not the component.” It works since the agent was caught doing it incorrectly. “Always call workspace provisioning when creating a user” – ditto.

Behavior rules (rules regarding comments, naming, dos and don'ts) – this is where the OP fits in. My observation: such rules work if they are concise, specific, and based on an already existing failure pattern. They don’t work if created in anticipation of some failure that didn’t happen yet. Rules made from scratch are usually not followed. The 50 line limitation is justified for this category.

zambelli 20 hours ago |

I personally don't. I do maintain a repo/obsidian vault of useful skills. They're patterns I've "debugged" (ie, how to setup a systemd unattended batch job specifically on this linux box).

When I start a project, I'll point the agent to a few big behavior concepts on my own standards and preferences, we iterate on the project specific stuff, and once the shape is locked in I point it to the repo to look for relevant patterns.

Once that is covered, it's off to the races. That being said, I don't consider myself an agentic coding power-user.

bisonbear 2 days ago |

AGENTS.md is extremely important - it's probably the highest leverage thing you can give your agent. It's injected into every turn, and the agents are trained to follow instructions. If anything, I think people are under-investing into AGENTS.md and going purely based on vibes.

For example, if I write a bad AGENTS.md for a repo with 100 engineers actively working in it, then every agent for every engineer gets worse, without anyone really noticing.

I think we should move towards data-based tuning of AGENTS.md, testing out changes, gathering data, and then making a decision on whether or not to ship it.

david_d8912 1 day ago | |

The project directory, sure. I'm more of talking about behavior rules here. What are you guys writing, is it effective

bisonbear 1 day ago | | |

My advice, from doing this myself and reading best practices, would be:

- Keep it concise, use progressive disclosure / nested AGENTS.md for information expansion - Give agent the high level repo structure if necessary - Have a "why" section to align the agent, high level, what your code is doing - Keep behavior instructions positive where possible, eg Always clarify intent before acting

alwillis 1 day ago |

What helps me a lot: if Claude makes a mistake or an incorrect assumption, press # to tell Claude to remember the correct behavior next time.

Put your coding guidelines in the ./claude/rules for additional progressive disclosure, not CLAUDE.md or AGENTS.md.

rurban 1 day ago |

Of course. Claude.md is symlinked, and I change it for every new major task. Keeps cost down

verdverm 1 day ago |

I wrote one yesterday, but what goes in them has changed. Now I only put what amounts to a table of contents and some highlights of important things. Other info goes in other markdown, either localized agents.md or a directory of references. Skills are useful too

Anthropic has a new post series on enterprise adoption, their first one is on the setup and AGENTS.md gets a good chunk of that

I now have agents write more of that stuff but deeply review it. As peer commenter points out, a bad instruction can do damage. Keep them lean and clean, adjust them as new models arrive.