From a0de8ba18c35ed3f828b98c220fc1c5e8f87fd2d Mon Sep 17 00:00:00 2001 From: rob thijssen Date: Wed, 22 Apr 2026 12:54:32 +0300 Subject: [PATCH] docs(generic): keep CLAUDE.md/AGENTS.md uppercase, allow autonomous edits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Carve out the agent-instruction files as exceptions to the lowercase-readme convention — their all-caps naming is what tooling expects and what makes them visible in a file listing. Also document that agents can modify these files on their own judgement; diffs get reviewed so drift is caught downstream. Co-Authored-By: Claude Opus 4.7 (1M context) --- generic.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/generic.md b/generic.md index aaac1d6..fb99c35 100644 --- a/generic.md +++ b/generic.md @@ -515,6 +515,8 @@ This is the environment these apps deploy into. Claude Code should assume it. - Each crate has a `readme.md` or top-level module doc explaining its role in the workspace. - The repo `readme.md` covers: what the project does, how to build, how to run locally, how to deploy. Point readers to this document for architectural conventions. - **Name readme files `readme.md` (lowercase), not `README.md`.** The shouty all-caps spelling is a convention I don't share; filenames aren't where emphasis belongs. Every forge in use (Gitea, GitHub, GitLab) renders `readme.md` as the repo landing page just as readily as `README.md`. Other conventional top-level docs — `license`, `changelog`, `contributing` — follow the same rule: lowercase, no shouting. +- **Exception: `CLAUDE.md` and `AGENTS.md` stay in uppercase.** These are agent-facing instruction files and are easy to miss in a file listing when lowercased. The all-caps spelling is the established convention and the one that tooling (Claude Code and other agent harnesses) looks for, so leave them as-is. +- **Agents may modify `CLAUDE.md` and `AGENTS.md` at their own discretion** — no approval needed to add, update, or remove guidance when it's warranted. Diffs get reviewed, so unintentional drift will surface in the normal flow. Treat these as living instructions that should be kept accurate and current. ### Commits - **Use [Conventional Commits](https://www.conventionalcommits.org/) syntax for every commit.** `type(scope): subject`, with types drawn from the standard set (`feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `build`, `ci`, `perf`, `style`). Scope is the crate, component, or area touched. Subject is imperative and under ~70 characters. A body may follow if the *why* isn't self-evident.