diff --git a/CLAUDE.md b/CLAUDE.md
index 5a5a253..a702cb1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -24,6 +24,13 @@ These rules apply to every GSD phase in this project and override defaults:
 - Never add co-author tags to commit messages.
 - One logical change per commit. Planning docs and code in separate commits.
 
+## Documentation
+
+- Any change to a package under `modules/` that touches its exported API, config keys, CLI commands or dependencies must update that module's `README.md` in the same change (the same commit or PR).
+- A new module ships with a `README.md` that follows the standard structure: H1 name, one-sentence summary, import line, then Overview, Features, Usage, API reference, the optional Configuration and CLI commands sections, Dependencies and Testing. It also gets a row in the root `README.md` modules table, whose purpose text reuses the summary sentence.
+- Framework READMEs never name a consuming application. Say "the application" or "host application", and use neutral example names such as `blog` or `acme`.
+- Every identifier named in a README must exist in the package; check it with `go doc ./modules/<name> <Identifier>`.
+
 <!-- GSD:project-start source:PROJECT.md -->
 ## Project