claudeos-core 2.4.1 → 2.4.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +17 -0
- package/README.de.md +172 -174
- package/README.es.md +161 -163
- package/README.fr.md +159 -161
- package/README.hi.md +166 -168
- package/README.ja.md +166 -168
- package/README.ko.md +139 -141
- package/README.md +55 -57
- package/README.ru.md +173 -175
- package/README.vi.md +169 -171
- package/README.zh-CN.md +168 -170
- package/package.json +1 -1
package/README.ru.md
CHANGED
|
@@ -7,58 +7,40 @@
|
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
[](https://www.npmjs.com/package/claudeos-core)
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
Детерминированный Node.js scanner сначала читает ваш код; затем 4-pass конвейер Claude пишет полный набор — `CLAUDE.md` + автоматически загружаемые `.claude/rules/` + standards + skills + L4 memory. 10 языков вывода, 5 post-generation validator-ов и явный path allowlist, не позволяющий LLM выдумывать файлы или фреймворки, отсутствующие в вашем коде.
|
|
13
|
-
|
|
14
|
-
Работает на [**12 стеках**](#supported-stacks) (включая monorepo) — одна команда `npx`, без конфигурации, resume-safe, идемпотентно.
|
|
10
|
+
**CLI-инструмент, который читает реальный исходный код вашего проекта и на его основе сам собирает `CLAUDE.md` и `.claude/rules/`. Внутри: сканер на Node.js, четырёхпроходный пайплайн на базе Claude и пять валидаторов. Поддерживаются 12 стеков и 10 языков, а пути, которых нет в коде, инструмент не выдумывает.**
|
|
15
11
|
|
|
16
12
|
```bash
|
|
17
13
|
npx claudeos-core init
|
|
18
14
|
```
|
|
19
15
|
|
|
16
|
+
Работает на [**12 стеках**](#supported-stacks), включая монорепозитории. Одна команда без конфигурации, безопасная при прерывании, идемпотентная при повторных запусках.
|
|
17
|
+
|
|
20
18
|
[🇺🇸 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)
|
|
21
19
|
|
|
22
20
|
---
|
|
23
21
|
|
|
24
|
-
## Что
|
|
25
|
-
|
|
26
|
-
Вы используете Claude Code. Он мощный, но каждая сессия начинается с нуля — у него нет памяти о том, как устроен _ваш_ проект. Поэтому он откатывается на «в целом хорошие» дефолты, которые редко совпадают с тем, что реально делает ваша команда:
|
|
22
|
+
## Что это?
|
|
27
23
|
|
|
28
|
-
|
|
29
|
-
- Ваша обёртка для ответов — `ApiResponse.ok()`, а Claude пишет `ResponseEntity.success()`.
|
|
30
|
-
- Ваши пакеты — layer-first (`controller/order/`), а Claude создаёт domain-first (`order/controller/`).
|
|
31
|
-
- Ваши ошибки идут через централизованный middleware, а Claude разбрасывает `try/catch` по каждому endpoint.
|
|
24
|
+
В каждой новой сессии Claude Code откатывается к дефолтам фреймворка. Команда сидит на **MyBatis**, а Claude всё равно пишет JPA. В коде обёртка `ApiResponse.ok()`, а Claude подставляет `ResponseEntity.success()`. Пакеты разложены по слоям, а Claude собирает структуру по доменам. Можно, конечно, написать `.claude/rules/` руками для каждого репозитория — только код развивается, и правила почти сразу отстают от реальности.
|
|
32
25
|
|
|
33
|
-
|
|
26
|
+
**ClaudeOS-Core пересобирает их предсказуемо, прямо из исходного кода проекта.** Сначала сканер на Node.js разбирает проект и вытаскивает стек, ORM, раскладку пакетов, реальные пути к файлам. Затем четырёхпроходный пайплайн на Claude пишет полный комплект документации: `CLAUDE.md`, автоматически подгружаемые `.claude/rules/`, стандарты, навыки. Всё это происходит строго внутри явного allowlist путей — за его пределы LLM выйти не может. И прежде чем результат окажется у вас, его проверяют пять валидаторов.
|
|
34
27
|
|
|
35
|
-
|
|
28
|
+
В итоге одинаковый вход даёт побайтово одинаковый выход на любом из 10 языков, а пути, которых нет в коде, в документации не появляются. Подробности — ниже, в разделе [В чём отличие](#в-чём-отличие).
|
|
36
29
|
|
|
37
|
-
|
|
38
|
-
- **`.claude/rules/`** — автоматически загружаемые rules по категориям (`00.core` / `10.backend` / `20.frontend` / `30.security-db` / `40.infra` / `60.memory` / `70.domains` / `80.verification`)
|
|
39
|
-
- **`claudeos-core/standard/`** — справочные документы («почему» за каждым rule)
|
|
40
|
-
- **`claudeos-core/skills/`** — переиспользуемые паттерны (CRUD scaffolding, шаблоны страниц)
|
|
41
|
-
- **`claudeos-core/memory/`** — decision log + failure patterns, растущие вместе с проектом
|
|
42
|
-
|
|
43
|
-
Поскольку scanner передаёт Claude явный path allowlist, LLM **не может выдумать файлы или фреймворки, которых нет в вашем коде**. Пять post-generation validator-ов (`claude-md-validator`, `content-validator`, `pass-json-validator`, `plan-validator`, `sync-checker`) проверяют вывод до отправки — language-invariant, поэтому одни и те же правила применяются независимо от того, генерируете ли вы на английском, русском или одном из 8 других языков.
|
|
44
|
-
|
|
45
|
-
```
|
|
46
|
-
До: Вы → Claude Code → "в целом хороший" код → ручные правки каждый раз
|
|
47
|
-
После: Вы → Claude Code → код, соответствующий ВАШЕМУ проекту → используйте как есть
|
|
48
|
-
```
|
|
30
|
+
Для долгоживущих проектов рядом разворачивается [Memory Layer](#memory-layer-опционально-для-долгосрочных-проектов).
|
|
49
31
|
|
|
50
32
|
---
|
|
51
33
|
|
|
52
|
-
##
|
|
34
|
+
## Посмотреть на реальном проекте
|
|
53
35
|
|
|
54
|
-
|
|
36
|
+
Прогнали на [`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 минуты**, все валидаторы зелёные ✅.
|
|
55
37
|
|
|
56
38
|
<p align="center">
|
|
57
39
|
<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">
|
|
58
40
|
</p>
|
|
59
41
|
|
|
60
42
|
<details>
|
|
61
|
-
<summary><strong
|
|
43
|
+
<summary><strong>Вывод терминала (текстовая версия для поиска и копирования)</strong></summary>
|
|
62
44
|
|
|
63
45
|
```text
|
|
64
46
|
╔════════════════════════════════════════════════════╗
|
|
@@ -93,18 +75,18 @@ npx claudeos-core init
|
|
|
93
75
|
[██████████░░░░░░░░░░] 50% (2/4)
|
|
94
76
|
|
|
95
77
|
[6] Pass 3 — Generating all files...
|
|
96
|
-
|
|
78
|
+
Pass 3 split mode (3a → 3b → 3c → 3d-aux)
|
|
97
79
|
✅ 3a complete (2m 57s) — pass3a-facts.md (187-path allowlist)
|
|
98
80
|
✅ 3b complete (18m 49s) — CLAUDE.md + 19 standards + 20 rules
|
|
99
81
|
✅ 3c complete (12m 35s) — 13 skills + 9 guides
|
|
100
82
|
✅ 3d-aux complete (3m 18s) — database/ + mcp-guide/
|
|
101
|
-
|
|
83
|
+
Pass 3 split complete: 4/4 stages successful
|
|
102
84
|
[███████████████░░░░░] 75% (3/4)
|
|
103
85
|
|
|
104
86
|
[7] Pass 4 — Memory scaffolding...
|
|
105
|
-
|
|
87
|
+
Pass 4 staged-rules: 6 rule files moved to .claude/rules/
|
|
106
88
|
✅ Pass 4 complete (5m)
|
|
107
|
-
|
|
89
|
+
Gap-fill: all 12 expected files already present
|
|
108
90
|
[████████████████████] 100% (4/4)
|
|
109
91
|
|
|
110
92
|
╔═══════════════════════════════════════╗
|
|
@@ -133,7 +115,7 @@ npx claudeos-core init
|
|
|
133
115
|
</details>
|
|
134
116
|
|
|
135
117
|
<details>
|
|
136
|
-
<summary><strong
|
|
118
|
+
<summary><strong>Что в итоге попадает в ваш <code>CLAUDE.md</code> (реальный фрагмент — Section 1 + 2)</strong></summary>
|
|
137
119
|
|
|
138
120
|
```markdown
|
|
139
121
|
# CLAUDE.md — spring-boot-realworld-example-app
|
|
@@ -142,7 +124,7 @@ npx claudeos-core init
|
|
|
142
124
|
> Java 11 + Spring Boot 2.6, exposing both REST and GraphQL endpoints
|
|
143
125
|
> over a hexagonal MyBatis persistence layer.
|
|
144
126
|
|
|
145
|
-
|
|
127
|
+
#### 1. Role Definition
|
|
146
128
|
|
|
147
129
|
As the senior developer for this repository, you are responsible for
|
|
148
130
|
writing, modifying, and reviewing code. Responses must be written in English.
|
|
@@ -150,7 +132,7 @@ A Java Spring Boot REST + GraphQL API server organized around a hexagonal
|
|
|
150
132
|
(ports & adapters) architecture, with a CQRS-lite read/write split inside
|
|
151
133
|
an XML-driven MyBatis persistence layer and JWT-based authentication.
|
|
152
134
|
|
|
153
|
-
|
|
135
|
+
#### 2. Project Overview
|
|
154
136
|
|
|
155
137
|
| Item | Value |
|
|
156
138
|
|---|---|
|
|
@@ -166,12 +148,12 @@ an XML-driven MyBatis persistence layer and JWT-based authentication.
|
|
|
166
148
|
| Test Stack | JUnit Jupiter 5, Mockito, AssertJ, rest-assured, spring-mock-mvc |
|
|
167
149
|
```
|
|
168
150
|
|
|
169
|
-
Каждое значение
|
|
151
|
+
Каждое значение в этой таблице — точные координаты зависимостей, имя файла `dev.db`, название миграции `V1__create_tables.sql`, пометка «no JPA» — сканер вычитал из `build.gradle`, `application.properties` и дерева исходников ещё до того, как Claude взялся за файл. Ничего не угадано.
|
|
170
152
|
|
|
171
153
|
</details>
|
|
172
154
|
|
|
173
155
|
<details>
|
|
174
|
-
<summary><strong
|
|
156
|
+
<summary><strong>Реальное автоматически подгружаемое правило (<code>.claude/rules/10.backend/01.controller-rules.md</code>)</strong></summary>
|
|
175
157
|
|
|
176
158
|
````markdown
|
|
177
159
|
---
|
|
@@ -179,9 +161,9 @@ paths:
|
|
|
179
161
|
- "**/*"
|
|
180
162
|
---
|
|
181
163
|
|
|
182
|
-
|
|
164
|
+
#### Controller Rules
|
|
183
165
|
|
|
184
|
-
|
|
166
|
+
##### REST (`io.spring.api.*`)
|
|
185
167
|
|
|
186
168
|
- Controllers are the SOLE response wrapper for HTTP — no aggregator/facade above them.
|
|
187
169
|
Return `ResponseEntity<?>` or a body Spring serializes via `JacksonCustomizations`.
|
|
@@ -194,13 +176,13 @@ paths:
|
|
|
194
176
|
- Let exceptions propagate to `io.spring.api.exception.CustomizeExceptionHandler`
|
|
195
177
|
(`@ControllerAdvice`). Do NOT `try/catch` business exceptions inside the controller.
|
|
196
178
|
|
|
197
|
-
|
|
179
|
+
##### GraphQL (`io.spring.graphql.*`)
|
|
198
180
|
|
|
199
181
|
- DGS components (`@DgsComponent`) are the sole GraphQL response wrappers.
|
|
200
182
|
Use `@DgsQuery` / `@DgsData` / `@DgsMutation`.
|
|
201
183
|
- Resolve the current user via `io.spring.graphql.SecurityUtil.getCurrentUser()`.
|
|
202
184
|
|
|
203
|
-
|
|
185
|
+
##### Examples
|
|
204
186
|
|
|
205
187
|
✅ Correct:
|
|
206
188
|
```java
|
|
@@ -228,15 +210,15 @@ public ResponseEntity<?> create(@RequestBody NewArticleParam p) {
|
|
|
228
210
|
```
|
|
229
211
|
````
|
|
230
212
|
|
|
231
|
-
|
|
213
|
+
Глоб `paths: ["**/*"]` означает, что Claude Code будет автоматически подтягивать это правило при редактировании любого файла в проекте. Имена классов, пакеты и обработчики исключений в правиле взяты прямо из просканированных исходников, поэтому в нём фигурируют реальные `CustomizeExceptionHandler` и `JacksonCustomizations` именно из этого проекта.
|
|
232
214
|
|
|
233
215
|
</details>
|
|
234
216
|
|
|
235
217
|
<details>
|
|
236
|
-
<summary><strong
|
|
218
|
+
<summary><strong>Сид автоматически сгенерированного <code>decision-log.md</code> (реальный фрагмент)</strong></summary>
|
|
237
219
|
|
|
238
220
|
```markdown
|
|
239
|
-
|
|
221
|
+
#### 2026-04-26 — Hexagonal ports & adapters with MyBatis-only persistence
|
|
240
222
|
|
|
241
223
|
- **Context:** `io.spring.core.*` exposes `*Repository` ports (e.g.,
|
|
242
224
|
`io.spring.core.article.ArticleRepository`) implemented by
|
|
@@ -255,260 +237,276 @@ Glob `paths: ["**/*"]` означает, что Claude Code автоматиче
|
|
|
255
237
|
split the persistence model.
|
|
256
238
|
```
|
|
257
239
|
|
|
258
|
-
Pass 4
|
|
240
|
+
Pass 4 заранее засевает `decision-log.md` архитектурными решениями из `pass2-merged.json`. Так в следующих сессиях видно не только _как_ устроен код, но и _почему_ он устроен именно так. Альтернативы («JPA/Hibernate», «MyBatis-Plus») и их последствия — прямо из блока зависимостей `build.gradle`.
|
|
259
241
|
|
|
260
242
|
</details>
|
|
261
243
|
|
|
262
244
|
---
|
|
263
245
|
|
|
264
|
-
##
|
|
246
|
+
## Протестировано на
|
|
265
247
|
|
|
266
|
-
|
|
248
|
+
ClaudeOS-Core поставляется с эталонными бенчмарками на реальных open-source проектах. Если вы запускали инструмент на публичном репозитории, [откройте issue](https://github.com/claudeos-core/claudeos-core/issues), и мы добавим запись в эту таблицу.
|
|
249
|
+
|
|
250
|
+
| Проект | Стек | Scanned → Generated | Статус |
|
|
251
|
+
|---|---|---|---|
|
|
252
|
+
| [`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 валидаторов прошли |
|
|
253
|
+
|
|
254
|
+
---
|
|
255
|
+
|
|
256
|
+
## Быстрый старт
|
|
257
|
+
|
|
258
|
+
**Что нужно заранее:** Node.js 18+, установленный и авторизованный [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
|
|
267
259
|
|
|
268
260
|
```bash
|
|
269
261
|
# 1. Перейдите в корень проекта
|
|
270
262
|
cd my-spring-boot-project
|
|
271
263
|
|
|
272
|
-
# 2. Запустите init (
|
|
264
|
+
# 2. Запустите init (разбирает код и поручает Claude написать правила)
|
|
273
265
|
npx claudeos-core init
|
|
274
266
|
|
|
275
|
-
# 3. Готово.
|
|
267
|
+
# 3. Готово. Открывайте Claude Code и работайте — правила уже подгружены.
|
|
276
268
|
```
|
|
277
269
|
|
|
278
|
-
|
|
270
|
+
После того как `init` отработает, в проекте окажется примерно следующее:
|
|
279
271
|
|
|
280
272
|
```
|
|
281
273
|
your-project/
|
|
282
274
|
├── .claude/
|
|
283
|
-
│ └── rules/ ← Claude Code
|
|
284
|
-
│ ├── 00.core/ (общие
|
|
285
|
-
│ ├── 10.backend/ (
|
|
286
|
-
│ ├── 20.frontend/ (
|
|
287
|
-
│ ├── 30.security-db/ (
|
|
275
|
+
│ └── rules/ ← Подгружается Claude Code автоматически
|
|
276
|
+
│ ├── 00.core/ (общие правила — нейминг, архитектура)
|
|
277
|
+
│ ├── 10.backend/ (правила бэкенд-стека, если есть)
|
|
278
|
+
│ ├── 20.frontend/ (правила фронтенд-стека, если есть)
|
|
279
|
+
│ ├── 30.security-db/ (соглашения по безопасности и БД)
|
|
288
280
|
│ ├── 40.infra/ (env, логирование, CI/CD)
|
|
289
|
-
│ ├── 50.sync/ (напоминания о синхронизации документации — rules
|
|
290
|
-
│ ├── 60.memory/ (
|
|
291
|
-
│ ├── 70.domains/{type}/ (
|
|
292
|
-
│ └── 80.verification/ (стратегия тестирования + напоминания о
|
|
281
|
+
│ ├── 50.sync/ (напоминания о синхронизации документации — только rules)
|
|
282
|
+
│ ├── 60.memory/ (правила памяти — Pass 4, только rules)
|
|
283
|
+
│ ├── 70.domains/{type}/ (правила по доменам, type = backend|frontend)
|
|
284
|
+
│ └── 80.verification/ (стратегия тестирования + напоминания о проверке сборки)
|
|
293
285
|
├── claudeos-core/
|
|
294
|
-
│ ├── standard/ ← Справочные документы (
|
|
295
|
-
│ │ ├── 00.core/ (обзор проекта, архитектура,
|
|
296
|
-
│ │ ├── 10.backend/ (
|
|
297
|
-
│ │ ├── 20.frontend/ (
|
|
298
|
-
│ │ ├── 30.security-db/ (
|
|
299
|
-
│ │ ├── 40.infra/ (env /
|
|
300
|
-
│ │ ├── 70.domains/{type}/ (
|
|
301
|
-
│ │ ├── 80.verification/ (
|
|
302
|
-
│ │ └── 90.optional/ (
|
|
303
|
-
│ ├── skills/ (повторно используемые
|
|
304
|
-
│ ├── guide/ (how-to
|
|
286
|
+
│ ├── standard/ ← Справочные документы (структура категорий зеркалит rules)
|
|
287
|
+
│ │ ├── 00.core/ (обзор проекта, архитектура, нейминг)
|
|
288
|
+
│ │ ├── 10.backend/ (справка по бэкенду — если есть бэкенд-стек)
|
|
289
|
+
│ │ ├── 20.frontend/ (справка по фронтенду — если есть фронтенд-стек)
|
|
290
|
+
│ │ ├── 30.security-db/ (справка по безопасности и БД)
|
|
291
|
+
│ │ ├── 40.infra/ (справка по env / логированию / CI-CD)
|
|
292
|
+
│ │ ├── 70.domains/{type}/ (справка по доменам)
|
|
293
|
+
│ │ ├── 80.verification/ (справка по сборке / запуску / тестам — только standard)
|
|
294
|
+
│ │ └── 90.optional/ (стек-специфичные дополнения — только standard)
|
|
295
|
+
│ ├── skills/ (повторно используемые паттерны для Claude)
|
|
296
|
+
│ ├── guide/ (how-to для типичных задач)
|
|
305
297
|
│ ├── database/ (обзор схемы, гайд по миграциям)
|
|
306
|
-
│ ├── mcp-guide/ (заметки по интеграции MCP)
|
|
298
|
+
│ ├── mcp-guide/ (заметки по интеграции с MCP)
|
|
307
299
|
│ └── memory/ (decision log, failure patterns, compaction)
|
|
308
300
|
└── CLAUDE.md (индекс, который Claude читает первым)
|
|
309
301
|
```
|
|
310
302
|
|
|
311
|
-
|
|
303
|
+
Категории с одним и тем же числовым префиксом в `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 знает проект.
|
|
312
304
|
|
|
313
305
|
---
|
|
314
306
|
|
|
315
|
-
## Кому это
|
|
307
|
+
## Кому это нужно?
|
|
316
308
|
|
|
317
|
-
|
|
|
309
|
+
| Вы... | Какую боль это снимает |
|
|
318
310
|
|---|---|
|
|
319
|
-
| **Соло-разработчик**, начинающий новый проект
|
|
320
|
-
| **Тимлид**,
|
|
321
|
-
| **Уже
|
|
322
|
-
|
|
|
323
|
-
|
|
|
324
|
-
|
|
|
325
|
-
|
|
|
311
|
+
| **Соло-разработчик**, начинающий новый проект на Claude Code | «Объяснять Claude свои соглашения каждую сессию» — больше не надо. `CLAUDE.md` и `.claude/rules/` из 8 категорий собираются за один проход. |
|
|
312
|
+
| **Тимлид**, отвечающий за общие стандарты в нескольких репозиториях | Правила в `.claude/rules/` устаревают, как только переименовываются пакеты, меняются ORM или обёртки ответов. ClaudeOS-Core пересобирает их детерминированно: на одном входе всегда побайтово одинаковый выход, поэтому в diff нет шума. |
|
|
313
|
+
| **Уже использует Claude Code**, но устал чинить сгенерированный код | Не та обёртка ответа, не та раскладка пакетов, JPA вместо MyBatis, `try/catch` россыпью при том, что в проекте есть централизованный middleware. Сканер достаёт ваши настоящие соглашения, а каждый проход Claude работает только в рамках явного allowlist путей. |
|
|
314
|
+
| **Подключается к новому репозиторию** (готовый проект, выход в команду) | Запустите `init` — и получите живую карту архитектуры: таблицу стека в CLAUDE.md, правила по слоям с примерами ✅/❌, decision log с ответом на вопрос «почему» по ключевым решениям (JPA vs MyBatis, REST vs GraphQL и т. д.). Прочитать пять файлов быстрее, чем пять тысяч исходников. |
|
|
315
|
+
| **Пишет на корейском, японском, китайском или ещё на 7 языках** | Большинство генераторов правил для Claude Code умеют только в английский. ClaudeOS-Core выпускает полный комплект на **10 языках** (`en/ko/ja/zh-CN/es/vi/hi/ru/fr/de`) и применяет одинаковую структурную проверку независимо от языка вывода — `claude-md-validator` выдаёт один и тот же вердикт на всех. |
|
|
316
|
+
| **Работает с монорепозиторием** (Turborepo, pnpm/yarn workspaces, Lerna) | За один запуск разбираются и бэкенд, и фронтенд, причём с отдельными промптами. Каталоги `apps/*/` и `packages/*/` обходятся автоматически, а правила по стекам складываются в `70.domains/{type}/`. |
|
|
317
|
+
| **Контрибьютит в OSS или экспериментирует** | Результат удобно класть под gitignore: `claudeos-core/` — это локальная рабочая директория, а в репозиторий нужно отправлять только `CLAUDE.md` и `.claude/`. После прерывания запуск можно продолжить, повторный запуск безопасен (ваши ручные правки в правилах сохраняются без `--force`). |
|
|
326
318
|
|
|
327
|
-
|
|
319
|
+
**Скорее не подойдёт, если:** хочется готовый универсальный набор агентов, навыков и правил, который работает с первого дня без шага сканирования (что для каких задач подходит — см. [docs/ru/comparison.md](docs/ru/comparison.md)); ваш проект пока не попадает ни в один из [поддерживаемых стеков](#supported-stacks); нужен только один файл `CLAUDE.md` (тогда хватает встроенного `claude /init`, ставить ещё один инструмент незачем).
|
|
328
320
|
|
|
329
321
|
---
|
|
330
322
|
|
|
331
323
|
## Как это работает?
|
|
332
324
|
|
|
333
|
-
ClaudeOS-Core
|
|
325
|
+
ClaudeOS-Core переворачивает привычный сценарий работы с Claude Code:
|
|
334
326
|
|
|
335
327
|
```
|
|
336
|
-
Обычно:
|
|
337
|
-
Здесь:
|
|
328
|
+
Обычно: Вы описываете проект → Claude угадывает стек → Claude пишет документацию
|
|
329
|
+
Здесь: Код читает ваш стек → Код передаёт Claude факты → Claude пишет документацию по фактам
|
|
338
330
|
```
|
|
339
331
|
|
|
340
|
-
|
|
332
|
+
Пайплайн состоит из **трёх стадий**: детерминированный код стоит и до LLM, и после неё.
|
|
341
333
|
|
|
342
|
-
**1.
|
|
334
|
+
**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`, единый источник истины для всех последующих шагов.
|
|
343
335
|
|
|
344
|
-
**2.
|
|
345
|
-
- **Pass 1** читает
|
|
346
|
-
- **Pass 2**
|
|
347
|
-
- **Pass 3** пишет `CLAUDE.md
|
|
348
|
-
- **Pass 4** заполняет L4
|
|
336
|
+
**2. Step B — четырёхпроходный пайплайн на Claude (опирается на факты из Step A).**
|
|
337
|
+
- **Pass 1** читает по группе доменов представительные файлы и достаёт по 50–100 соглашений на домен: обёртки ответов, библиотеки логирования, обработку ошибок, нейминг, паттерны тестов. Запускается по разу на каждую группу доменов (`max 4 domains, 40 files per group`), поэтому контекст не переполняется.
|
|
338
|
+
- **Pass 2** сводит результаты по доменам в общую картину проекта и при расхождениях оставляет преобладающее соглашение.
|
|
339
|
+
- **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 доменов.
|
|
340
|
+
- **Pass 4** заполняет L4-слой памяти (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`) и добавляет универсальные scaffold-правила. При этом Pass 4 **не имеет права трогать `CLAUDE.md`**: за этот файл отвечает Section 8 из Pass 3.
|
|
349
341
|
|
|
350
|
-
**3.
|
|
351
|
-
- `claude-md-validator` — 25 структурных проверок `CLAUDE.md` (8
|
|
352
|
-
- `content-validator` — 10
|
|
353
|
-
- `pass-json-validator` —
|
|
354
|
-
- `plan-validator` —
|
|
355
|
-
- `sync-checker` —
|
|
342
|
+
**3. Step C — Verification (детерминированно, без LLM).** Результат проверяют пять валидаторов:
|
|
343
|
+
- `claude-md-validator` — 25 структурных проверок `CLAUDE.md` (8 секций, количество H3/H4, уникальность memory-файлов, инвариант канонических заголовков T1). Не зависит от языка: вердикт одинаковый при любом `--lang`.
|
|
344
|
+
- `content-validator` — 10 контентных проверок, включая верификацию упоминаемых путей (`STALE_PATH` ловит выдуманные ссылки на `src/...`) и обнаружение дрейфа MANIFEST.
|
|
345
|
+
- `pass-json-validator` — корректность JSON выходов Pass 1/2/3/4 и количество секций с учётом стека.
|
|
346
|
+
- `plan-validator` — соответствие плана и состояния диска (легаси, начиная с v2.1.0 практически no-op).
|
|
347
|
+
- `sync-checker` — соответствие диска и регистраций в `sync-map.json` по 7 отслеживаемым каталогам.
|
|
356
348
|
|
|
357
|
-
|
|
349
|
+
Уровней важности три (`fail` / `warn` / `advisory`), поэтому предупреждения никогда не блокируют CI из-за галлюцинаций LLM, которые легко поправить руками.
|
|
358
350
|
|
|
359
|
-
|
|
351
|
+
Главный инвариант, на котором всё держится: **Claude может ссылаться только на пути, реально существующие в коде**, потому что на вход ему уходит конечный allowlist из Step A. Если LLM всё-таки попытается что-то выдумать (редко, но на отдельных запусках случается), Step C это перехватит ещё до того, как документация дойдёт до пользователя.
|
|
360
352
|
|
|
361
|
-
Подробности по
|
|
353
|
+
Подробности по каждому проходу, resume на маркерах, обходной механизм staged-rules для блокировки записи в `.claude/` со стороны Claude Code и внутренности детектора стеков — в [docs/ru/architecture.md](docs/ru/architecture.md).
|
|
362
354
|
|
|
363
355
|
---
|
|
364
356
|
|
|
365
357
|
## Supported Stacks
|
|
366
358
|
|
|
367
|
-
12 стеков, автоматически
|
|
359
|
+
12 стеков, которые определяются автоматически по файлам проекта:
|
|
368
360
|
|
|
369
361
|
**Backend:** Java/Spring Boot · Kotlin/Spring Boot · Node/Express · Node/Fastify · Node/NestJS · Python/Django · Python/FastAPI · Python/Flask
|
|
370
362
|
|
|
371
363
|
**Frontend:** Node/Next.js · Node/Vite · Angular · Vue/Nuxt
|
|
372
364
|
|
|
373
|
-
|
|
365
|
+
Многостековые проекты (например, Spring Boot на бэкенде и Next.js на фронтенде) поддерживаются из коробки.
|
|
374
366
|
|
|
375
|
-
Правила
|
|
367
|
+
Правила детекции и то, что вытаскивает каждый сканер, описаны в [docs/ru/stacks.md](docs/ru/stacks.md).
|
|
376
368
|
|
|
377
369
|
---
|
|
378
370
|
|
|
379
|
-
##
|
|
371
|
+
## Ежедневный рабочий процесс
|
|
380
372
|
|
|
381
|
-
|
|
373
|
+
Для примерно 95% случаев хватает трёх команд:
|
|
382
374
|
|
|
383
375
|
```bash
|
|
384
|
-
# Первый
|
|
376
|
+
# Первый запуск на проекте
|
|
385
377
|
npx claudeos-core init
|
|
386
378
|
|
|
387
|
-
# После
|
|
379
|
+
# После ручных правок в стандартах или правилах
|
|
388
380
|
npx claudeos-core lint
|
|
389
381
|
|
|
390
|
-
# Health-check (
|
|
382
|
+
# Health-check (перед коммитом или в CI)
|
|
391
383
|
npx claudeos-core health
|
|
392
384
|
```
|
|
393
385
|
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
```bash
|
|
397
|
-
# Компактация лога failure-patterns (запускайте периодически)
|
|
398
|
-
npx claudeos-core memory compact
|
|
399
|
-
|
|
400
|
-
# Продвижение частых failure pattern в предложенные rules
|
|
401
|
-
npx claudeos-core memory propose-rules
|
|
402
|
-
```
|
|
403
|
-
|
|
404
|
-
Полные опции каждой команды см. в [docs/ru/commands.md](docs/ru/commands.md).
|
|
386
|
+
Полный список опций для каждой команды смотрите в [docs/ru/commands.md](docs/ru/commands.md). Команды слоя памяти (`memory compact`, `memory propose-rules`) разобраны ниже, в разделе [Memory Layer](#memory-layer-опционально-для-долгосрочных-проектов).
|
|
405
387
|
|
|
406
388
|
---
|
|
407
389
|
|
|
408
|
-
##
|
|
390
|
+
## В чём отличие
|
|
409
391
|
|
|
410
|
-
Большинство инструментов документации Claude Code
|
|
392
|
+
Большинство инструментов документации для Claude Code исходят из вашего описания: вы рассказываете инструменту, инструмент пересказывает Claude. ClaudeOS-Core идёт от исходного кода: инструмент читает код, передаёт Claude уже подтверждённые факты, а Claude пишет только то, что подтверждено.
|
|
411
393
|
|
|
412
|
-
|
|
394
|
+
На практике это даёт три конкретных эффекта:
|
|
413
395
|
|
|
414
|
-
1.
|
|
415
|
-
2.
|
|
416
|
-
3.
|
|
396
|
+
1. **Детерминированная детекция стека.** Тот же проект и тот же код всегда дают тот же результат. Никаких «в этот раз Claude как-то иначе всё интерпретировал».
|
|
397
|
+
2. **Выдуманных путей не появляется.** В промпте Pass 3 явно перечислены все разрешённые пути в исходниках, поэтому Claude не может сослаться на то, чего нет.
|
|
398
|
+
3. **Учёт нескольких стеков сразу.** В рамках одного запуска бэкенд- и фронтенд-домены анализируются разными промптами.
|
|
417
399
|
|
|
418
|
-
|
|
400
|
+
Сравнение по охвату с другими инструментами есть в [docs/ru/comparison.md](docs/ru/comparison.md). Это сравнение про то, **что делает каждый инструмент**, а не про то, **какой из них лучше**: в большинстве случаев они дополняют друг друга.
|
|
419
401
|
|
|
420
402
|
---
|
|
421
403
|
|
|
422
|
-
##
|
|
404
|
+
## Проверка (после генерации)
|
|
423
405
|
|
|
424
|
-
|
|
406
|
+
Когда Claude закончил писать документацию, за дело снова берётся код и проверяет результат. Пять независимых валидаторов:
|
|
425
407
|
|
|
426
|
-
|
|
|
408
|
+
| Валидатор | Что проверяет | Кем запускается |
|
|
427
409
|
|---|---|---|
|
|
428
|
-
| `claude-md-validator` | Структурные инварианты CLAUDE.md (8
|
|
429
|
-
| `content-validator` | Реальное существование
|
|
430
|
-
| `pass-json-validator` |
|
|
431
|
-
| `plan-validator` |
|
|
432
|
-
| `sync-checker` |
|
|
410
|
+
| `claude-md-validator` | Структурные инварианты CLAUDE.md (8 секций, не зависит от языка) | `claudeos-core lint` |
|
|
411
|
+
| `content-validator` | Реальное существование упоминаемых путей и согласованность manifest | `health` (advisory) |
|
|
412
|
+
| `pass-json-validator` | Корректность JSON выходов Pass 1 / 2 / 3 / 4 | `health` (warn) |
|
|
413
|
+
| `plan-validator` | Соответствие сохранённого плана состоянию диска | `health` (fail-on-error) |
|
|
414
|
+
| `sync-checker` | Соответствие файлов на диске записям в `sync-map.json` (поиск orphaned/unregistered) | `health` (fail-on-error) |
|
|
433
415
|
|
|
434
|
-
`health-checker`
|
|
416
|
+
Четыре runtime-валидатора оркестрирует `health-checker` с тремя уровнями важности (fail / warn / advisory), а наружу отдаётся exit-код, удобный для CI. `claude-md-validator` вынесен в отдельную команду `lint`: структурный сдвиг — это сигнал к re-init, а не мягкое предупреждение. Запустить можно в любой момент:
|
|
435
417
|
|
|
436
418
|
```bash
|
|
437
419
|
npx claudeos-core health
|
|
438
420
|
```
|
|
439
421
|
|
|
440
|
-
|
|
422
|
+
Подробный список проверок каждого валидатора — в [docs/ru/verification.md](docs/ru/verification.md).
|
|
441
423
|
|
|
442
424
|
---
|
|
443
425
|
|
|
444
|
-
## Memory Layer (опционально, для
|
|
426
|
+
## Memory Layer (опционально, для долгосрочных проектов)
|
|
445
427
|
|
|
446
|
-
|
|
428
|
+
Кроме основного пайплайна, ClaudeOS-Core поднимает каталог `claudeos-core/memory/` — для проектов, где контекст должен жить дольше одной сессии. Слой опциональный: если хватает `CLAUDE.md` и правил, его можно спокойно игнорировать.
|
|
447
429
|
|
|
448
|
-
|
|
449
|
-
- `failure-patterns.md` — повторяющиеся ошибки с оценками frequency/importance
|
|
450
|
-
- `compaction.md` — как memory автоматически компактируется со временем
|
|
451
|
-
- `auto-rule-update.md` — паттерны, которые должны стать новыми rules
|
|
430
|
+
Внутри четыре файла, и все их пишет Pass 4:
|
|
452
431
|
|
|
453
|
-
|
|
432
|
+
- `decision-log.md` — append-only журнал «почему выбрали X, а не Y»; засевается из `pass2-merged.json`.
|
|
433
|
+
- `failure-patterns.md` — повторяющиеся ошибки с оценками frequency / importance.
|
|
434
|
+
- `compaction.md` — описание того, как память автоматически уплотняется со временем.
|
|
435
|
+
- `auto-rule-update.md` — паттерны, которые стоит превратить в новые правила.
|
|
454
436
|
|
|
455
|
-
|
|
437
|
+
Поддерживать слой со временем помогают две команды:
|
|
438
|
+
|
|
439
|
+
```bash
|
|
440
|
+
# Уплотнить лог failure-patterns (запускайте периодически)
|
|
441
|
+
npx claudeos-core memory compact
|
|
442
|
+
|
|
443
|
+
# Превратить часто встречающиеся failure-паттерны в предложенные правила
|
|
444
|
+
npx claudeos-core memory propose-rules
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
Модель памяти и её жизненный цикл подробно описаны в [docs/ru/memory-layer.md](docs/ru/memory-layer.md).
|
|
456
448
|
|
|
457
449
|
---
|
|
458
450
|
|
|
459
451
|
## FAQ
|
|
460
452
|
|
|
461
|
-
|
|
462
|
-
|
|
453
|
+
**Q: Нужен ли API-ключ Claude?**
|
|
454
|
+
A: Нет. ClaudeOS-Core использует уже установленный Claude Code и просто отправляет промпты в `claude -p` на вашей машине. Дополнительные аккаунты не нужны.
|
|
455
|
+
|
|
456
|
+
**Q: Перезапишет ли инструмент уже существующий CLAUDE.md или `.claude/rules/`?**
|
|
457
|
+
A: На чистом проекте создаст с нуля. При повторном запуске без `--force` правки сохраняются: инструмент находит маркеры предыдущих проходов и пропускает их. С `--force` всё стирается и собирается заново — правки исчезают, в этом и весь смысл флага. Подробнее — в [docs/ru/safety.md](docs/ru/safety.md).
|
|
463
458
|
|
|
464
|
-
|
|
465
|
-
|
|
459
|
+
**Q: Моего стека нет в списке. Можно добавить свой?**
|
|
460
|
+
A: Можно. На новый стек обычно нужны примерно три шаблона промптов и доменный сканер. Пошаговое руководство из 8 шагов есть в [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
466
461
|
|
|
467
|
-
|
|
468
|
-
|
|
462
|
+
**Q: Как сгенерировать документацию на русском (или другом языке)?**
|
|
463
|
+
A: `npx claudeos-core init --lang ru`. Поддерживается 10 языков: en, ko, ja, zh-CN, es, vi, hi, ru, fr, de.
|
|
469
464
|
|
|
470
|
-
|
|
471
|
-
|
|
465
|
+
**Q: Работает ли это с монорепозиториями?**
|
|
466
|
+
A: Да. Stack-detector распознаёт Turborepo (`turbo.json`), pnpm workspaces (`pnpm-workspace.yaml`), Lerna (`lerna.json`) и npm/yarn workspaces (`package.json#workspaces`); каждое приложение получает собственный анализ. Другие раскладки монорепо (например, NX) отдельно не детектируются, но привычные `apps/*/` и `packages/*/` стек-сканеры подхватят и так.
|
|
472
467
|
|
|
473
|
-
|
|
474
|
-
|
|
468
|
+
**Q: Что делать, если Claude Code сгенерировал правила, с которыми я не согласен?**
|
|
469
|
+
A: Правьте прямо в файлах. Потом запустите `npx claudeos-core lint` — он проверит, что структура CLAUDE.md осталась валидной. Правки переживут последующие запуски `init` без `--force`: механизм resume пропускает проходы, у которых уже есть маркеры.
|
|
470
|
+
|
|
471
|
+
**Q: Где сообщать о багах?**
|
|
472
|
+
A: В [GitHub Issues](https://github.com/claudeos-core/claudeos-core/issues). Вопросы безопасности — см. [SECURITY.md](SECURITY.md).
|
|
473
|
+
|
|
474
|
+
---
|
|
475
475
|
|
|
476
|
-
|
|
477
|
-
О: Редактируйте напрямую. Затем запустите `npx claudeos-core lint`, чтобы убедиться, что CLAUDE.md по-прежнему структурно валиден. Ваши правки сохраняются при последующих запусках `init` (без `--force`) — механизм resume пропускает pass-ы, у которых есть маркеры.
|
|
476
|
+
## Если это сэкономило вам время
|
|
478
477
|
|
|
479
|
-
|
|
480
|
-
О: [GitHub Issues](https://github.com/claudeos-core/claudeos-core/issues). По вопросам безопасности — [SECURITY.md](SECURITY.md).
|
|
478
|
+
⭐ на GitHub помогает проекту оставаться заметным и облегчает другим разработчикам его поиск. Issues, PR и шаблоны под новые стеки — приветствуются, подробности в [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
481
479
|
|
|
482
480
|
---
|
|
483
481
|
|
|
484
482
|
## Документация
|
|
485
483
|
|
|
486
|
-
| Тема |
|
|
484
|
+
| Тема | Где почитать |
|
|
487
485
|
|---|---|
|
|
488
|
-
| Как
|
|
489
|
-
| Визуальные диаграммы (Mermaid)
|
|
490
|
-
|
|
|
491
|
-
|
|
|
492
|
-
| Все 5
|
|
493
|
-
| Все CLI-команды и опции | [docs/ru/commands.md](docs/ru/commands.md) |
|
|
486
|
+
| Как устроен 4-проходный пайплайн (глубже, чем диаграмма) | [docs/ru/architecture.md](docs/ru/architecture.md) |
|
|
487
|
+
| Визуальные диаграммы архитектуры (Mermaid) | [docs/ru/diagrams.md](docs/ru/diagrams.md) |
|
|
488
|
+
| Детекция стеков — на что смотрит каждый сканер | [docs/ru/stacks.md](docs/ru/stacks.md) |
|
|
489
|
+
| Слой памяти — decision log и failure patterns | [docs/ru/memory-layer.md](docs/ru/memory-layer.md) |
|
|
490
|
+
| Все 5 валидаторов в деталях | [docs/ru/verification.md](docs/ru/verification.md) |
|
|
491
|
+
| Все CLI-команды и их опции | [docs/ru/commands.md](docs/ru/commands.md) |
|
|
494
492
|
| Ручная установка (без `npx`) | [docs/ru/manual-installation.md](docs/ru/manual-installation.md) |
|
|
495
|
-
|
|
|
496
|
-
| Безопасность: что сохраняется при
|
|
497
|
-
| Сравнение со схожими инструментами (
|
|
493
|
+
| Переопределения сканера — `.claudeos-scan.json` | [docs/ru/advanced-config.md](docs/ru/advanced-config.md) |
|
|
494
|
+
| Безопасность: что сохраняется при повторном init | [docs/ru/safety.md](docs/ru/safety.md) |
|
|
495
|
+
| Сравнение со схожими инструментами (по охвату, не по качеству) | [docs/ru/comparison.md](docs/ru/comparison.md) |
|
|
498
496
|
| Ошибки и восстановление | [docs/ru/troubleshooting.md](docs/ru/troubleshooting.md) |
|
|
499
497
|
|
|
500
498
|
---
|
|
501
499
|
|
|
502
|
-
##
|
|
500
|
+
## Участие в проекте
|
|
503
501
|
|
|
504
|
-
|
|
502
|
+
Контрибьюции приветствуются: добавление новых стеков, улучшение промптов, фиксы багов. Подробности в [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
505
503
|
|
|
506
|
-
Кодекс поведения и
|
|
504
|
+
Кодекс поведения и политика безопасности — [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) и [SECURITY.md](SECURITY.md).
|
|
507
505
|
|
|
508
506
|
## Лицензия
|
|
509
507
|
|
|
510
|
-
[ISC](LICENSE)
|
|
508
|
+
[ISC License](LICENSE). Свободно для любого использования, включая коммерческое. © 2025–2026 ClaudeOS-Core contributors.
|
|
511
509
|
|
|
512
510
|
---
|
|
513
511
|
|
|
514
|
-
<sub
|
|
512
|
+
<sub>Поддерживается командой [claudeos-core](https://github.com/claudeos-core). Issues и PR — на <https://github.com/claudeos-core/claudeos-core>.</sub>
|