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.fr.md
CHANGED
|
@@ -7,58 +7,40 @@
|
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
[](https://www.npmjs.com/package/claudeos-core)
|
|
9
9
|
|
|
10
|
-
**
|
|
11
|
-
|
|
12
|
-
Un scanner Node.js déterministe lit d'abord votre code ; un pipeline Claude en 4 passes écrit ensuite l'ensemble complet — `CLAUDE.md` + `.claude/rules/` auto-chargé + standards + skills + L4 memory. 10 langues de sortie, 5 validators post-génération, et une path allowlist explicite qui empêche le LLM d'inventer des fichiers ou frameworks absents de votre code.
|
|
13
|
-
|
|
14
|
-
Fonctionne sur [**12 stacks**](#supported-stacks) (monorepos inclus) — une seule commande `npx`, sans config, resume-safe, idempotent.
|
|
10
|
+
**Une CLI qui produit `CLAUDE.md` et `.claude/rules/` à partir du code source réel du projet, et qui renvoie toujours le même résultat pour les mêmes entrées. Elle s'appuie sur un scanner Node.js, un pipeline Claude en 4 passes, et 5 validateurs. 12 stacks, 10 langues pris en charge, et aucun chemin fabriqué hors du code.**
|
|
15
11
|
|
|
16
12
|
```bash
|
|
17
13
|
npx claudeos-core init
|
|
18
14
|
```
|
|
19
15
|
|
|
16
|
+
Compatible avec [**12 stacks**](#supported-stacks), monorepos compris. Une seule commande, sans configuration, reprenant après une interruption, et sans risque à la ré-exécution.
|
|
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) · [🇷🇺 Русский](README.ru.md) · [🇩🇪 Deutsch](README.de.md)
|
|
21
19
|
|
|
22
20
|
---
|
|
23
21
|
|
|
24
|
-
## C'est quoi
|
|
25
|
-
|
|
26
|
-
Vous utilisez Claude Code. Il est puissant, mais chaque session démarre à zéro — il n'a aucun souvenir de la façon dont _votre_ projet est structuré. Du coup, il retombe sur des valeurs par défaut « globalement bonnes » qui correspondent rarement à ce que votre équipe fait réellement :
|
|
22
|
+
## C'est quoi ?
|
|
27
23
|
|
|
28
|
-
|
|
29
|
-
- Votre wrapper de réponse est `ApiResponse.ok()`, mais Claude écrit `ResponseEntity.success()`.
|
|
30
|
-
- Vos packages sont organisés par couche (`controller/order/`), mais Claude crée par domaine (`order/controller/`).
|
|
31
|
-
- Vos erreurs passent par un middleware centralisé, mais Claude éparpille des `try/catch` dans chaque endpoint.
|
|
24
|
+
À chaque nouvelle session, Claude Code retombe sur les valeurs par défaut génériques du framework. L'équipe travaille avec **MyBatis** ? Claude écrit du JPA. Le wrapper de réponse s'appelle `ApiResponse.ok()` ? Claude utilise `ResponseEntity.success()`. Les paquets sont organisés par couches ? La génération propose une architecture orientée domaine. Écrire `.claude/rules/` à la main pour chaque dépôt règle le problème, jusqu'au jour où le code évolue et où les règles se mettent à dériver.
|
|
32
25
|
|
|
33
|
-
|
|
26
|
+
**ClaudeOS-Core régénère ces règles de façon reproductible, à partir du code source réel.** Un scanner Node.js commence par lire le projet : stack, ORM, organisation des paquets, chemins de fichiers. Un pipeline Claude en 4 passes prend ensuite le relais et produit l'ensemble complet : `CLAUDE.md`, les fichiers `.claude/rules/` chargés automatiquement, les standards et les skills. Tout reste cantonné à une liste blanche de chemins explicite, hors de laquelle le LLM ne peut pas sortir. Cinq validateurs contrôlent le résultat avant le rendu final.
|
|
34
27
|
|
|
35
|
-
|
|
28
|
+
Conséquence : pour une même entrée, la sortie est rigoureusement identique au bit près, dans n'importe laquelle des 10 langues, et aucun chemin n'est fabriqué. (Le détail se trouve plus bas, dans [Ce qui le rend différent](#ce-qui-le-rend-différent).)
|
|
36
29
|
|
|
37
|
-
|
|
38
|
-
- **`.claude/rules/`** — rules auto-chargées par catégorie (`00.core` / `10.backend` / `20.frontend` / `30.security-db` / `40.infra` / `60.memory` / `70.domains` / `80.verification`)
|
|
39
|
-
- **`claudeos-core/standard/`** — documents de référence (le « pourquoi » derrière chaque rule)
|
|
40
|
-
- **`claudeos-core/skills/`** — patterns réutilisables (CRUD scaffolding, templates de pages)
|
|
41
|
-
- **`claudeos-core/memory/`** — decision log + failure patterns qui grandissent avec le projet
|
|
42
|
-
|
|
43
|
-
Parce que le scanner remet à Claude une path allowlist explicite, le LLM **ne peut pas inventer de fichiers ou frameworks qui ne sont pas dans votre code**. Cinq validators post-génération (`claude-md-validator`, `content-validator`, `pass-json-validator`, `plan-validator`, `sync-checker`) vérifient la sortie avant qu'elle ne soit publiée — language-invariant, donc les mêmes règles s'appliquent que vous génériez en anglais, en coréen ou dans l'une des 8 autres langues.
|
|
44
|
-
|
|
45
|
-
```
|
|
46
|
-
Avant : Vous → Claude Code → code « globalement bon » → corrections manuelles à chaque fois
|
|
47
|
-
Après : Vous → Claude Code → code qui colle à VOTRE projet → on expédie
|
|
48
|
-
```
|
|
30
|
+
Pour les projets qui durent dans le temps, un [Memory Layer](#memory-layer-optionnel-pour-les-projets-longue-durée) distinct est également initialisé.
|
|
49
31
|
|
|
50
32
|
---
|
|
51
33
|
|
|
52
|
-
##
|
|
34
|
+
## Voir sur un vrai projet
|
|
53
35
|
|
|
54
|
-
Exécution sur [`spring-boot-realworld-example-app`](https://github.com/gothinkster/spring-boot-realworld-example-app)
|
|
36
|
+
Exécution sur [`spring-boot-realworld-example-app`](https://github.com/gothinkster/spring-boot-realworld-example-app), un projet Java 11 · Spring Boot 2.6 · MyBatis · SQLite, 187 fichiers source. Résultat obtenu : **75 fichiers générés**, durée totale **53 minutes**, tous les validateurs au vert.
|
|
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>Sortie terminal (version texte, pour la recherche et la copie)</strong></summary>
|
|
62
44
|
|
|
63
45
|
```text
|
|
64
46
|
╔════════════════════════════════════════════════════╗
|
|
@@ -93,18 +75,18 @@ Exécution sur [`spring-boot-realworld-example-app`](https://github.com/gothinks
|
|
|
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 @@ Exécution sur [`spring-boot-realworld-example-app`](https://github.com/gothinks
|
|
|
133
115
|
</details>
|
|
134
116
|
|
|
135
117
|
<details>
|
|
136
|
-
<summary><strong
|
|
118
|
+
<summary><strong>Ce qui finit dans votre <code>CLAUDE.md</code> (extrait réel, sections 1 et 2)</strong></summary>
|
|
137
119
|
|
|
138
120
|
```markdown
|
|
139
121
|
# CLAUDE.md — spring-boot-realworld-example-app
|
|
@@ -142,7 +124,7 @@ Exécution sur [`spring-boot-realworld-example-app`](https://github.com/gothinks
|
|
|
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
|
+
Toutes les valeurs ci-dessus, des coordonnées exactes des dépendances au nom de fichier `dev.db`, en passant par la migration `V1__create_tables.sql` et la mention « no JPA », sont extraites par le scanner depuis `build.gradle`, `application.properties` et l'arborescence source, avant même que Claude n'écrive la moindre ligne. Rien n'est deviné.
|
|
170
152
|
|
|
171
153
|
</details>
|
|
172
154
|
|
|
173
155
|
<details>
|
|
174
|
-
<summary><strong
|
|
156
|
+
<summary><strong>Une rule chargée automatiquement (<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
|
-
Le glob `paths: ["**/*"]`
|
|
213
|
+
Le glob `paths: ["**/*"]` indique à Claude Code de charger automatiquement cette rule dès qu'un fichier du projet est édité. Tous les noms de classe, chemins de paquet et exception handlers proviennent du code scanné, y compris les véritables `CustomizeExceptionHandler` et `JacksonCustomizations` du projet.
|
|
232
214
|
|
|
233
215
|
</details>
|
|
234
216
|
|
|
235
217
|
<details>
|
|
236
|
-
<summary><strong
|
|
218
|
+
<summary><strong>Un seed <code>decision-log.md</code> auto-généré (extrait réel)</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,229 +237,245 @@ Le glob `paths: ["**/*"]` signifie que Claude Code charge automatiquement cette
|
|
|
255
237
|
split the persistence model.
|
|
256
238
|
```
|
|
257
239
|
|
|
258
|
-
|
|
240
|
+
La passe 4 alimente `decision-log.md` avec les décisions architecturales tirées de `pass2-merged.json`. Les sessions futures gardent ainsi en mémoire le *pourquoi* derrière la base de code, et pas seulement le *à quoi ça ressemble*. Chaque option (« JPA/Hibernate », « MyBatis-Plus ») comme chaque conséquence s'ancre directement dans le bloc de dépendances réel de `build.gradle`.
|
|
259
241
|
|
|
260
242
|
</details>
|
|
261
243
|
|
|
262
244
|
---
|
|
263
245
|
|
|
264
|
-
##
|
|
246
|
+
## Testé sur
|
|
247
|
+
|
|
248
|
+
ClaudeOS-Core est livré avec des benchmarks de référence mesurés sur de vrais projets open source. Si vous l'avez essayé sur un dépôt public, [ouvrez une issue](https://github.com/claudeos-core/claudeos-core/issues) et le projet rejoindra le tableau.
|
|
249
|
+
|
|
250
|
+
| Projet | Stack | Scanné → Généré | Statut |
|
|
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 fichiers | ✅ 5 validateurs au vert |
|
|
253
|
+
|
|
254
|
+
---
|
|
255
|
+
|
|
256
|
+
## Démarrage rapide
|
|
265
257
|
|
|
266
258
|
**Prérequis :** Node.js 18+, [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installé et authentifié.
|
|
267
259
|
|
|
268
260
|
```bash
|
|
269
|
-
# 1.
|
|
261
|
+
# 1. Se placer à la racine du projet
|
|
270
262
|
cd my-spring-boot-project
|
|
271
263
|
|
|
272
|
-
# 2. Lancer init (
|
|
264
|
+
# 2. Lancer init (le code est analysé, puis Claude rédige les rules)
|
|
273
265
|
npx claudeos-core init
|
|
274
266
|
|
|
275
|
-
# 3. Terminé. Ouvrez Claude Code et
|
|
267
|
+
# 3. Terminé. Ouvrez Claude Code et commencez à coder, les rules sont déjà chargées.
|
|
276
268
|
```
|
|
277
269
|
|
|
278
|
-
|
|
270
|
+
Une fois `init` terminé, voici l'arborescence obtenue :
|
|
279
271
|
|
|
280
272
|
```
|
|
281
273
|
your-project/
|
|
282
274
|
├── .claude/
|
|
283
|
-
│ └── rules/ ←
|
|
284
|
-
│ ├── 00.core/ (rules générales
|
|
285
|
-
│ ├── 10.backend/ (rules
|
|
286
|
-
│ ├── 20.frontend/ (rules
|
|
287
|
-
│ ├── 30.security-db/ (sécurité
|
|
275
|
+
│ └── rules/ ← Chargé automatiquement par Claude Code
|
|
276
|
+
│ ├── 00.core/ (rules générales : naming, architecture)
|
|
277
|
+
│ ├── 10.backend/ (rules backend, le cas échéant)
|
|
278
|
+
│ ├── 20.frontend/ (rules frontend, le cas échéant)
|
|
279
|
+
│ ├── 30.security-db/ (conventions sécurité et BD)
|
|
288
280
|
│ ├── 40.infra/ (env, logging, CI/CD)
|
|
289
|
-
│ ├── 50.sync/ (rappels de doc
|
|
290
|
-
│ ├── 60.memory/ (memory
|
|
281
|
+
│ ├── 50.sync/ (rappels de synchro doc — rules uniquement)
|
|
282
|
+
│ ├── 60.memory/ (rules memory — Pass 4, rules uniquement)
|
|
291
283
|
│ ├── 70.domains/{type}/ (rules par domaine, type = backend|frontend)
|
|
292
|
-
│ └── 80.verification/ (stratégie de tests
|
|
284
|
+
│ └── 80.verification/ (stratégie de tests et rappels de vérif build)
|
|
293
285
|
├── claudeos-core/
|
|
294
|
-
│ ├── standard/ ←
|
|
295
|
-
│ │ ├── 00.core/ (
|
|
286
|
+
│ ├── standard/ ← Documentation de référence (miroir des catégories)
|
|
287
|
+
│ │ ├── 00.core/ (présentation projet, architecture, naming)
|
|
296
288
|
│ │ ├── 10.backend/ (référence backend — si stack backend)
|
|
297
289
|
│ │ ├── 20.frontend/ (référence frontend — si stack frontend)
|
|
298
|
-
│ │ ├── 30.security-db/ (référence sécurité
|
|
290
|
+
│ │ ├── 30.security-db/ (référence sécurité et BD)
|
|
299
291
|
│ │ ├── 40.infra/ (référence env / logging / CI-CD)
|
|
300
292
|
│ │ ├── 70.domains/{type}/ (référence par domaine)
|
|
301
|
-
│ │ ├── 80.verification/ (référence build / startup / tests — standard
|
|
302
|
-
│ │ └── 90.optional/ (extras spécifiques au stack — standard
|
|
293
|
+
│ │ ├── 80.verification/ (référence build / startup / tests — standard uniquement)
|
|
294
|
+
│ │ └── 90.optional/ (extras spécifiques au stack — standard uniquement)
|
|
303
295
|
│ ├── skills/ (patterns réutilisables que Claude peut appliquer)
|
|
304
|
-
│ ├── guide/ (
|
|
305
|
-
│ ├── database/ (
|
|
296
|
+
│ ├── guide/ (guides pratiques pour les tâches fréquentes)
|
|
297
|
+
│ ├── database/ (panorama du schéma, guide de migration)
|
|
306
298
|
│ ├── mcp-guide/ (notes d'intégration MCP)
|
|
307
299
|
│ └── memory/ (decision log, failure patterns, compaction)
|
|
308
300
|
└── CLAUDE.md (l'index que Claude lit en premier)
|
|
309
301
|
```
|
|
310
302
|
|
|
311
|
-
|
|
303
|
+
Lorsque `rules/` et `standard/` partagent le même préfixe numérique, ils couvrent la même zone conceptuelle : les rules `10.backend` répondent aux standards `10.backend`, par exemple. Deux catégories existent uniquement côté rules : `50.sync` (rappels de synchro doc) et `60.memory` (mémoire issue de la passe 4). Une seule existe uniquement côté standard : `90.optional` (extras spécifiques au stack, sans contrainte d'application). Tous les autres préfixes (`00`, `10`, `20`, `30`, `40`, `70`, `80`) figurent dans les deux. Claude Code connaît désormais le projet.
|
|
312
304
|
|
|
313
305
|
---
|
|
314
306
|
|
|
315
|
-
## À qui s'adresse
|
|
307
|
+
## À qui s'adresse-t-il ?
|
|
316
308
|
|
|
317
|
-
|
|
|
309
|
+
| Profil | Le problème qui disparaît |
|
|
318
310
|
|---|---|
|
|
319
|
-
| **
|
|
320
|
-
| **
|
|
321
|
-
| **
|
|
322
|
-
| **
|
|
323
|
-
| **
|
|
324
|
-
| **
|
|
325
|
-
| **
|
|
311
|
+
| **Développeur solo** qui démarre un nouveau projet avec Claude Code | « Réexpliquer les conventions à Claude à chaque session » : terminé. `CLAUDE.md` et les `.claude/rules/` répartis en 8 catégories sont générés en une seule passe. |
|
|
312
|
+
| **Tech lead** qui maintient des standards communs entre plusieurs dépôts | Les `.claude/rules/` qui dérivent à mesure que les paquets sont renommés, que l'ORM change ou que le wrapper de réponse évolue. ClaudeOS-Core resynchronise tout de façon reproductible : même entrée, même sortie au bit près, donc zéro bruit dans les diffs. |
|
|
313
|
+
| **Utilisateur de Claude Code** lassé de corriger le code généré | Mauvais wrapper de réponse, paquets mal organisés, JPA alors que le projet utilise MyBatis, `try/catch` éparpillés alors qu'un middleware centralisé existe. Le scanner extrait les vraies conventions du projet, et chaque passe Claude opère sur une liste blanche de chemins explicite. |
|
|
314
|
+
| **Onboarding sur un nouveau dépôt** (projet existant, intégration en équipe) | Un simple `init` suffit pour obtenir une carte d'architecture vivante : tableau de stack dans CLAUDE.md, rules par couche avec exemples ✅/❌, decision log initialisé avec le « pourquoi » des choix structurants (JPA ou MyBatis, REST ou GraphQL, etc.). Lire 5 fichiers vaut mieux qu'éplucher 5 000 fichiers source. |
|
|
315
|
+
| **Travail en coréen, japonais, chinois ou 7 autres langues** | La plupart des générateurs de rules pour Claude Code se cantonnent à l'anglais. ClaudeOS-Core produit l'ensemble complet dans **10 langues** (`en/ko/ja/zh-CN/es/vi/hi/ru/fr/de`), avec une **validation structurelle identique au bit près**. Le verdict de `claude-md-validator` reste le même quelle que soit la langue de sortie. |
|
|
316
|
+
| **Projet en monorepo** (Turborepo, pnpm/yarn workspaces, Lerna) | Domaines backend et frontend analysés dans la même exécution, avec des prompts distincts. Les répertoires `apps/*/` et `packages/*/` sont parcourus automatiquement, et les rules par stack atterrissent dans `70.domains/{type}/`. |
|
|
317
|
+
| **Contribution OSS ou expérimentation** | La sortie reste compatible avec `.gitignore` : `claudeos-core/` est un répertoire de travail local, seuls `CLAUDE.md` et `.claude/` ont vocation à être livrés. La reprise est sûre après interruption et la commande est idempotente. Les éditions manuelles des rules survivent tant que `--force` n'est pas utilisé. |
|
|
326
318
|
|
|
327
|
-
**Pas adapté si :** vous
|
|
319
|
+
**Pas adapté si :** vous cherchez un preset universel d'agents, skills et rules qui fonctionne dès le premier jour sans étape de scan (voir [docs/fr/comparison.md](docs/fr/comparison.md) pour situer chaque outil) ; votre projet ne correspond pas encore à l'un des [stacks pris en charge](#supported-stacks) ; ou un simple `CLAUDE.md` vous suffit (dans ce cas, le `claude /init` intégré fait déjà l'affaire, inutile d'installer un outil de plus).
|
|
328
320
|
|
|
329
321
|
---
|
|
330
322
|
|
|
331
323
|
## Comment ça marche ?
|
|
332
324
|
|
|
333
|
-
ClaudeOS-Core inverse le
|
|
325
|
+
ClaudeOS-Core inverse le flux Claude Code habituel :
|
|
334
326
|
|
|
335
327
|
```
|
|
336
328
|
Habituel : Vous décrivez le projet → Claude devine votre stack → Claude écrit la doc
|
|
337
|
-
Ici : Le code lit votre stack → Le code
|
|
329
|
+
Ici : Le code lit votre stack → Le code passe les faits confirmés à Claude → Claude écrit la doc à partir de ces faits
|
|
338
330
|
```
|
|
339
331
|
|
|
340
|
-
Le pipeline
|
|
332
|
+
Le pipeline se déroule en **trois étapes**, avec du code de part et d'autre de l'appel LLM.
|
|
341
333
|
|
|
342
|
-
**1.
|
|
334
|
+
**1. Étape A — Scanner (reproductible, sans LLM).** Un scanner Node.js parcourt la racine du projet, lit `package.json`, `build.gradle`, `pom.xml` ou `pyproject.toml`, et analyse les fichiers `.env*`. Les variables sensibles (`PASSWORD/SECRET/TOKEN/JWT_SECRET/...`) sont automatiquement masquées. Le scanner classe ensuite le pattern d'architecture (5 patterns Java A/B/C/D/E, Kotlin CQRS ou multi-module, Next.js App ou Pages Router, FSD, components-pattern), identifie les domaines et construit une liste blanche explicite qui recense chaque chemin de fichier source réellement présent. Le tout finit dans `project-analysis.json`, source unique de vérité pour la suite.
|
|
343
335
|
|
|
344
|
-
**2.
|
|
345
|
-
- **Pass 1** lit
|
|
346
|
-
- **Pass 2** fusionne toutes les analyses par domaine en une vue projet globale et
|
|
347
|
-
- **Pass 3**
|
|
348
|
-
- **Pass 4**
|
|
336
|
+
**2. Étape B — Pipeline Claude en 4 passes (contraint par les faits de l'étape A).**
|
|
337
|
+
- **Pass 1** lit des fichiers représentatifs par groupe de domaines et en extrait 50 à 100 conventions par domaine : wrappers de réponse, bibliothèques de logging, gestion des erreurs, conventions de naming, patterns de tests. La passe tourne une fois par groupe de domaines (`max 4 domains, 40 files per group`), si bien que le contexte ne déborde jamais.
|
|
338
|
+
- **Pass 2** fusionne toutes les analyses par domaine en une vue projet globale et tranche les désaccords en retenant la convention dominante.
|
|
339
|
+
- **Pass 3** rédige `CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, les skills et les guides. Le travail est découpé en stages (`3a` facts, puis `3b-core/3b-N` rules+standards, puis `3c-core/3c-N` skills+guides, enfin `3d-aux` database+mcp-guide) afin que le prompt de chaque stage tienne dans la fenêtre de contexte du LLM, même lorsque `pass2-merged.json` devient volumineux. Pour les projets de 16 domaines ou plus, 3b et 3c sont à nouveau découpés en lots de 15 domaines maximum.
|
|
340
|
+
- **Pass 4** initialise la couche memory L4 (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`) et ajoute les rules de scaffold universelles. Cette passe a **interdiction de toucher à `CLAUDE.md`** : la section 8 produite par la passe 3 fait autorité.
|
|
349
341
|
|
|
350
|
-
**3.
|
|
351
|
-
- `claude-md-validator`
|
|
352
|
-
- `content-validator`
|
|
353
|
-
- `pass-json-validator`
|
|
354
|
-
- `plan-validator`
|
|
355
|
-
- `sync-checker`
|
|
342
|
+
**3. Étape C — Vérification (reproductible, sans LLM).** Cinq validateurs contrôlent le résultat.
|
|
343
|
+
- `claude-md-validator` : 25 vérifications structurelles sur `CLAUDE.md` (8 sections, comptage H3/H4, unicité des fichiers memory, invariant T1 sur les canonical headings). Indépendant de la langue : le verdict reste identique quel que soit `--lang`.
|
|
344
|
+
- `content-validator` : 10 vérifications de contenu, dont la vérification des chemins cités (`STALE_PATH` repère les références `src/...` absentes du code) et la détection de drift dans le MANIFEST.
|
|
345
|
+
- `pass-json-validator` : bonne forme JSON pour les passes 1/2/3/4 et comptage des sections en fonction du stack.
|
|
346
|
+
- `plan-validator` : cohérence plan ↔ disque (legacy, principalement no-op depuis la v2.1.0).
|
|
347
|
+
- `sync-checker` : cohérence d'enregistrement disque ↔ `sync-map.json` sur 7 répertoires suivis.
|
|
356
348
|
|
|
357
|
-
Trois niveaux de sévérité (`fail
|
|
349
|
+
Trois niveaux de sévérité (`fail`, `warn`, `advisory`) cohabitent : ainsi, les warnings ne bloquent jamais la CI pour une hallucination LLM que l'on peut corriger à la main.
|
|
358
350
|
|
|
359
|
-
L'invariant qui
|
|
351
|
+
L'invariant qui tient tout l'édifice est simple : **Claude ne peut citer que des chemins réellement présents dans le code**, puisque l'étape A lui remet une liste blanche finie. Si le LLM tente malgré tout d'inventer quelque chose (cas rare, mais cela arrive sur certains seeds), l'étape C l'attrape avant la livraison.
|
|
360
352
|
|
|
361
|
-
Pour les détails par passe, le
|
|
353
|
+
Pour les détails par passe, le mécanisme de reprise par marker, le contournement staged-rules face au blocage `.claude/` de Claude Code, et le fonctionnement interne de la stack detection, voir [docs/fr/architecture.md](docs/fr/architecture.md).
|
|
362
354
|
|
|
363
355
|
---
|
|
364
356
|
|
|
365
357
|
## Supported Stacks
|
|
366
358
|
|
|
367
|
-
12 stacks,
|
|
359
|
+
12 stacks, détectés automatiquement à partir des fichiers de votre projet.
|
|
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
|
-
Les projets multi-stack (par
|
|
365
|
+
Les projets multi-stack (par exemple un backend Spring Boot couplé à un frontend Next.js) fonctionnent sans configuration particulière.
|
|
374
366
|
|
|
375
|
-
Pour les règles de détection et
|
|
367
|
+
Pour les règles de détection et le contenu extrait par chaque scanner, voir [docs/fr/stacks.md](docs/fr/stacks.md).
|
|
376
368
|
|
|
377
369
|
---
|
|
378
370
|
|
|
379
|
-
##
|
|
371
|
+
## Flux de travail quotidien
|
|
380
372
|
|
|
381
|
-
Trois commandes couvrent
|
|
373
|
+
Trois commandes couvrent environ 95 % des usages :
|
|
382
374
|
|
|
383
375
|
```bash
|
|
384
|
-
# Première
|
|
376
|
+
# Première utilisation sur un projet
|
|
385
377
|
npx claudeos-core init
|
|
386
378
|
|
|
387
|
-
# Après avoir édité manuellement les standards ou rules
|
|
379
|
+
# Après avoir édité manuellement les standards ou les rules
|
|
388
380
|
npx claudeos-core lint
|
|
389
381
|
|
|
390
|
-
# Health check (avant
|
|
382
|
+
# Health check (avant un commit, ou en CI)
|
|
391
383
|
npx claudeos-core health
|
|
392
384
|
```
|
|
393
385
|
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
```bash
|
|
397
|
-
# Compacter le log failure-patterns (à exécuter périodiquement)
|
|
398
|
-
npx claudeos-core memory compact
|
|
399
|
-
|
|
400
|
-
# Promouvoir des failure patterns fréquents en rules proposées
|
|
401
|
-
npx claudeos-core memory propose-rules
|
|
402
|
-
```
|
|
403
|
-
|
|
404
|
-
Pour toutes les options de chaque commande, voir [docs/fr/commands.md](docs/fr/commands.md).
|
|
386
|
+
Pour les options complètes de chaque commande, voir [docs/fr/commands.md](docs/fr/commands.md). Les commandes du memory layer (`memory compact`, `memory propose-rules`) sont documentées dans la section [Memory Layer](#memory-layer-optionnel-pour-les-projets-longue-durée) ci-dessous.
|
|
405
387
|
|
|
406
388
|
---
|
|
407
389
|
|
|
408
|
-
## Ce qui
|
|
390
|
+
## Ce qui le rend différent
|
|
409
391
|
|
|
410
|
-
La plupart des outils de documentation Claude Code génèrent à partir d'une description
|
|
392
|
+
La plupart des outils de documentation pour Claude Code génèrent à partir d'une description : l'utilisateur explique à l'outil, qui transmet ensuite à Claude. ClaudeOS-Core, lui, génère à partir du code source réel : l'outil lit le code, transmet à Claude ce qui est confirmé, et Claude n'écrit que ce qui est confirmé.
|
|
411
393
|
|
|
412
|
-
Trois conséquences concrètes
|
|
394
|
+
Trois conséquences concrètes en découlent.
|
|
413
395
|
|
|
414
|
-
1. **Détection de stack
|
|
415
|
-
2. **Aucun chemin
|
|
416
|
-
3. **
|
|
396
|
+
1. **Détection de stack reproductible.** À projet et code identiques, sortie identique. Plus de « cette fois Claude est parti sur autre chose ».
|
|
397
|
+
2. **Aucun chemin fabriqué.** Le prompt de la passe 3 énumère noir sur blanc chaque chemin source autorisé : Claude ne peut donc pas citer un chemin qui n'existe pas.
|
|
398
|
+
3. **Pensé multi-stack.** Backend et frontend s'appuient sur des prompts d'analyse distincts, dans une même exécution.
|
|
417
399
|
|
|
418
|
-
Pour une comparaison
|
|
400
|
+
Pour une comparaison de scope côte à côte avec d'autres outils, voir [docs/fr/comparison.md](docs/fr/comparison.md). Cette comparaison décrit **ce que chaque outil fait**, pas **lequel est meilleur** : la plupart sont en réalité complémentaires.
|
|
419
401
|
|
|
420
402
|
---
|
|
421
403
|
|
|
422
404
|
## Vérification (post-génération)
|
|
423
405
|
|
|
424
|
-
Une fois la
|
|
406
|
+
Une fois la documentation rédigée par Claude, le code prend le relais pour la valider. Cinq validateurs distincts entrent en jeu.
|
|
425
407
|
|
|
426
|
-
|
|
|
408
|
+
| Validateur | Ce qu'il vérifie | Lancé par |
|
|
427
409
|
|---|---|---|
|
|
428
|
-
| `claude-md-validator` | Invariants structurels de CLAUDE.md (8 sections,
|
|
429
|
-
| `content-validator` |
|
|
430
|
-
| `pass-json-validator` |
|
|
431
|
-
| `plan-validator` |
|
|
432
|
-
| `sync-checker` |
|
|
410
|
+
| `claude-md-validator` | Invariants structurels de CLAUDE.md (8 sections, indépendant de la langue) | `claudeos-core lint` |
|
|
411
|
+
| `content-validator` | Existence réelle des chemins cités, cohérence du manifest | `health` (advisory) |
|
|
412
|
+
| `pass-json-validator` | Bonne forme JSON des sorties Pass 1 / 2 / 3 / 4 | `health` (warn) |
|
|
413
|
+
| `plan-validator` | Correspondance entre le plan sauvegardé et le disque | `health` (fail-on-error) |
|
|
414
|
+
| `sync-checker` | Correspondance entre les fichiers sur disque et les entrées de `sync-map.json` (détection orphaned/unregistered) | `health` (fail-on-error) |
|
|
433
415
|
|
|
434
|
-
Un `health-checker` orchestre les quatre
|
|
416
|
+
Un `health-checker` orchestre les quatre validateurs runtime selon les trois niveaux de sévérité (fail / warn / advisory) et sort avec le code adapté à la CI. `claude-md-validator`, en revanche, se lance séparément via la commande `lint` : un drift structurel n'est pas un simple warning, c'est le signal qu'il faut relancer `init`. Exécution possible à tout moment :
|
|
435
417
|
|
|
436
418
|
```bash
|
|
437
419
|
npx claudeos-core health
|
|
438
420
|
```
|
|
439
421
|
|
|
440
|
-
Pour le détail des
|
|
422
|
+
Pour le détail des contrôles de chaque validateur, voir [docs/fr/verification.md](docs/fr/verification.md).
|
|
441
423
|
|
|
442
424
|
---
|
|
443
425
|
|
|
444
|
-
## Memory Layer (optionnel, pour les projets
|
|
426
|
+
## Memory Layer (optionnel, pour les projets longue durée)
|
|
445
427
|
|
|
446
|
-
|
|
428
|
+
Au-delà du pipeline de scaffolding décrit plus haut, ClaudeOS-Core initialise un dossier `claudeos-core/memory/` pour les projets dont le contexte dépasse une seule session. La couche est optionnelle : on peut tout à fait l'ignorer si seuls `CLAUDE.md` et les rules sont nécessaires.
|
|
447
429
|
|
|
448
|
-
|
|
449
|
-
- `failure-patterns.md` — erreurs récurrentes avec scores frequency/importance
|
|
450
|
-
- `compaction.md` — comment la memory est auto-compactée au fil du temps
|
|
451
|
-
- `auto-rule-update.md` — patterns qui devraient devenir de nouvelles rules
|
|
430
|
+
Quatre fichiers, tous écrits par la passe 4 :
|
|
452
431
|
|
|
453
|
-
|
|
432
|
+
- `decision-log.md` : journal append-only du « pourquoi avoir choisi X plutôt que Y », initialisé depuis `pass2-merged.json`.
|
|
433
|
+
- `failure-patterns.md` : erreurs récurrentes, accompagnées de scores frequency / importance.
|
|
434
|
+
- `compaction.md` : description de la compaction automatique de la mémoire au fil du temps.
|
|
435
|
+
- `auto-rule-update.md` : patterns qui devraient être promus au rang de nouvelles rules.
|
|
454
436
|
|
|
455
|
-
|
|
437
|
+
Deux commandes assurent la maintenance de cette couche dans la durée :
|
|
438
|
+
|
|
439
|
+
```bash
|
|
440
|
+
# Compacter le log failure-patterns (à lancer périodiquement)
|
|
441
|
+
npx claudeos-core memory compact
|
|
442
|
+
|
|
443
|
+
# Promouvoir les failure patterns fréquents en rules proposées
|
|
444
|
+
npx claudeos-core memory propose-rules
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
Pour le modèle de mémoire et son cycle de vie, voir [docs/fr/memory-layer.md](docs/fr/memory-layer.md).
|
|
456
448
|
|
|
457
449
|
---
|
|
458
450
|
|
|
459
451
|
## FAQ
|
|
460
452
|
|
|
461
|
-
**Q :
|
|
462
|
-
R : Non. ClaudeOS-Core
|
|
453
|
+
**Q : Faut-il une clé API Claude ?**
|
|
454
|
+
R : Non. ClaudeOS-Core s'appuie sur l'installation Claude Code déjà présente sur le poste et envoie les prompts à `claude -p` en local. Aucun compte supplémentaire n'est requis.
|
|
463
455
|
|
|
464
|
-
**Q :
|
|
465
|
-
R :
|
|
456
|
+
**Q : Mes CLAUDE.md ou `.claude/rules/` existants seront-ils écrasés ?**
|
|
457
|
+
R : Sur un projet vierge, ils sont créés. En réexécution sans `--force`, les éditions sont préservées : les pass markers du run précédent sont détectés et les passes correspondantes sont sautées. Avec `--force`, tout est effacé et régénéré depuis zéro : les éditions sont alors perdues, et c'est précisément le rôle de `--force`. Voir [docs/fr/safety.md](docs/fr/safety.md).
|
|
466
458
|
|
|
467
|
-
**Q : Mon stack n'est pas
|
|
468
|
-
R : Oui.
|
|
459
|
+
**Q : Mon stack n'est pas pris en charge. Puis-je l'ajouter ?**
|
|
460
|
+
R : Oui. Compter environ 3 templates de prompts et un domain scanner pour un nouveau stack. Voir [CONTRIBUTING.md](CONTRIBUTING.md) pour le guide en 8 étapes.
|
|
469
461
|
|
|
470
|
-
**Q : Comment générer la
|
|
471
|
-
R : `npx claudeos-core init --lang
|
|
462
|
+
**Q : Comment générer la documentation en coréen (ou dans une autre langue) ?**
|
|
463
|
+
R : `npx claudeos-core init --lang ko`. 10 langues prises en charge : en, ko, ja, zh-CN, es, vi, hi, ru, fr, de.
|
|
472
464
|
|
|
473
465
|
**Q : Cela fonctionne-t-il avec les monorepos ?**
|
|
474
|
-
R : Oui
|
|
466
|
+
R : Oui. Turborepo (`turbo.json`), pnpm workspaces (`pnpm-workspace.yaml`), Lerna (`lerna.json`) et les npm/yarn workspaces (`package.json#workspaces`) sont reconnus par le stack-detector, et chaque app obtient sa propre analyse. D'autres layouts (NX, par exemple) ne sont pas détectés explicitement, mais les patterns génériques `apps/*/` et `packages/*/` restent captés par les scanners par stack.
|
|
475
467
|
|
|
476
|
-
**Q : Et si Claude Code génère des rules avec lesquelles je suis
|
|
477
|
-
R : Éditez-les directement
|
|
468
|
+
**Q : Et si Claude Code génère des rules avec lesquelles je ne suis pas d'accord ?**
|
|
469
|
+
R : Éditez-les directement, puis lancez `npx claudeos-core lint` pour vérifier que CLAUDE.md reste structurellement valide. Les éditions sont préservées lors des prochains `init` (sans `--force`), car le mécanisme de reprise saute les passes dont les markers existent déjà.
|
|
478
470
|
|
|
479
471
|
**Q : Où signaler les bugs ?**
|
|
480
|
-
R : [GitHub Issues](https://github.com/claudeos-core/claudeos-core/issues). Pour les problèmes de sécurité, voir [SECURITY.md](SECURITY.md).
|
|
472
|
+
R : Sur les [GitHub Issues](https://github.com/claudeos-core/claudeos-core/issues). Pour les problèmes de sécurité, voir [SECURITY.md](SECURITY.md).
|
|
473
|
+
|
|
474
|
+
---
|
|
475
|
+
|
|
476
|
+
## Si cela vous a fait gagner du temps
|
|
477
|
+
|
|
478
|
+
Une ⭐ sur GitHub aide à garder le projet visible et à le faire découvrir. Les issues, les PR et les contributions de templates de stack sont les bienvenues. Voir [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
481
479
|
|
|
482
480
|
---
|
|
483
481
|
|
|
@@ -485,15 +483,15 @@ R : [GitHub Issues](https://github.com/claudeos-core/claudeos-core/issues). Pour
|
|
|
485
483
|
|
|
486
484
|
| Sujet | À lire |
|
|
487
485
|
|---|---|
|
|
488
|
-
|
|
|
486
|
+
| Fonctionnement du pipeline 4-pass (plus en profondeur que le diagramme) | [docs/fr/architecture.md](docs/fr/architecture.md) |
|
|
489
487
|
| Diagrammes visuels (Mermaid) de l'architecture | [docs/fr/diagrams.md](docs/fr/diagrams.md) |
|
|
490
|
-
|
|
|
491
|
-
| Memory layer
|
|
492
|
-
| Les 5
|
|
493
|
-
| Toutes les commandes CLI et options | [docs/fr/commands.md](docs/fr/commands.md) |
|
|
488
|
+
| Stack detection : ce que chaque scanner cherche | [docs/fr/stacks.md](docs/fr/stacks.md) |
|
|
489
|
+
| Memory layer : decision logs et failure patterns | [docs/fr/memory-layer.md](docs/fr/memory-layer.md) |
|
|
490
|
+
| Les 5 validateurs en détail | [docs/fr/verification.md](docs/fr/verification.md) |
|
|
491
|
+
| Toutes les commandes CLI et leurs options | [docs/fr/commands.md](docs/fr/commands.md) |
|
|
494
492
|
| Installation manuelle (sans `npx`) | [docs/fr/manual-installation.md](docs/fr/manual-installation.md) |
|
|
495
|
-
| Overrides
|
|
496
|
-
| Sécurité : ce qui est préservé
|
|
493
|
+
| Overrides du scanner : `.claudeos-scan.json` | [docs/fr/advanced-config.md](docs/fr/advanced-config.md) |
|
|
494
|
+
| Sécurité : ce qui est préservé en cas de re-init | [docs/fr/safety.md](docs/fr/safety.md) |
|
|
497
495
|
| Comparaison avec des outils similaires (scope, pas qualité) | [docs/fr/comparison.md](docs/fr/comparison.md) |
|
|
498
496
|
| Erreurs et récupération | [docs/fr/troubleshooting.md](docs/fr/troubleshooting.md) |
|
|
499
497
|
|
|
@@ -501,14 +499,14 @@ R : [GitHub Issues](https://github.com/claudeos-core/claudeos-core/issues). Pour
|
|
|
501
499
|
|
|
502
500
|
## Contribuer
|
|
503
501
|
|
|
504
|
-
Les contributions sont
|
|
502
|
+
Les contributions sont bienvenues : ajout de support de stack, amélioration des prompts, corrections de bugs. Voir [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
505
503
|
|
|
506
|
-
Pour le
|
|
504
|
+
Pour le code de conduite et la politique de sécurité, voir [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) et [SECURITY.md](SECURITY.md).
|
|
507
505
|
|
|
508
506
|
## Licence
|
|
509
507
|
|
|
510
|
-
[ISC](LICENSE)
|
|
508
|
+
[ISC License](LICENSE). Libre pour tout usage, y compris commercial. © 2025–2026 ClaudeOS-Core contributors.
|
|
511
509
|
|
|
512
510
|
---
|
|
513
511
|
|
|
514
|
-
<sub>
|
|
512
|
+
<sub>Maintenu par l'équipe [claudeos-core](https://github.com/claudeos-core). Issues et PR sur <https://github.com/claudeos-core/claudeos-core>.</sub>
|