Updated CLAUDE.md

CLAUDE.md

@@ -23,6 +23,15 @@ I'm an engineer. I know what I want. You must not propose next actions, unless I
 - Source comments always describe the current functions of the code, never document the history.
 - Unusual coding diverging from upstream documentation can be commented after the end-user approval.
 
+### Documentation and code comments
+
+- Documentation (README.md, GUIDE.md, docs/*, etc) describes the current state and does not include past state nor things that are missing.
+- Reasoning and decision explanations go to the ADR.md - architecture decision records file if it has been created by the user.
+- Change history goes to the CHANGELOG.md, if it has been created by the user.
+- Do not place documentation like content into comments.
+- Use heredocs to describe code fragments like functions, classes or methods.
+- Use terse single sentence comments to describe code paths and purpose of parts of the long functions or code blocks.
+
 ### Translation
 
 You will ocassionally be asked to translate a program from one language to another, or one framework to a different one. Follow the rules below:
@@ -34,7 +43,7 @@ You will ocassionally be asked to translate a program from one language to anoth
 
 - Do not create passthrough output variables, e.g. in an object or modules that take an input, do not expose the exact same value as output.
 
-# Markdown style
+## Markdown style
 
 - Do not put `---` directly before headers `#` of any level.
 - Always separate lists with a blank line from the preceding paragraph.