Merge claude guidelines into CLAUDE.md

Karakatiza666 · Karakatiza666 · commit 081b5255509f · 2025-08-13T14:13:38.000Z
Signed-off-by: Karakatiza666 &lt;bulakh.96@gmail.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,3 +1,5 @@
+> Important! When `SECTION:some/path/CLAUDE.md START` HTML comment tag is encountered in this file, it means that the content within this tag applies to `some/path/` directory.
+
 ## Context: CLAUDE.md
 <!-- SECTION:CLAUDE.md START -->
 # CLAUDE.md
@@ -254,6 +256,46 @@ The repository seamlessly integrates four major programming languages, each serv
 - **Performance Monitoring**: Built-in benchmarking and profiling tools
 
 This repository represents a complete platform for incremental stream processing, providing everything needed to develop, deploy, and operate high-performance streaming analytics at scale. The modular architecture enables both ease of development and flexibility in deployment while maintaining the performance characteristics essential for real-time data processing.
+
+## CLAUDE.md Authoring Guide
+
+Follow these governing principles when documenting the repository in CLAUDE.md files.
+
+### Purpose and placement
+
+* Write only what’s needed to work effectively in that directory's context; avoid project history; concise underlying reasoning is OK.
+
+### Layering and scope
+
+* Top level provides a high-level overview: the project’s purpose, key components, core workflows, and dependencies between major areas.
+* In the top level, include exactly one short paragraph per current subdirectory describing why it exists and what lives there. Keep it concrete but concise.
+* Subdirectory docs add progressively more detail the deeper you go. Each level narrows to responsibilities, interfaces, commands, schemas, and caveats specific to that scope.
+
+### DRY information flow
+
+* Do not repeat what a parent `CLAUDE.md` already states about a subdirectory. Instead, link up to the relevant section.
+* Put cross-cutting concepts at the highest level that owns them, and reference from below.
+* Keep a single source of truth for contracts, schemas, and commands; everything else links to it.
+
+### Clarity for Claude Code
+
+* Prefer crisp headings, short paragraphs, and tight bullets over prose.
+* Name files, entry points, public interfaces, and primary commands explicitly where they belong.
+* Call out constraints, feature flags, performance notes, and “gotchas” near the workflows they affect.
+
+### Maintenance rules
+
+* Update the highest applicable level first; ensure lower levels still defer to it.
+* Remove stale sections rather than letting them drift; shorter and correct beats exhaustive and outdated.
+* When documenting a new directory, add its paragraph to the top level and create its own `CLAUDE.md` that deepens—never duplicates—the parent’s description.
+
+### Quality checklist
+
+* Top level gives a true overview and one concise paragraph per important subdirectory.
+* Every subdirectory doc increases detail appropriate to its scope.
+* No duplication across levels; links replace repetition.
+* Commands, interfaces, and data shapes are precise and current. It is OK to document different arguments for the same command for different use-cases.
+* Formatting is skim-friendly and consistent across the repo.
 <!-- SECTION:CLAUDE.md END -->
 
 ---
diff --git a/CLAUDE_GUIDELINES.md b/CLAUDE_GUIDELINES.md
diff --git a/scripts/claude.js b/scripts/claude.js
@@ -69,6 +69,8 @@ ${sectionEnd(relPath)}
 
 ---
 `
+const mergedFileHeader =
+'> Important! When `SECTION:some/path/CLAUDE.md START` HTML comment tag is encountered in this file, it means that the content within this tag applies to `some/path/` directory.\n'
 
 /**
  * @param {string} dir
@@ -122,7 +124,7 @@ async function mergeAll() {
   const files = await listClaudeFiles(REPO_ROOT);
   files.sort((a, b) => toRel(a).localeCompare(toRel(b)));
 
-  const sections = [];
+  const sections = [mergedFileHeader];
 
   // If a pre-merge root existed, include it as an (optional) root section
   if (preMergeRoot !== null) {
