claudeos-core 2.4.0 → 2.4.2

package/README.ru.md

@@ -7,44 +7,40 @@
 [![license](https://img.shields.io/npm/l/claudeos-core.svg?color=blue)](LICENSE)
 [![downloads](https://img.shields.io/npm/dm/claudeos-core.svg?logo=npm&color=blue&label=downloads)](https://www.npmjs.com/package/claudeos-core)
 
-**Автоматическая генерация документации Claude Code из вашего реального исходного кода.** CLI-инструмент, который статически анализирует ваш проект, а затем запускает 4-pass конвейер Claude для создания `.claude/rules/`, standards, skills и guides — так что Claude Code следует конвенциям **именно вашего** проекта, а не общим.
+**CLI-инструмент, который читает реальный исходный код вашего проекта и на его основе сам собирает `CLAUDE.md` и `.claude/rules/`. Внутри: сканер на Node.js, четырёхпроходный пайплайн на базе Claude и пять валидаторов. Поддерживаются 12 стеков и 10 языков, а пути, которых нет в коде, инструмент не выдумывает.**
 
 ```bash
 npx claudeos-core init
 ```
 
+Работает на [**12 стеках**](#supported-stacks), включая монорепозитории. Одна команда без конфигурации, безопасная при прерывании, идемпотентная при повторных запусках.
+
 [🇺🇸 English](README.md) · [🇰🇷 한국어](README.ko.md) · [🇨🇳 中文](README.zh-CN.md) · [🇯🇵 日本語](README.ja.md) · [🇪🇸 Español](README.es.md) · [🇻🇳 Tiếng Việt](README.vi.md) · [🇮🇳 हिन्दी](README.hi.md) · [🇫🇷 Français](README.fr.md) · [🇩🇪 Deutsch](README.de.md)
 
 ---
 
-## Что это такое?
+## Что это?
 
-Вы используете Claude Code. Он умный, но **не знает конвенций вашего проекта**:
-- Ваша команда использует MyBatis, а Claude генерирует код для JPA.
-- Ваша обёртка — `ApiResponse.ok()`, а Claude пишет `ResponseEntity.success()`.
-- Ваши пакеты — `controller/order/`, а Claude создаёт `order/controller/`.
+В каждой новой сессии Claude Code откатывается к дефолтам фреймворка. Команда сидит на **MyBatis**, а Claude всё равно пишет JPA. В коде обёртка `ApiResponse.ok()`, а Claude подставляет `ResponseEntity.success()`. Пакеты разложены по слоям, а Claude собирает структуру по доменам. Можно, конечно, написать `.claude/rules/` руками для каждого репозитория — только код развивается, и правила почти сразу отстают от реальности.
 
-Поэтому вы тратите немалую часть времени на правку каждого сгенерированного файла.
+**ClaudeOS-Core пересобирает их предсказуемо, прямо из исходного кода проекта.** Сначала сканер на Node.js разбирает проект и вытаскивает стек, ORM, раскладку пакетов, реальные пути к файлам. Затем четырёхпроходный пайплайн на Claude пишет полный комплект документации: `CLAUDE.md`, автоматически подгружаемые `.claude/rules/`, стандарты, навыки. Всё это происходит строго внутри явного allowlist путей — за его пределы LLM выйти не может. И прежде чем результат окажется у вас, его проверяют пять валидаторов.
 
-**ClaudeOS-Core решает эту проблему.** Он сканирует ваш реальный исходный код, выясняет ваши конвенции и записывает полный набор правил в `.claude/rules/` — каталог, который Claude Code читает автоматически. В следующий раз, когда вы скажете *"Создай CRUD для заказов"*, Claude последует вашим конвенциям с первой попытки.
+В итоге одинаковый вход даёт побайтово одинаковый выход на любом из 10 языков, а пути, которых нет в коде, в документации не появляются. Подробности — ниже, в разделе [В чём отличие](#в-чём-отличие).
 
-```
-До:    Вы → Claude Code → "в целом хороший" код → правка вручную
-После: Вы → Claude Code → код, соответствующий вашему проекту → используйте как есть
-```
+Для долгоживущих проектов рядом разворачивается [Memory Layer](#memory-layer-опционально-для-долгосрочных-проектов).
 
 ---
 
-## Демонстрация на реальном проекте
+## Посмотреть на реальном проекте
 
-Запуск на [`spring-boot-realworld-example-app`](https://github.com/gothinkster/spring-boot-realworld-example-app) — Java 11 · Spring Boot 2.6 · MyBatis · SQLite · 187 source files. Результат: **75 generated files**, общее время **53 минуты**, все validators ✅.
+Прогнали на [`spring-boot-realworld-example-app`](https://github.com/gothinkster/spring-boot-realworld-example-app): Java 11 · Spring Boot 2.6 · MyBatis · SQLite · 187 исходных файлов. На выходе — **75 сгенерированных файлов** за **53 минуты**, все валидаторы зелёные ✅.
 
 <p align="center">
   <img src="docs/assets/spring-boot-realworld-demo.gif" alt="ClaudeOS-Core init running on spring-boot-realworld-example-app — stack detection, 4-pass pipeline, validators, completion summary" width="769">
 </p>
 
 <details>
-<summary><strong>📺 Вывод терминала (текстовая версия, для поиска и копирования)</strong></summary>
+<summary><strong>Вывод терминала (текстовая версия для поиска и копирования)</strong></summary>
 
 ```text
 ╔════════════════════════════════════════════════════╗
@@ -79,18 +75,18 @@ npx claudeos-core init
     [██████████░░░░░░░░░░] 50% (2/4)
 
 [6] Pass 3 — Generating all files...
-    🚀 Pass 3 split mode (3a → 3b → 3c → 3d-aux)
+    Pass 3 split mode (3a → 3b → 3c → 3d-aux)
     ✅ 3a complete (2m 57s)            — pass3a-facts.md (187-path allowlist)
     ✅ 3b complete (18m 49s)           — CLAUDE.md + 19 standards + 20 rules
     ✅ 3c complete (12m 35s)           — 13 skills + 9 guides
     ✅ 3d-aux complete (3m 18s)        — database/ + mcp-guide/
-    🎉 Pass 3 split complete: 4/4 stages successful
+    Pass 3 split complete: 4/4 stages successful
     [███████████████░░░░░] 75% (3/4)
 
 [7] Pass 4 — Memory scaffolding...
-    📦 Pass 4 staged-rules: 6 rule files moved to .claude/rules/
+    Pass 4 staged-rules: 6 rule files moved to .claude/rules/
     ✅ Pass 4 complete (5m)
-       📋 Gap-fill: all 12 expected files already present
+       Gap-fill: all 12 expected files already present
     [████████████████████] 100% (4/4)
 
 ╔═══════════════════════════════════════╗
@@ -119,37 +115,45 @@ npx claudeos-core init
 </details>
 
 <details>
-<summary><strong>📄 Что попадает в ваш <code>CLAUDE.md</code> (реальный фрагмент)</strong></summary>
+<summary><strong>Что в итоге попадает в ваш <code>CLAUDE.md</code> (реальный фрагмент — Section 1 + 2)</strong></summary>
 
 ```markdown
-## 4. Core Architecture
-
-### Core Patterns
-
-- **Hexagonal ports & adapters**: domain ports live in `io.spring.core.{aggregate}`
-  and are implemented by `io.spring.infrastructure.repository.MyBatis{Aggregate}Repository`.
-  The domain layer has zero MyBatis imports.
-- **CQRS-lite read/write split (same DB)**: write side goes through repository ports
-  + entities; read side is a separate `readservice` package whose `@Mapper`
-  interfaces return `*Data` DTOs directly (no entity hydration).
-- **No aggregator/orchestrator layer**: multi-source orchestration happens inside
-  application services (e.g., `ArticleQueryService`); there is no `*Aggregator`
-  class in the codebase.
-- **Application-supplied UUIDs**: entity constructors assign their own UUID; PK is
-  passed via `#{user.id}` on INSERT. The global
-  `mybatis.configuration.use-generated-keys=true` flag is dead config
-  (auto-increment is unused).
-- **JWT HS512 authentication**: `io.spring.infrastructure.service.DefaultJwtService`
-  is the sole token subject in/out; `io.spring.api.security.JwtTokenFilter`
-  extracts the token at the servlet layer.
+# CLAUDE.md — spring-boot-realworld-example-app
+
+> Reference implementation of the RealWorld backend specification on
+> Java 11 + Spring Boot 2.6, exposing both REST and GraphQL endpoints
+> over a hexagonal MyBatis persistence layer.
+
+#### 1. Role Definition
+
+As the senior developer for this repository, you are responsible for
+writing, modifying, and reviewing code. Responses must be written in English.
+A Java Spring Boot REST + GraphQL API server organized around a hexagonal
+(ports & adapters) architecture, with a CQRS-lite read/write split inside
+an XML-driven MyBatis persistence layer and JWT-based authentication.
+
+#### 2. Project Overview
+
+| Item | Value |
+|---|---|
+| Language | Java 11 |
+| Framework | Spring Boot 2.6.3 |
+| Build Tool | Gradle (Groovy DSL) |
+| Persistence | MyBatis 3 via `mybatis-spring-boot-starter:2.2.2` (no JPA) |
+| Database | SQLite (`org.xerial:sqlite-jdbc:3.36.0.3`) — `dev.db` (default), `:memory:` (test) |
+| Migration | Flyway — single baseline `V1__create_tables.sql` |
+| API Style | REST (`io.spring.api.*`) + GraphQL via Netflix DGS `:4.9.21` |
+| Authentication | JWT HS512 (`jjwt-api:0.11.2`) + Spring Security `PasswordEncoder` |
+| Server Port | 8080 (default) |
+| Test Stack | JUnit Jupiter 5, Mockito, AssertJ, rest-assured, spring-mock-mvc |
 ```
 
-Примечание: каждое утверждение выше основано на реальном исходном коде — имена классов, пути пакетов, ключи конфигурации и флаг dead-config извлечены сканером ещё до того, как Claude начал писать файл.
+Каждое значение в этой таблице — точные координаты зависимостей, имя файла `dev.db`, название миграции `V1__create_tables.sql`, пометка «no JPA» — сканер вычитал из `build.gradle`, `application.properties` и дерева исходников ещё до того, как Claude взялся за файл. Ничего не угадано.
 
 </details>
 
 <details>
-<summary><strong>🛡️ Реальное автоматически загружаемое правило (<code>.claude/rules/10.backend/03.data-access-rules.md</code>)</strong></summary>
+<summary><strong>Реальное автоматически подгружаемое правило (<code>.claude/rules/10.backend/01.controller-rules.md</code>)</strong></summary>
 
 ````markdown
 ---
@@ -157,298 +161,352 @@ paths:
   - "**/*"
 ---
 
-# Data Access Rules
+#### Controller Rules
+
+##### REST (`io.spring.api.*`)
 
-## XML-only SQL
-- Every SQL statement lives in `src/main/resources/mapper/*.xml`.
-  NO `@Select` / `@Insert` / `@Update` / `@Delete` annotations on `@Mapper` methods.
-- Each `@Mapper` interface has exactly one XML file at
-  `src/main/resources/mapper/{InterfaceName}.xml`.
-- `<mapper namespace="...">` MUST be the fully qualified Java interface name.
-  The single existing exception is `TransferData.xml` (free-form `transfer.data`).
+- Controllers are the SOLE response wrapper for HTTP — no aggregator/facade above them.
+  Return `ResponseEntity<?>` or a body Spring serializes via `JacksonCustomizations`.
+- Each controller method calls exactly ONE application service method. Multi-source
+  composition lives in the application service.
+- Controllers MUST NOT import `io.spring.infrastructure.*`. No direct `@Mapper` access.
+- Validate command-param arguments with `@Valid`. Custom JSR-303 constraints live under
+  `io.spring.application.{aggregate}.*`.
+- Resolve the current user via `@AuthenticationPrincipal User`.
+- Let exceptions propagate to `io.spring.api.exception.CustomizeExceptionHandler`
+  (`@ControllerAdvice`). Do NOT `try/catch` business exceptions inside the controller.
 
-## Dynamic SQL
-- `<if>` predicates MUST guard both null and empty:
-  `<if test="X != null and X != ''">`. Empty-only is the existing HIGH-severity bug pattern.
-- Prefer `LIMIT n OFFSET m` over MySQL-style `LIMIT m, n`.
+##### GraphQL (`io.spring.graphql.*`)
 
-## Examples
+- DGS components (`@DgsComponent`) are the sole GraphQL response wrappers.
+  Use `@DgsQuery` / `@DgsData` / `@DgsMutation`.
+- Resolve the current user via `io.spring.graphql.SecurityUtil.getCurrentUser()`.
+
+##### Examples
 
 ✅ Correct:
-```xml
-<update id="update">
-  UPDATE articles
-  <set>
-    <if test="article.title != null and article.title != ''">title = #{article.title},</if>
-    updated_at = #{article.updatedAt}
-  </set>
-  WHERE id = #{article.id}
-</update>
+```java
+@PostMapping
+public ResponseEntity<?> createArticle(@AuthenticationPrincipal User user,
+                                       @Valid @RequestBody NewArticleParam param) {
+    Article article = articleCommandService.createArticle(param, user);
+    ArticleData data = articleQueryService.findById(article.getId(), user)
+        .orElseThrow(ResourceNotFoundException::new);
+    return ResponseEntity.ok(Map.of("article", data));
+}
 ```
 
 ❌ Incorrect:
-```xml
-<mapper namespace="article.mapper">          <!-- NO — namespace MUST be FQCN -->
+```java
+@PostMapping
+public ResponseEntity<?> create(@RequestBody NewArticleParam p) {
+    try {
+        articleCommandService.createArticle(p, currentUser);
+    } catch (Exception e) {                                      // NO — let CustomizeExceptionHandler handle it
+        return ResponseEntity.status(500).body(e.getMessage());  // NO — leaks raw message
+    }
+    return ResponseEntity.ok().build();
+}
 ```
 ````
 
-Glob `paths: ["**/*"]` означает, что Claude Code автоматически загружает это правило при редактировании любого файла в проекте. Примеры ✅/❌ берутся прямо из реальных конвенций этой кодовой базы и существующих паттернов багов.
+Глоб `paths: ["**/*"]` означает, что Claude Code будет автоматически подтягивать это правило при редактировании любого файла в проекте. Имена классов, пакеты и обработчики исключений в правиле взяты прямо из просканированных исходников, поэтому в нём фигурируют реальные `CustomizeExceptionHandler` и `JacksonCustomizations` именно из этого проекта.
 
 </details>
 
 <details>
-<summary><strong>🧠 Автоматически сгенерированный сид <code>decision-log.md</code> (реальный фрагмент)</strong></summary>
+<summary><strong>Сид автоматически сгенерированного <code>decision-log.md</code> (реальный фрагмент)</strong></summary>
 
 ```markdown
-## 2026-04-26 — CQRS-lite read/write split inside the persistence layer
-
-- **Context:** Writes go through `core.*Repository` port → `MyBatis*Repository`
-  adapter → `io.spring.infrastructure.mybatis.mapper.{Aggregate}Mapper`.
-  Reads bypass the domain port: application service →
-  `io.spring.infrastructure.mybatis.readservice.{Concept}ReadService` directly,
-  returning flat `*Data` DTOs from `io.spring.application.data.*`.
-- **Options considered:** Single repository surface returning hydrated entities
-  for both reads and writes.
-- **Decision:** Same database, two `@Mapper` packages — `mapper/` (write side,
-  operates on core entities) and `readservice/` (read side, returns `*Data` DTOs).
-  Read DTOs avoid entity hydration overhead.
-- **Consequences:** Reads are NOT routed through the domain port — this is
-  intentional, not a bug. Application services may inject both a `*Repository`
-  (writes) and one or more `*ReadService` interfaces (reads) at the same time.
-  Do NOT add hydrate-then-map glue in the read path.
+#### 2026-04-26 — Hexagonal ports & adapters with MyBatis-only persistence
+
+- **Context:** `io.spring.core.*` exposes `*Repository` ports (e.g.,
+  `io.spring.core.article.ArticleRepository`) implemented by
+  `io.spring.infrastructure.repository.MyBatis*Repository` adapters.
+  The domain layer has zero `org.springframework.*` /
+  `org.apache.ibatis.*` / `io.spring.infrastructure.*` imports.
+- **Options considered:** JPA/Hibernate, Spring Data, MyBatis-Plus
+  `BaseMapper`. None adopted.
+- **Decision:** MyBatis 3 (`mybatis-spring-boot-starter:2.2.2`) with
+  hand-written XML statements under `src/main/resources/mapper/*.xml`.
+  Hexagonal port/adapter wiring keeps the domain framework-free.
+- **Consequences:** Every SQL lives in XML — `@Select`/`@Insert`/`@Update`/`@Delete`
+  annotations are forbidden. New aggregates require both a
+  `core.{aggregate}.{Aggregate}Repository` port AND a
+  `MyBatis{Aggregate}Repository` adapter; introducing a JPA repository would
+  split the persistence model.
 ```
 
-Pass 4 заполняет `decision-log.md` архитектурными решениями, извлечёнными из `pass2-merged.json`, чтобы будущие сессии помнили *почему* кодовая база выглядит так, а не только *как* она выглядит.
+Pass 4 заранее засевает `decision-log.md` архитектурными решениями из `pass2-merged.json`. Так в следующих сессиях видно не только _как_ устроен код, но и _почему_ он устроен именно так. Альтернативы («JPA/Hibernate», «MyBatis-Plus») и их последствия — прямо из блока зависимостей `build.gradle`.
 
 </details>
 
 ---
 
-## Quick Start
+## Протестировано на
+
+ClaudeOS-Core поставляется с эталонными бенчмарками на реальных open-source проектах. Если вы запускали инструмент на публичном репозитории, [откройте issue](https://github.com/claudeos-core/claudeos-core/issues), и мы добавим запись в эту таблицу.
+
+| Проект | Стек | Scanned → Generated | Статус |
+|---|---|---|---|
+| [`spring-boot-realworld-example-app`](https://github.com/gothinkster/spring-boot-realworld-example-app) | Java 11 · Spring Boot 2.6 · MyBatis · SQLite | 187 → 75 files | ✅ все 5 валидаторов прошли |
+
+---
+
+## Быстрый старт
 
-**Предварительные требования:** Node.js 18+, [Claude Code](https://docs.anthropic.com/en/docs/claude-code) установлен и аутентифицирован.
+**Что нужно заранее:** Node.js 18+, установленный и авторизованный [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
 
 ```bash
 # 1. Перейдите в корень проекта
 cd my-spring-boot-project
 
-# 2. Запустите init (анализирует код и просит Claude написать rules)
+# 2. Запустите init (разбирает код и поручает Claude написать правила)
 npx claudeos-core init
 
-# 3. Готово. Откройте Claude Code и начните кодить — rules уже загружены.
+# 3. Готово. Открывайте Claude Code и работайте — правила уже подгружены.
 ```
 
-**Что вы получаете** после завершения `init`:
+После того как `init` отработает, в проекте окажется примерно следующее:
 
 ```
 your-project/
 ├── .claude/
-│   └── rules/                    ← Claude Code загружает автоматически
-│       ├── 00.core/              (общие rules — именование, архитектура)
-│       ├── 10.backend/           (backend stack rules, если есть)
-│       ├── 20.frontend/          (frontend stack rules, если есть)
-│       ├── 30.security-db/       (конвенции безопасности и БД)
+│   └── rules/                    ← Подгружается Claude Code автоматически
+│       ├── 00.core/              (общие правила — нейминг, архитектура)
+│       ├── 10.backend/           (правила бэкенд-стека, если есть)
+│       ├── 20.frontend/          (правила фронтенд-стека, если есть)
+│       ├── 30.security-db/       (соглашения по безопасности и БД)
 │       ├── 40.infra/             (env, логирование, CI/CD)
-│       ├── 50.sync/              (напоминания о синхронизации документации — rules only)
-│       ├── 60.memory/            (memory rules — Pass 4, rules only)
-│       ├── 70.domains/{type}/    (rules по доменам, type = backend|frontend)
-│       └── 80.verification/      (стратегия тестирования + напоминания о верификации сборки)
+│       ├── 50.sync/              (напоминания о синхронизации документации — только rules)
+│       ├── 60.memory/            (правила памяти — Pass 4, только rules)
+│       ├── 70.domains/{type}/    (правила по доменам, type = backend|frontend)
+│       └── 80.verification/      (стратегия тестирования + напоминания о проверке сборки)
 ├── claudeos-core/
-│   ├── standard/                 ← Справочные документы (зеркалят структуру категорий)
-│   │   ├── 00.core/              (обзор проекта, архитектура, именование)
-│   │   ├── 10.backend/           (backend reference — если backend stack)
-│   │   ├── 20.frontend/          (frontend reference — если frontend stack)
-│   │   ├── 30.security-db/       (security & DB reference)
-│   │   ├── 40.infra/             (env / логирование / CI-CD reference)
-│   │   ├── 70.domains/{type}/    (reference по доменам)
-│   │   ├── 80.verification/      (build / startup / testing reference — standard only)
-│   │   └── 90.optional/          (специфика стека — standard only)
-│   ├── skills/                   (повторно используемые паттерны, которые Claude может применить)
-│   ├── guide/                    (how-to гайды для типовых задач)
+│   ├── standard/                 ← Справочные документы (структура категорий зеркалит rules)
+│   │   ├── 00.core/              (обзор проекта, архитектура, нейминг)
+│   │   ├── 10.backend/           (справка по бэкенду — если есть бэкенд-стек)
+│   │   ├── 20.frontend/          (справка по фронтенду — если есть фронтенд-стек)
+│   │   ├── 30.security-db/       (справка по безопасности и БД)
+│   │   ├── 40.infra/             (справка по env / логированию / CI-CD)
+│   │   ├── 70.domains/{type}/    (справка по доменам)
+│   │   ├── 80.verification/      (справка по сборке / запуску / тестам — только standard)
+│   │   └── 90.optional/          (стек-специфичные дополнения — только standard)
+│   ├── skills/                   (повторно используемые паттерны для Claude)
+│   ├── guide/                    (how-to для типичных задач)
 │   ├── database/                 (обзор схемы, гайд по миграциям)
-│   ├── mcp-guide/                (заметки по интеграции MCP)
+│   ├── mcp-guide/                (заметки по интеграции с MCP)
 │   └── memory/                   (decision log, failure patterns, compaction)
 └── CLAUDE.md                     (индекс, который Claude читает первым)
 ```
 
-Категории, разделяющие одинаковый числовой prefix между `rules/` и `standard/`, представляют одну и ту же концептуальную область (например, `10.backend` rules ↔ `10.backend` standards). Категории только-для-rules: `50.sync` (напоминания о синхронизации документации) и `60.memory` (Pass 4 memory). Категория только-для-standard: `90.optional` (специфика стека без принуждения). Все остальные prefix (`00`, `10`, `20`, `30`, `40`, `70`, `80`) присутствуют И в `rules/`, И в `standard/`. Теперь Claude Code знает ваш проект.
+Категории с одним и тем же числовым префиксом в `rules/` и `standard/` относятся к одной теме (например, правила `10.backend` ↔ стандарты `10.backend`). Только в rules живут `50.sync` (напоминания о синхронизации документации) и `60.memory` (память Pass 4). Только в standard — `90.optional` (стек-специфичные материалы без принудительного применения). Остальные префиксы (`00`, `10`, `20`, `30`, `40`, `70`, `80`) есть и там, и там. С этого момента Claude Code знает проект.
 
 ---
 
-## Кому это подходит?
+## Кому это нужно?
 
-| Если вы... | Это поможет вам... |
+| Вы... | Какую боль это снимает |
 |---|---|
-| **Соло-разработчик**, начинающий новый проект с Claude Code | Полностью пропустить фазу "учим Claude нашим конвенциям" |
-| **Тимлид**, поддерживающий общие стандарты | Автоматизировать рутину поддержания `.claude/rules/` в актуальном состоянии |
-| **Уже использующий Claude Code**, но устал править генерируемый код | Заставить Claude следовать ВАШИМ паттернам, а не "в целом хорошим" |
+| **Соло-разработчик**, начинающий новый проект на Claude Code | «Объяснять Claude свои соглашения каждую сессию» — больше не надо. `CLAUDE.md` и `.claude/rules/` из 8 категорий собираются за один проход. |
+| **Тимлид**, отвечающий за общие стандарты в нескольких репозиториях | Правила в `.claude/rules/` устаревают, как только переименовываются пакеты, меняются ORM или обёртки ответов. ClaudeOS-Core пересобирает их детерминированно: на одном входе всегда побайтово одинаковый выход, поэтому в diff нет шума. |
+| **Уже использует Claude Code**, но устал чинить сгенерированный код | Не та обёртка ответа, не та раскладка пакетов, JPA вместо MyBatis, `try/catch` россыпью при том, что в проекте есть централизованный middleware. Сканер достаёт ваши настоящие соглашения, а каждый проход Claude работает только в рамках явного allowlist путей. |
+| **Подключается к новому репозиторию** (готовый проект, выход в команду) | Запустите `init` — и получите живую карту архитектуры: таблицу стека в CLAUDE.md, правила по слоям с примерами ✅/❌, decision log с ответом на вопрос «почему» по ключевым решениям (JPA vs MyBatis, REST vs GraphQL и т. д.). Прочитать пять файлов быстрее, чем пять тысяч исходников. |
+| **Пишет на корейском, японском, китайском или ещё на 7 языках** | Большинство генераторов правил для Claude Code умеют только в английский. ClaudeOS-Core выпускает полный комплект на **10 языках** (`en/ko/ja/zh-CN/es/vi/hi/ru/fr/de`) и применяет одинаковую структурную проверку независимо от языка вывода — `claude-md-validator` выдаёт один и тот же вердикт на всех. |
+| **Работает с монорепозиторием** (Turborepo, pnpm/yarn workspaces, Lerna) | За один запуск разбираются и бэкенд, и фронтенд, причём с отдельными промптами. Каталоги `apps/*/` и `packages/*/` обходятся автоматически, а правила по стекам складываются в `70.domains/{type}/`. |
+| **Контрибьютит в OSS или экспериментирует** | Результат удобно класть под gitignore: `claudeos-core/` — это локальная рабочая директория, а в репозиторий нужно отправлять только `CLAUDE.md` и `.claude/`. После прерывания запуск можно продолжить, повторный запуск безопасен (ваши ручные правки в правилах сохраняются без `--force`). |
 
-**Не подходит, если:** вы хотите универсальный preset bundle из agents/skills/rules, который работает с первого дня без шага сканирования (см. [docs/ru/comparison.md](docs/ru/comparison.md) — что под какие задачи подходит), либо ваш проект пока не вписывается в один из [поддерживаемых стеков](#supported-stacks).
+**Скорее не подойдёт, если:** хочется готовый универсальный набор агентов, навыков и правил, который работает с первого дня без шага сканирования (что для каких задач подходит — см. [docs/ru/comparison.md](docs/ru/comparison.md)); ваш проект пока не попадает ни в один из [поддерживаемых стеков](#supported-stacks); нужен только один файл `CLAUDE.md` (тогда хватает встроенного `claude /init`, ставить ещё один инструмент незачем).
 
 ---
 
 ## Как это работает?
 
-ClaudeOS-Core инвертирует обычный workflow Claude Code:
+ClaudeOS-Core переворачивает привычный сценарий работы с Claude Code:
 
 ```
-Обычно:  Вы описываете проект → Claude угадывает ваш стек → Claude пишет docs
-Здесь:   Код читает ваш стек → Код передаёт подтверждённые факты Claude → Claude пишет docs из фактов
+Обычно:    Вы описываете проект   → Claude угадывает стек     → Claude пишет документацию
+Здесь:     Код читает ваш стек    → Код передаёт Claude факты → Claude пишет документацию по фактам
 ```
 
-Ключевая идея: **Node.js scanner сначала читает ваш исходный код** (детерминированно, без AI), а затем 4-pass конвейер Claude пишет документацию, ограниченную тем, что обнаружил сканер. Claude не может выдумать пути или фреймворки, которых на самом деле нет в вашем коде.
+Пайплайн состоит из **трёх стадий**: детерминированный код стоит и до LLM, и после неё.
+
+**1. Step A — Scanner (детерминированно, без LLM).** Сканер на Node.js обходит корень проекта, читает `package.json`, `build.gradle`, `pom.xml`, `pyproject.toml`, разбирает файлы `.env*` (чувствительные переменные `PASSWORD/SECRET/TOKEN/JWT_SECRET/...` при этом редактируются), классифицирует архитектурный паттерн (5 паттернов Java A/B/C/D/E, Kotlin CQRS / multi-module, Next.js App vs Pages Router, FSD, components-pattern), находит домены и собирает явный allowlist путей всех существующих исходных файлов. На выходе — `project-analysis.json`, единый источник истины для всех последующих шагов.
+
+**2. Step B — четырёхпроходный пайплайн на Claude (опирается на факты из Step A).**
+- **Pass 1** читает по группе доменов представительные файлы и достаёт по 50–100 соглашений на домен: обёртки ответов, библиотеки логирования, обработку ошибок, нейминг, паттерны тестов. Запускается по разу на каждую группу доменов (`max 4 domains, 40 files per group`), поэтому контекст не переполняется.
+- **Pass 2** сводит результаты по доменам в общую картину проекта и при расхождениях оставляет преобладающее соглашение.
+- **Pass 3** пишет `CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, навыки и руководства. Работа разбита на этапы (`3a` facts → `3b-core/3b-N` rules+standards → `3c-core/3c-N` skills+guides → `3d-aux` database+mcp-guide), благодаря чему каждый промпт укладывается в окно контекста LLM, даже когда `pass2-merged.json` получился крупным. Если доменов 16 и больше, 3b/3c дополнительно дробятся на батчи по 15 доменов.
+- **Pass 4** заполняет L4-слой памяти (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`) и добавляет универсальные scaffold-правила. При этом Pass 4 **не имеет права трогать `CLAUDE.md`**: за этот файл отвечает Section 8 из Pass 3.
+
+**3. Step C — Verification (детерминированно, без LLM).** Результат проверяют пять валидаторов:
+- `claude-md-validator` — 25 структурных проверок `CLAUDE.md` (8 секций, количество H3/H4, уникальность memory-файлов, инвариант канонических заголовков T1). Не зависит от языка: вердикт одинаковый при любом `--lang`.
+- `content-validator` — 10 контентных проверок, включая верификацию упоминаемых путей (`STALE_PATH` ловит выдуманные ссылки на `src/...`) и обнаружение дрейфа MANIFEST.
+- `pass-json-validator` — корректность JSON выходов Pass 1/2/3/4 и количество секций с учётом стека.
+- `plan-validator` — соответствие плана и состояния диска (легаси, начиная с v2.1.0 практически no-op).
+- `sync-checker` — соответствие диска и регистраций в `sync-map.json` по 7 отслеживаемым каталогам.
+
+Уровней важности три (`fail` / `warn` / `advisory`), поэтому предупреждения никогда не блокируют CI из-за галлюцинаций LLM, которые легко поправить руками.
 
-Полное описание архитектуры см. в [docs/ru/architecture.md](docs/ru/architecture.md).
+Главный инвариант, на котором всё держится: **Claude может ссылаться только на пути, реально существующие в коде**, потому что на вход ему уходит конечный allowlist из Step A. Если LLM всё-таки попытается что-то выдумать (редко, но на отдельных запусках случается), Step C это перехватит ещё до того, как документация дойдёт до пользователя.
+
+Подробности по каждому проходу, resume на маркерах, обходной механизм staged-rules для блокировки записи в `.claude/` со стороны Claude Code и внутренности детектора стеков — в [docs/ru/architecture.md](docs/ru/architecture.md).
 
 ---
 
 ## Supported Stacks
 
-12 стеков, автоматически определяемых по файлам вашего проекта:
+12 стеков, которые определяются автоматически по файлам проекта:
 
 **Backend:** Java/Spring Boot · Kotlin/Spring Boot · Node/Express · Node/Fastify · Node/NestJS · Python/Django · Python/FastAPI · Python/Flask
 
 **Frontend:** Node/Next.js · Node/Vite · Angular · Vue/Nuxt
 
-Multi-stack проекты (например, Spring Boot backend + Next.js frontend) работают «из коробки».
+Многостековые проекты (например, Spring Boot на бэкенде и Next.js на фронтенде) поддерживаются из коробки.
 
-Правила обнаружения и то, что извлекает каждый сканер, см. в [docs/ru/stacks.md](docs/ru/stacks.md).
+Правила детекции и то, что вытаскивает каждый сканер, описаны в [docs/ru/stacks.md](docs/ru/stacks.md).
 
 ---
 
-## Повседневный workflow
+## Ежедневный рабочий процесс
 
-Три команды покрывают ~95% использования:
+Для примерно 95% случаев хватает трёх команд:
 
 ```bash
-# Первый раз на проекте
+# Первый запуск на проекте
 npx claudeos-core init
 
-# После того как вы вручную отредактировали standards или rules
+# После ручных правок в стандартах или правилах
 npx claudeos-core lint
 
-# Health-check (запускайте перед коммитом или в CI)
+# Health-check (перед коммитом или в CI)
 npx claudeos-core health
 ```
 
-Ещё две — для обслуживания memory layer:
-
-```bash
-# Компактация лога failure-patterns (запускайте периодически)
-npx claudeos-core memory compact
-
-# Продвижение частых failure pattern в предложенные rules
-npx claudeos-core memory propose-rules
-```
-
-Полные опции каждой команды см. в [docs/ru/commands.md](docs/ru/commands.md).
+Полный список опций для каждой команды смотрите в [docs/ru/commands.md](docs/ru/commands.md). Команды слоя памяти (`memory compact`, `memory propose-rules`) разобраны ниже, в разделе [Memory Layer](#memory-layer-опционально-для-долгосрочных-проектов).
 
 ---
 
-## Чем это отличается
+## В чём отличие
 
-Большинство инструментов документации Claude Code генерируют по описанию (вы рассказываете инструменту, инструмент рассказывает Claude). ClaudeOS-Core генерирует из вашего реального исходного кода (инструмент читает, инструмент сообщает Claude, что подтверждено, Claude пишет только подтверждённое).
+Большинство инструментов документации для Claude Code исходят из вашего описания: вы рассказываете инструменту, инструмент пересказывает Claude. ClaudeOS-Core идёт от исходного кода: инструмент читает код, передаёт Claude уже подтверждённые факты, а Claude пишет только то, что подтверждено.
 
-Три конкретных следствия:
+На практике это даёт три конкретных эффекта:
 
-1. **Детерминированное обнаружение стека.** Тот же проект + тот же код = тот же вывод. Никакого «Claude в этот раз бросил кубик иначе».
-2. **Никаких выдуманных путей.** Промпт Pass 3 явно перечисляет каждый разрешённый путь к исходникам; Claude не может процитировать несуществующий путь.
-3. **Multi-stack-aware.** Backend и frontend домены используют разные analysis prompts в одном запуске.
+1. **Детерминированная детекция стека.** Тот же проект и тот же код всегда дают тот же результат. Никаких «в этот раз Claude как-то иначе всё интерпретировал».
+2. **Выдуманных путей не появляется.** В промпте Pass 3 явно перечислены все разрешённые пути в исходниках, поэтому Claude не может сослаться на то, чего нет.
+3. **Учёт нескольких стеков сразу.** В рамках одного запуска бэкенд- и фронтенд-домены анализируются разными промптами.
 
-Бок о бок сравнение scope с другими инструментами см. в [docs/ru/comparison.md](docs/ru/comparison.md). Сравнение про **что делает каждый инструмент**, а не **что лучше** — большинство дополняют друг друга.
+Сравнение по охвату с другими инструментами есть в [docs/ru/comparison.md](docs/ru/comparison.md). Это сравнение про то, **что делает каждый инструмент**, а не про то, **какой из них лучше**: в большинстве случаев они дополняют друг друга.
 
 ---
 
-## Верификация (post-generation)
+## Проверка (после генерации)
 
-После того как Claude напишет docs, код их проверяет. Пять отдельных validator:
+Когда Claude закончил писать документацию, за дело снова берётся код и проверяет результат. Пять независимых валидаторов:
 
-| Validator | Что проверяет | Запускается через |
+| Валидатор | Что проверяет | Кем запускается |
 |---|---|---|
-| `claude-md-validator` | Структурные инварианты CLAUDE.md (8 sections, language-invariant) | `claudeos-core lint` |
-| `content-validator` | Реальное существование заявленных путей; согласованность manifest | `health` (advisory) |
-| `pass-json-validator` | Выводы Pass 1 / 2 / 3 / 4 — well-formed JSON | `health` (warn) |
-| `plan-validator` | Сохранённый plan совпадает с тем, что на диске | `health` (fail-on-error) |
-| `sync-checker` | Файлы на диске совпадают с регистрациями `sync-map.json` (детекция orphaned/unregistered) | `health` (fail-on-error) |
+| `claude-md-validator` | Структурные инварианты CLAUDE.md (8 секций, не зависит от языка) | `claudeos-core lint` |
+| `content-validator` | Реальное существование упоминаемых путей и согласованность manifest | `health` (advisory) |
+| `pass-json-validator` | Корректность JSON выходов Pass 1 / 2 / 3 / 4 | `health` (warn) |
+| `plan-validator` | Соответствие сохранённого плана состоянию диска | `health` (fail-on-error) |
+| `sync-checker` | Соответствие файлов на диске записям в `sync-map.json` (поиск orphaned/unregistered) | `health` (fail-on-error) |
 
-`health-checker` оркестрирует четыре runtime-validator с трёхуровневой severity (fail / warn / advisory) и завершается с подходящим кодом для CI. `claude-md-validator` запускается отдельно через команду `lint`, поскольку структурный drift — это сигнал переинициализации, а не мягкое предупреждение. Запускайте в любой момент:
+Четыре runtime-валидатора оркестрирует `health-checker` с тремя уровнями важности (fail / warn / advisory), а наружу отдаётся exit-код, удобный для CI. `claude-md-validator` вынесен в отдельную команду `lint`: структурный сдвиг — это сигнал к re-init, а не мягкое предупреждение. Запустить можно в любой момент:
 
 ```bash
 npx claudeos-core health
 ```
 
-Подробное описание проверок каждого validator см. в [docs/ru/verification.md](docs/ru/verification.md).
+Подробный список проверок каждого валидатора — в [docs/ru/verification.md](docs/ru/verification.md).
 
 ---
 
-## Memory Layer (опционально, для долгоживущих проектов)
+## Memory Layer (опционально, для долгосрочных проектов)
 
-Начиная с v2.0, ClaudeOS-Core пишет папку `claudeos-core/memory/` с четырьмя файлами:
+Кроме основного пайплайна, ClaudeOS-Core поднимает каталог `claudeos-core/memory/` — для проектов, где контекст должен жить дольше одной сессии. Слой опциональный: если хватает `CLAUDE.md` и правил, его можно спокойно игнорировать.
 
-- `decision-log.md` — append-only «почему мы выбрали X вместо Y»
-- `failure-patterns.md` — повторяющиеся ошибки с оценками frequency/importance
-- `compaction.md` — как memory автоматически компактируется со временем
-- `auto-rule-update.md` — паттерны, которые должны стать новыми rules
+Внутри четыре файла, и все их пишет Pass 4:
 
-Можно запустить `npx claudeos-core memory propose-rules`, чтобы попросить Claude изучить недавние failure patterns и предложить новые rules.
+- `decision-log.md` — append-only журнал «почему выбрали X, а не Y»; засевается из `pass2-merged.json`.
+- `failure-patterns.md` — повторяющиеся ошибки с оценками frequency / importance.
+- `compaction.md` — описание того, как память автоматически уплотняется со временем.
+- `auto-rule-update.md` — паттерны, которые стоит превратить в новые правила.
 
-Модель memory и жизненный цикл см. в [docs/ru/memory-layer.md](docs/ru/memory-layer.md).
+Поддерживать слой со временем помогают две команды:
+
+```bash
+# Уплотнить лог failure-patterns (запускайте периодически)
+npx claudeos-core memory compact
+
+# Превратить часто встречающиеся failure-паттерны в предложенные правила
+npx claudeos-core memory propose-rules
+```
+
+Модель памяти и её жизненный цикл подробно описаны в [docs/ru/memory-layer.md](docs/ru/memory-layer.md).
 
 ---
 
 ## FAQ
 
-**В: Нужен ли мне Claude API ключ?**
-О: Нет. ClaudeOS-Core использует ваш существующий Claude Code — он отправляет промпты в `claude -p` на вашей машине. Никаких дополнительных аккаунтов.
+**Q: Нужен ли API-ключ Claude?**
+A: Нет. ClaudeOS-Core использует уже установленный Claude Code и просто отправляет промпты в `claude -p` на вашей машине. Дополнительные аккаунты не нужны.
 
-**В: Перезапишет ли это мой существующий CLAUDE.md или `.claude/rules/`?**
-О: Первый запуск на свежем проекте: создаёт. Перезапуск без `--force` сохраняет ваши правки — pass-маркеры предыдущего запуска обнаруживаются, и pass-ы пропускаются. Перезапуск с `--force` стирает и регенерирует всё (ваши правки теряются — в этом и смысл `--force`). См. [docs/ru/safety.md](docs/ru/safety.md).
+**Q: Перезапишет ли инструмент уже существующий CLAUDE.md или `.claude/rules/`?**
+A: На чистом проекте создаст с нуля. При повторном запуске без `--force` правки сохраняются: инструмент находит маркеры предыдущих проходов и пропускает их. С `--force` всё стирается и собирается заново — правки исчезают, в этом и весь смысл флага. Подробнее — в [docs/ru/safety.md](docs/ru/safety.md).
 
-**В: Мой стек не поддерживается. Можно добавить?**
-О: Да. Новый стек требует ~3 prompt-шаблона + domain scanner. См. [CONTRIBUTING.md](CONTRIBUTING.md) — гайд из 8 шагов.
+**Q: Моего стека нет в списке. Можно добавить свой?**
+A: Можно. На новый стек обычно нужны примерно три шаблона промптов и доменный сканер. Пошаговое руководство из 8 шагов есть в [CONTRIBUTING.md](CONTRIBUTING.md).
 
-**В: Как сгенерировать docs на корейском (или другом языке)?**
-О: `npx claudeos-core init --lang ko`. Поддерживается 10 языков: en, ko, ja, zh-CN, es, vi, hi, ru, fr, de.
+**Q: Как сгенерировать документацию на русском (или другом языке)?**
+A: `npx claudeos-core init --lang ru`. Поддерживается 10 языков: en, ko, ja, zh-CN, es, vi, hi, ru, fr, de.
 
-**В: Работает ли это с monorepo?**
-О: Да — Turborepo (`turbo.json`), pnpm workspaces (`pnpm-workspace.yaml`), Lerna (`lerna.json`) и npm/yarn workspaces (`package.json#workspaces`) определяются stack-detector. Каждое приложение получает собственный анализ. Другие layout monorepo (например, NX) специально не определяются, но универсальные паттерны `apps/*/` и `packages/*/` всё равно подбираются per-stack сканерами.
+**Q: Работает ли это с монорепозиториями?**
+A: Да. Stack-detector распознаёт Turborepo (`turbo.json`), pnpm workspaces (`pnpm-workspace.yaml`), Lerna (`lerna.json`) и npm/yarn workspaces (`package.json#workspaces`); каждое приложение получает собственный анализ. Другие раскладки монорепо (например, NX) отдельно не детектируются, но привычные `apps/*/` и `packages/*/` стек-сканеры подхватят и так.
+
+**Q: Что делать, если Claude Code сгенерировал правила, с которыми я не согласен?**
+A: Правьте прямо в файлах. Потом запустите `npx claudeos-core lint` — он проверит, что структура CLAUDE.md осталась валидной. Правки переживут последующие запуски `init` без `--force`: механизм resume пропускает проходы, у которых уже есть маркеры.
+
+**Q: Где сообщать о багах?**
+A: В [GitHub Issues](https://github.com/claudeos-core/claudeos-core/issues). Вопросы безопасности — см. [SECURITY.md](SECURITY.md).
+
+---
 
-**В: Что, если Claude Code сгенерирует rules, с которыми я не согласен?**
-О: Редактируйте напрямую. Затем запустите `npx claudeos-core lint`, чтобы убедиться, что CLAUDE.md по-прежнему структурно валиден. Ваши правки сохраняются при последующих запусках `init` (без `--force`) — механизм resume пропускает pass-ы, у которых есть маркеры.
+## Если это сэкономило вам время
 
-**В: Куда сообщать о багах?**
-О: [GitHub Issues](https://github.com/claudeos-core/claudeos-core/issues). По вопросам безопасности — [SECURITY.md](SECURITY.md).
+⭐ на GitHub помогает проекту оставаться заметным и облегчает другим разработчикам его поиск. Issues, PR и шаблоны под новые стеки — приветствуются, подробности в [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ---
 
 ## Документация
 
-| Тема | Читать |
+| Тема | Где почитать |
 |---|---|
-| Как работает 4-pass конвейер (глубже, чем диаграмма) | [docs/ru/architecture.md](docs/ru/architecture.md) |
-| Визуальные диаграммы (Mermaid) архитектуры | [docs/ru/diagrams.md](docs/ru/diagrams.md) |
-| Обнаружение стека — что ищет каждый сканер | [docs/ru/stacks.md](docs/ru/stacks.md) |
-| Memory layer — decision logs и failure patterns | [docs/ru/memory-layer.md](docs/ru/memory-layer.md) |
-| Все 5 validator подробно | [docs/ru/verification.md](docs/ru/verification.md) |
-| Все CLI-команды и опции | [docs/ru/commands.md](docs/ru/commands.md) |
+| Как устроен 4-проходный пайплайн (глубже, чем диаграмма) | [docs/ru/architecture.md](docs/ru/architecture.md) |
+| Визуальные диаграммы архитектуры (Mermaid) | [docs/ru/diagrams.md](docs/ru/diagrams.md) |
+| Детекция стеков — на что смотрит каждый сканер | [docs/ru/stacks.md](docs/ru/stacks.md) |
+| Слой памяти — decision log и failure patterns | [docs/ru/memory-layer.md](docs/ru/memory-layer.md) |
+| Все 5 валидаторов в деталях | [docs/ru/verification.md](docs/ru/verification.md) |
+| Все CLI-команды и их опции | [docs/ru/commands.md](docs/ru/commands.md) |
 | Ручная установка (без `npx`) | [docs/ru/manual-installation.md](docs/ru/manual-installation.md) |
-| Override-ы сканера — `.claudeos-scan.json` | [docs/ru/advanced-config.md](docs/ru/advanced-config.md) |
-| Безопасность: что сохраняется при re-init | [docs/ru/safety.md](docs/ru/safety.md) |
-| Сравнение со схожими инструментами (scope, не качество) | [docs/ru/comparison.md](docs/ru/comparison.md) |
+| Переопределения сканера — `.claudeos-scan.json` | [docs/ru/advanced-config.md](docs/ru/advanced-config.md) |
+| Безопасность: что сохраняется при повторном init | [docs/ru/safety.md](docs/ru/safety.md) |
+| Сравнение со схожими инструментами (по охвату, не по качеству) | [docs/ru/comparison.md](docs/ru/comparison.md) |
 | Ошибки и восстановление | [docs/ru/troubleshooting.md](docs/ru/troubleshooting.md) |
 
 ---
 
-## Вклад в проект
+## Участие в проекте
 
-Вклад приветствуется — добавление поддержки стека, улучшение промптов, исправление багов. См. [CONTRIBUTING.md](CONTRIBUTING.md).
+Контрибьюции приветствуются: добавление новых стеков, улучшение промптов, фиксы багов. Подробности в [CONTRIBUTING.md](CONTRIBUTING.md).
 
-Кодекс поведения и политику безопасности см. в [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) и [SECURITY.md](SECURITY.md).
+Кодекс поведения и политика безопасности — [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) и [SECURITY.md](SECURITY.md).
 
 ## Лицензия
 
-[ISC](LICENSE) — свободно для любого использования, включая коммерческое.
+[ISC License](LICENSE). Свободно для любого использования, включая коммерческое. © 2025–2026 ClaudeOS-Core contributors.
 
 ---
 
-<sub>Создано с заботой [@claudeos-core](https://github.com/claudeos-core). Если это сэкономило вам время, ⭐ на GitHub помогает сохранять видимость проекта.</sub>
+<sub>Поддерживается командой [claudeos-core](https://github.com/claudeos-core). Issues и PR — на <https://github.com/claudeos-core/claudeos-core>.</sub>