claudeos-core 2.0.2 → 2.1.0
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 +178 -0
- package/README.de.md +994 -880
- package/README.es.md +993 -880
- package/README.fr.md +993 -880
- package/README.hi.md +993 -880
- package/README.ja.md +993 -880
- package/README.ko.md +159 -47
- package/README.md +159 -46
- package/README.ru.md +993 -880
- package/README.vi.md +161 -48
- package/README.zh-CN.md +992 -880
- package/bin/cli.js +7 -2
- package/bin/commands/init.js +733 -143
- package/bin/commands/memory.js +17 -5
- package/bootstrap.sh +81 -81
- package/lib/expected-outputs.js +6 -7
- package/lib/memory-scaffold.js +84 -46
- package/lib/plan-parser.js +12 -0
- package/manifest-generator/index.js +16 -18
- package/package.json +1 -1
- package/pass-prompts/templates/angular/pass3.md +2 -10
- package/pass-prompts/templates/common/pass3-phase1.md +131 -0
- package/pass-prompts/templates/common/pass3a-facts.md +143 -0
- package/pass-prompts/templates/common/pass3b-core-header.md +58 -0
- package/pass-prompts/templates/common/pass3c-skills-guide-header.md +53 -0
- package/pass-prompts/templates/common/pass3d-plan-aux-header.md +57 -0
- package/pass-prompts/templates/common/pass4.md +4 -19
- package/pass-prompts/templates/java-spring/pass3.md +5 -15
- package/pass-prompts/templates/kotlin-spring/pass3.md +5 -15
- package/pass-prompts/templates/node-express/pass3.md +5 -14
- package/pass-prompts/templates/node-fastify/pass3.md +2 -10
- package/pass-prompts/templates/node-nestjs/pass3.md +5 -13
- package/pass-prompts/templates/node-nextjs/pass3.md +5 -14
- package/pass-prompts/templates/node-vite/pass3.md +95 -103
- package/pass-prompts/templates/python-django/pass3.md +5 -14
- package/pass-prompts/templates/python-fastapi/pass3.md +5 -14
- package/pass-prompts/templates/python-flask/pass3.md +95 -103
- package/pass-prompts/templates/vue-nuxt/pass3.md +2 -10
- package/plan-installer/pass3-context-builder.js +258 -0
- package/plan-installer/prompt-generator.js +9 -1
- package/plan-validator/index.js +23 -8
- package/sync-checker/index.js +44 -0
package/README.es.md
CHANGED
|
@@ -1,880 +1,993 @@
|
|
|
1
|
-
# ClaudeOS-Core
|
|
2
|
-
|
|
3
|
-
**La única herramienta que lee primero tu código fuente, confirma tu stack y tus patrones mediante análisis determinístico, y luego genera reglas de Claude Code adaptadas exactamente a tu proyecto.**
|
|
4
|
-
|
|
5
|
-
```bash
|
|
6
|
-
npx claudeos-core init
|
|
7
|
-
```
|
|
8
|
-
|
|
9
|
-
ClaudeOS-Core lee tu codebase, extrae cada patrón que encuentra y genera un conjunto completo de Standards, Rules, Skills y Guides adaptados a _tu_ proyecto. Después, cuando le digas a Claude Code "Crea un CRUD para pedidos", producirá código que coincide exactamente con tus patrones existentes.
|
|
10
|
-
|
|
11
|
-
[🇺🇸 English](./README.md) · [🇰🇷 한국어](./README.ko.md) · [🇨🇳 中文](./README.zh-CN.md) · [🇯🇵 日本語](./README.ja.md) · [🇻🇳 Tiếng Việt](./README.vi.md) · [🇮🇳 हिन्दी](./README.hi.md) · [🇷🇺 Русский](./README.ru.md) · [🇫🇷 Français](./README.fr.md) · [🇩🇪 Deutsch](./README.de.md)
|
|
12
|
-
|
|
13
|
-
---
|
|
14
|
-
|
|
15
|
-
##
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
**
|
|
34
|
-
|
|
35
|
-
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
**
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
|
95
|
-
|
|
96
|
-
|
|
|
97
|
-
|
|
|
98
|
-
|
|
|
99
|
-
|
|
|
100
|
-
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
|
109
|
-
|
|
110
|
-
|
|
|
111
|
-
|
|
|
112
|
-
|
|
|
113
|
-
|
|
|
114
|
-
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
### Detección de Dominios
|
|
119
|
-
|
|
120
|
-
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
###
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
#
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
#
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
-
|
|
268
|
-
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
```
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
"
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
```
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
#
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
```
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
│
|
|
443
|
-
├──
|
|
444
|
-
│
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
│ ├──
|
|
448
|
-
│
|
|
449
|
-
│
|
|
450
|
-
|
|
451
|
-
│
|
|
452
|
-
│
|
|
453
|
-
|
|
454
|
-
│
|
|
455
|
-
├──
|
|
456
|
-
│
|
|
457
|
-
│
|
|
458
|
-
│
|
|
459
|
-
│
|
|
460
|
-
│
|
|
461
|
-
│
|
|
462
|
-
│
|
|
463
|
-
│
|
|
464
|
-
│
|
|
465
|
-
│
|
|
466
|
-
|
|
467
|
-
│
|
|
468
|
-
│
|
|
469
|
-
│
|
|
470
|
-
│
|
|
471
|
-
│
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
###
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
El
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
|
586
|
-
|
|
587
|
-
|
|
|
588
|
-
|
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
```bash
|
|
619
|
-
#
|
|
620
|
-
npx claudeos-core
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
|
676
|
-
|
|
677
|
-
|
|
|
678
|
-
|
|
|
679
|
-
|
|
|
680
|
-
|
|
|
681
|
-
|
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
###
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
**
|
|
784
|
-
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
**
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
**
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
**
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
**
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
**
|
|
844
|
-
|
|
845
|
-
**
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
**
|
|
852
|
-
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
**
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
1
|
+
# ClaudeOS-Core
|
|
2
|
+
|
|
3
|
+
**La única herramienta que lee primero tu código fuente, confirma tu stack y tus patrones mediante análisis determinístico, y luego genera reglas de Claude Code adaptadas exactamente a tu proyecto.**
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npx claudeos-core init
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
ClaudeOS-Core lee tu codebase, extrae cada patrón que encuentra y genera un conjunto completo de Standards, Rules, Skills y Guides adaptados a _tu_ proyecto. Después, cuando le digas a Claude Code "Crea un CRUD para pedidos", producirá código que coincide exactamente con tus patrones existentes.
|
|
10
|
+
|
|
11
|
+
[🇺🇸 English](./README.md) · [🇰🇷 한국어](./README.ko.md) · [🇨🇳 中文](./README.zh-CN.md) · [🇯🇵 日本語](./README.ja.md) · [🇻🇳 Tiếng Việt](./README.vi.md) · [🇮🇳 हिन्दी](./README.hi.md) · [🇷🇺 Русский](./README.ru.md) · [🇫🇷 Français](./README.fr.md) · [🇩🇪 Deutsch](./README.de.md)
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Novedades en v2.1.0
|
|
16
|
+
|
|
17
|
+
v2.1.0 rediseña Pass 3 para eliminar los fallos `Prompt is too long` en proyectos medianos y grandes. Anteriormente, una única llamada de Pass 3 debía emitir todo el árbol de documentación de golpe — decenas de archivos entre `CLAUDE.md`, reglas, standards, skills y guides — y la salida acumulada superaba de forma confiable la ventana de contexto a partir de ~5 dominios. El fix es **estructural**, no un ajuste de prompt:
|
|
18
|
+
|
|
19
|
+
- **Modo split de Pass 3** (siempre activo) — Pass 3 se descompone en llamadas `claude -p` secuenciales (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`). Cada etapa arranca con una **ventana de contexto nueva**, así que el overflow por acumulación de salida deja de ser posible sin importar el tamaño del proyecto.
|
|
20
|
+
- **Fact sheet entre etapas** — La etapa `3a` lee el análisis de Pass 2 una sola vez y lo destila en un `pass3a-facts.md` de 5–10 KB. Todas las etapas posteriores referencian ese fact sheet en lugar de releer el `pass2-merged.json` de 100–500 KB, preservando la consistencia entre archivos a través de contextos nuevos.
|
|
21
|
+
- **Sub-división por lotes** (automática a partir de ≥16 dominios) — Las etapas 3b/3c se subdividen en lotes de 15 dominios cada uno, manteniendo cada etapa por debajo de ~50 archivos de salida. Un admin frontend React 19 + Vite 6 con 18 dominios se completó en **102 minutos con 101 archivos generados en 8 etapas, cero fallos por overflow** (ejecución real de producción, 2026-04-20).
|
|
22
|
+
- **Generación de Master plan eliminada** — Los archivos `claudeos-core/plan/*-master.md` ya no se generan. Los master plans eran un backup interno que Claude Code no consumía en runtime, y agregarlos en Pass 3d era una causa principal de overflow. Usa `git` para backup/restore en su lugar.
|
|
23
|
+
- **Gap-fill de Pass 4: `skills/00.shared/MANIFEST.md`** — Si Pass 3c omite el registro de skills (proyectos skill-sparse), Pass 4 ahora auto-crea un stub para que `.claude/rules/50.sync/03.skills-sync.md` nunca apunte a un archivo colgante.
|
|
24
|
+
|
|
25
|
+
También hay algunos fixes menores: `memory --help` ahora muestra la ayuda del subcomando memory (antes mostraba el top-level); `memory score` ya no deja líneas `importance` duplicadas; los marcadores de resumen de `memory compact` son ahora elementos de lista markdown propiamente formateados. Detalles completos: [CHANGELOG.md](./CHANGELOG.md).
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## ¿Por qué ClaudeOS-Core?
|
|
30
|
+
|
|
31
|
+
Cualquier otra herramienta de Claude Code funciona así:
|
|
32
|
+
|
|
33
|
+
> **El humano describe el proyecto → el LLM genera la documentación**
|
|
34
|
+
|
|
35
|
+
ClaudeOS-Core funciona así:
|
|
36
|
+
|
|
37
|
+
> **El código analiza tu fuente → el código construye un prompt adaptado → el LLM genera la documentación → el código verifica el resultado**
|
|
38
|
+
|
|
39
|
+
No es una pequeña diferencia. Aquí está por qué importa:
|
|
40
|
+
|
|
41
|
+
### El problema central: los LLMs adivinan. El código, no.
|
|
42
|
+
|
|
43
|
+
Cuando le pides a Claude que "analice este proyecto", **adivina** tu stack, tu ORM, tu estructura de dominios.
|
|
44
|
+
Puede ver `spring-boot` en tu `build.gradle` pero no darse cuenta de que usas MyBatis (no JPA).
|
|
45
|
+
Puede detectar un directorio `user/` sin percatarse de que tu proyecto usa empaquetado por capas primero (Patrón A), no por dominio primero (Patrón B).
|
|
46
|
+
|
|
47
|
+
**ClaudeOS-Core no adivina.** Antes de que Claude siquiera vea tu proyecto, el código Node.js ya ha:
|
|
48
|
+
|
|
49
|
+
- Parseado `build.gradle` / `package.json` / `pyproject.toml` y **confirmado** tu stack, ORM, BD y gestor de paquetes
|
|
50
|
+
- Escaneado tu estructura de directorios y **confirmado** tu lista de dominios con el conteo de archivos
|
|
51
|
+
- Clasificado la estructura de tu proyecto en uno de los 5 patrones Java, Kotlin CQRS/BFF, o Next.js App Router/FSD
|
|
52
|
+
- Dividido los dominios en grupos de tamaño óptimo que caben en la ventana de contexto de Claude
|
|
53
|
+
- Ensamblado un prompt específico del stack con todos los hechos confirmados inyectados
|
|
54
|
+
|
|
55
|
+
Cuando Claude recibe el prompt, no queda nada por adivinar. El stack está confirmado. Los dominios están confirmados. El patrón estructural está confirmado. El único trabajo de Claude es generar documentación que coincida con estos **hechos confirmados**.
|
|
56
|
+
|
|
57
|
+
### El resultado
|
|
58
|
+
|
|
59
|
+
Otras herramientas producen documentación "generalmente buena".
|
|
60
|
+
ClaudeOS-Core produce documentación que sabe que tu proyecto usa `ApiResponse.ok()` (no `ResponseEntity.success()`), que tus mappers MyBatis XML viven en `src/main/resources/mybatis/mappers/`, y que tu estructura de paquetes es `com.company.module.{domain}.controller` — porque leyó tu código real.
|
|
61
|
+
|
|
62
|
+
### Antes y después
|
|
63
|
+
|
|
64
|
+
**Sin ClaudeOS-Core** — le pides a Claude Code que cree un CRUD de Order:
|
|
65
|
+
```
|
|
66
|
+
❌ Usa un repository estilo JPA (tu proyecto usa MyBatis)
|
|
67
|
+
❌ Crea ResponseEntity.success() (tu wrapper es ApiResponse.ok())
|
|
68
|
+
❌ Coloca archivos en order/controller/ (tu proyecto usa controller/order/)
|
|
69
|
+
❌ Genera comentarios en inglés (tu equipo escribe comentarios en español)
|
|
70
|
+
→ Pasas 20 minutos corrigiendo cada archivo generado
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
**Con ClaudeOS-Core** — `.claude/rules/` ya contiene tus patrones confirmados:
|
|
74
|
+
```
|
|
75
|
+
✅ Genera mapper MyBatis + XML (detectado desde build.gradle)
|
|
76
|
+
✅ Usa ApiResponse.ok() (extraído de tu fuente real)
|
|
77
|
+
✅ Coloca archivos en controller/order/ (Patrón A confirmado por el escaneo estructural)
|
|
78
|
+
✅ Comentarios en español (--lang es aplicado)
|
|
79
|
+
→ El código generado coincide con las convenciones de tu proyecto al instante
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Esta diferencia se acumula. 10 tareas/día × 20 minutos ahorrados = **más de 3 horas/día**.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Stacks Soportados
|
|
87
|
+
|
|
88
|
+
| Stack | Detección | Profundidad de análisis |
|
|
89
|
+
|---|---|---|
|
|
90
|
+
| **Java / Spring Boot** | `build.gradle`, `pom.xml`, 5 patrones de paquete | 10 categorías, 59 sub-ítems |
|
|
91
|
+
| **Kotlin / Spring Boot** | `build.gradle.kts`, kotlin plugin, `settings.gradle.kts`, auto-detección CQRS/BFF | 12 categorías, 95 sub-ítems |
|
|
92
|
+
| **Node.js / Express** | `package.json` | 9 categorías, 57 sub-ítems |
|
|
93
|
+
| **Node.js / NestJS** | `package.json` (`@nestjs/core`) | 10 categorías, 68 sub-ítems |
|
|
94
|
+
| **Next.js / React** | `package.json`, `next.config.*`, soporte FSD | 9 categorías, 55 sub-ítems |
|
|
95
|
+
| **Vue / Nuxt** | `package.json`, `nuxt.config.*`, Composition API | 9 categorías, 58 sub-ítems |
|
|
96
|
+
| **Python / Django** | `requirements.txt`, `pyproject.toml` | 10 categorías, 55 sub-ítems |
|
|
97
|
+
| **Python / FastAPI** | `requirements.txt`, `pyproject.toml` | 10 categorías, 58 sub-ítems |
|
|
98
|
+
| **Node.js / Fastify** | `package.json` | 10 categorías, 62 sub-ítems |
|
|
99
|
+
| **Vite / React SPA** | `package.json`, `vite.config.*` | 9 categorías, 55 sub-ítems |
|
|
100
|
+
| **Angular** | `package.json`, `angular.json` | 12 categorías, 78 sub-ítems |
|
|
101
|
+
|
|
102
|
+
Auto-detectado: lenguaje y versión, framework y versión (incluyendo Vite como framework SPA), ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy, etc.), base de datos (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), gestor de paquetes (Gradle, Maven, npm, yarn, pnpm, pip, poetry), arquitectura (CQRS, BFF — a partir de los nombres de módulos), estructura multi-módulo (desde settings.gradle), monorepo (Turborepo, pnpm-workspace, Lerna, npm/yarn workspaces).
|
|
103
|
+
|
|
104
|
+
**No tienes que especificar nada. Todo se detecta automáticamente.**
|
|
105
|
+
|
|
106
|
+
### Detección de Dominios Java (5 patrones con fallback)
|
|
107
|
+
|
|
108
|
+
| Prioridad | Patrón | Estructura | Ejemplo |
|
|
109
|
+
|---|---|---|---|
|
|
110
|
+
| A | Capa primero | `controller/{domain}/` | `controller/user/UserController.java` |
|
|
111
|
+
| B | Dominio primero | `{domain}/controller/` | `user/controller/UserController.java` |
|
|
112
|
+
| D | Prefijo de módulo | `{module}/{domain}/controller/` | `front/member/controller/MemberController.java` |
|
|
113
|
+
| E | DDD/Hexagonal | `{domain}/adapter/in/web/` | `user/adapter/in/web/UserController.java` |
|
|
114
|
+
| C | Plano | `controller/*.java` | `controller/UserController.java` → extrae `user` del nombre de clase |
|
|
115
|
+
|
|
116
|
+
Los dominios solo con servicios (sin controladores) también se detectan mediante directorios `service/`, `dao/`, `aggregator/`, `facade/`, `usecase/`, `orchestrator/`, `mapper/`, `repository/`. Se omiten: `common`, `config`, `util`, `core`, `front`, `admin`, `v1`, `v2`, etc.
|
|
117
|
+
|
|
118
|
+
### Detección de Dominios Kotlin Multi-Módulo
|
|
119
|
+
|
|
120
|
+
Para proyectos Kotlin con estructura Gradle multi-módulo (por ejemplo, monorepo CQRS):
|
|
121
|
+
|
|
122
|
+
| Paso | Qué hace | Ejemplo |
|
|
123
|
+
|---|---|---|
|
|
124
|
+
| 1 | Escanea `settings.gradle.kts` en busca de `include()` | Encuentra 14 módulos |
|
|
125
|
+
| 2 | Detecta el tipo de módulo desde el nombre | `reservation-command-server` → tipo: `command` |
|
|
126
|
+
| 3 | Extrae el dominio del nombre del módulo | `reservation-command-server` → dominio: `reservation` |
|
|
127
|
+
| 4 | Agrupa el mismo dominio entre módulos | `reservation-command-server` + `common-query-server` → 1 dominio |
|
|
128
|
+
| 5 | Detecta la arquitectura | Tiene módulos `command` + `query` → CQRS |
|
|
129
|
+
|
|
130
|
+
Tipos de módulo soportados: `command`, `query`, `bff`, `integration`, `standalone`, `library`. Las bibliotecas compartidas (`shared-lib`, `integration-lib`) se detectan como dominios especiales.
|
|
131
|
+
|
|
132
|
+
### Detección de Dominios Frontend
|
|
133
|
+
|
|
134
|
+
- **App Router**: `app/{domain}/page.tsx` (Next.js)
|
|
135
|
+
- **Pages Router**: `pages/{domain}/index.tsx`
|
|
136
|
+
- **FSD (Feature-Sliced Design)**: `features/*/`, `widgets/*/`, `entities/*/`
|
|
137
|
+
- **División RSC/Client**: Detecta el patrón `client.tsx`, realiza seguimiento de la separación de componentes Server/Client
|
|
138
|
+
- **Rutas anidadas no estándar**: Detecta pages, components y capas FSD bajo rutas `src/*/` (ej: `src/admin/pages/dashboard/`, `src/admin/components/form/`, `src/admin/features/billing/`)
|
|
139
|
+
- **Detección platform/tier-split (v2.0.0)**: Reconoce layouts `src/{platform}/{subapp}/` — `{platform}` puede ser una palabra clave de dispositivo/objetivo (`desktop`, `pc`, `web`, `mobile`, `mc`, `mo`, `sp`, `tablet`, `tab`, `pwa`, `tv`, `ctv`, `ott`, `watch`, `wear`) o una palabra clave de nivel de acceso (`admin`, `cms`, `backoffice`, `back-office`, `portal`). Emite un dominio por cada par `(platform, subapp)` con el nombre `{platform}-{subapp}` y recuentos por dominio para routes/components/layouts/hooks. Se ejecuta simultáneamente sobre Angular, Next.js, React y Vue (glob multi-extensión `{tsx,jsx,ts,js,vue}`). Requiere ≥2 archivos fuente por subapp para evitar dominios ruidosos de 1 solo archivo.
|
|
140
|
+
- **División por plataforma en monorepo (v2.0.0)**: El escaneo de plataforma también coincide con `{apps,packages}/*/src/{platform}/{subapp}/` (Turborepo/pnpm workspace con `src/`) y `{apps,packages}/{platform}/{subapp}/` (workspaces sin envoltorio `src/`).
|
|
141
|
+
- **Fallback E — archivo de rutas (v2.0.0)**: Cuando los escáneres principales + los fallbacks A–D devuelven 0, hace un glob `**/routes/*.{tsx,jsx,ts,js,vue}` y agrupa por el nombre del directorio padre de `routes`. Captura proyectos de enrutamiento por archivo con React Router (CRA/Vite + `react-router`) que no encajan en los layouts `page.tsx` de Next.js ni de FSD. Se filtran los nombres de padre genéricos (`src`, `app`, `pages`).
|
|
142
|
+
- **Fallback de configuración**: Detecta Next.js/Vite/Nuxt desde archivos de configuración cuando no están en `package.json` (soporte de monorepo)
|
|
143
|
+
- **Fallback de directorio profundo**: Para proyectos React/CRA/Vite/Vue/RN, escanea `**/components/*/`, `**/views/*/`, `**/screens/*/`, `**/containers/*/`, `**/pages/*/`, `**/routes/*/`, `**/modules/*/`, `**/domains/*/` a cualquier profundidad
|
|
144
|
+
- **Listas de ignorados compartidas (v2.0.0)**: Todos los escáneres comparten `BUILD_IGNORE_DIRS` (`node_modules`, `build`, `dist`, `out`, `.next`, `.nuxt`, `.svelte-kit`, `.angular`, `.turbo`, `.cache`, `.parcel-cache`, `coverage`, `storybook-static`, `.vercel`, `.netlify`) y `TEST_FILE_IGNORE` (spec/test/stories/e2e/cy + `__snapshots__`/`__tests__`) para que los resultados de build y las fixtures de test no inflen los recuentos por dominio.
|
|
145
|
+
|
|
146
|
+
### Overrides de escáner (v2.0.0)
|
|
147
|
+
|
|
148
|
+
Coloca un `.claudeos-scan.json` opcional en la raíz de tu proyecto para extender los valores por defecto del escáner sin modificar el toolkit. Todos los campos son **aditivos** — las entradas del usuario extienden los valores por defecto, nunca los reemplazan:
|
|
149
|
+
|
|
150
|
+
```json
|
|
151
|
+
{
|
|
152
|
+
"frontendScan": {
|
|
153
|
+
"platformKeywords": ["kiosk"],
|
|
154
|
+
"skipSubappNames": ["legacy"],
|
|
155
|
+
"minSubappFiles": 3
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
| Campo | Por defecto | Propósito |
|
|
161
|
+
|---|---|---|
|
|
162
|
+
| `platformKeywords` | lista integrada indicada arriba | Palabras clave `{platform}` adicionales para el escaneo de plataforma (ej: `kiosk`, `vr`, `embedded`) |
|
|
163
|
+
| `skipSubappNames` | solo directorios estructurales | Nombres de subapp adicionales para excluir de la emisión de dominios del escaneo de plataforma |
|
|
164
|
+
| `minSubappFiles` | `2` | Anula el recuento mínimo de archivos requerido para que un subapp se convierta en dominio |
|
|
165
|
+
|
|
166
|
+
Archivo ausente o JSON mal formado → cae silenciosamente a los valores por defecto (no crashea). Uso típico: activar una abreviatura corta (`adm`, `bo`) que la lista integrada excluye por ser demasiado ambigua, o aumentar `minSubappFiles` para monorepos ruidosos.
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## Inicio Rápido
|
|
171
|
+
|
|
172
|
+
### Prerrequisitos
|
|
173
|
+
|
|
174
|
+
- **Node.js** v18+
|
|
175
|
+
- **Claude Code CLI** (instalado y autenticado)
|
|
176
|
+
|
|
177
|
+
### Instalación
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
cd /your/project/root
|
|
181
|
+
|
|
182
|
+
# Opción A: npx (recomendado — no requiere instalación)
|
|
183
|
+
npx claudeos-core init
|
|
184
|
+
|
|
185
|
+
# Opción B: instalación global
|
|
186
|
+
npm install -g claudeos-core
|
|
187
|
+
claudeos-core init
|
|
188
|
+
|
|
189
|
+
# Opción C: devDependency del proyecto
|
|
190
|
+
npm install --save-dev claudeos-core
|
|
191
|
+
npx claudeos-core init
|
|
192
|
+
|
|
193
|
+
# Opción D: git clone (para desarrollo/contribución)
|
|
194
|
+
git clone https://github.com/claudeos-core/claudeos-core.git claudeos-core-tools
|
|
195
|
+
|
|
196
|
+
# Multiplataforma (PowerShell, CMD, Bash, Zsh — cualquier terminal)
|
|
197
|
+
node claudeos-core-tools/bin/cli.js init
|
|
198
|
+
|
|
199
|
+
# Linux/macOS (solo Bash)
|
|
200
|
+
bash claudeos-core-tools/bootstrap.sh
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### Idioma de salida (10 idiomas)
|
|
204
|
+
|
|
205
|
+
Cuando ejecutas `init` sin `--lang`, aparece un selector interactivo — usa las flechas o las teclas numéricas para elegir:
|
|
206
|
+
|
|
207
|
+
```
|
|
208
|
+
╔══════════════════════════════════════════════════╗
|
|
209
|
+
║ Select generated document language (required) ║
|
|
210
|
+
╚══════════════════════════════════════════════════╝
|
|
211
|
+
|
|
212
|
+
Los archivos generados (CLAUDE.md, Standards, Rules,
|
|
213
|
+
Skills, Guides) se escribirán en español.
|
|
214
|
+
|
|
215
|
+
1. en — English
|
|
216
|
+
2. ko — 한국어 (Korean)
|
|
217
|
+
3. zh-CN — 简体中文 (Chinese Simplified)
|
|
218
|
+
4. ja — 日本語 (Japanese)
|
|
219
|
+
❯ 5. es — Español (Spanish)
|
|
220
|
+
6. vi — Tiếng Việt (Vietnamese)
|
|
221
|
+
7. hi — हिन्दी (Hindi)
|
|
222
|
+
8. ru — Русский (Russian)
|
|
223
|
+
9. fr — Français (French)
|
|
224
|
+
10. de — Deutsch (German)
|
|
225
|
+
|
|
226
|
+
↑↓ Move 1-0 Jump Enter Select ESC Cancel
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
La descripción cambia al idioma seleccionado a medida que navegas. Para saltarte el selector, pasa `--lang` directamente:
|
|
230
|
+
|
|
231
|
+
```bash
|
|
232
|
+
npx claudeos-core init --lang ko # Coreano
|
|
233
|
+
npx claudeos-core init --lang ja # Japonés
|
|
234
|
+
npx claudeos-core init --lang en # Inglés (por defecto)
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
> **Nota:** Esto establece el idioma solo para los archivos de documentación generados. El análisis de código (Pass 1–2) siempre se ejecuta en inglés; la salida generada (Pass 3) se escribe en el idioma elegido. Los ejemplos de código dentro de los archivos generados mantienen la sintaxis original del lenguaje de programación.
|
|
238
|
+
|
|
239
|
+
Eso es todo. Tras 10 minutos (proyecto pequeño) a 2 horas (monorepo de 60+ dominios), toda la documentación se genera y queda lista para usar. La CLI muestra una barra de progreso con porcentaje, tiempo transcurrido y ETA para cada pass. Ver [Auto-escalado por tamaño del proyecto](#auto-escalado-por-tamaño-del-proyecto) para los tiempos detallados por tamaño de proyecto.
|
|
240
|
+
|
|
241
|
+
### Instalación Manual Paso a Paso
|
|
242
|
+
|
|
243
|
+
Si quieres control total sobre cada fase — o si el pipeline automatizado falla en algún paso — puedes ejecutar cada etapa manualmente. Esto también sirve para entender cómo funciona ClaudeOS-Core internamente.
|
|
244
|
+
|
|
245
|
+
#### Paso 1: Clonar e instalar dependencias
|
|
246
|
+
|
|
247
|
+
```bash
|
|
248
|
+
cd /your/project/root
|
|
249
|
+
|
|
250
|
+
git clone https://github.com/claudeos-core/claudeos-core.git claudeos-core-tools
|
|
251
|
+
cd claudeos-core-tools && npm install && cd ..
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
#### Paso 2: Crear la estructura de directorios
|
|
255
|
+
|
|
256
|
+
```bash
|
|
257
|
+
# Rules (v2.0.0: añadido 60.memory)
|
|
258
|
+
mkdir -p .claude/rules/{00.core,10.backend,20.frontend,30.security-db,40.infra,50.sync,60.memory}
|
|
259
|
+
|
|
260
|
+
# Standards
|
|
261
|
+
mkdir -p claudeos-core/standard/{00.core,10.backend-api,20.frontend-ui,30.security-db,40.infra,50.verification,90.optional}
|
|
262
|
+
|
|
263
|
+
# Skills
|
|
264
|
+
mkdir -p claudeos-core/skills/{00.shared,10.backend-crud/scaffold-crud-feature,20.frontend-page/scaffold-page-feature,50.testing,90.experimental}
|
|
265
|
+
|
|
266
|
+
# Guide, Database, MCP, Generated, Memory (v2.0.0: añadido memory; v2.1.0: eliminado plan)
|
|
267
|
+
mkdir -p claudeos-core/guide/{01.onboarding,02.usage,03.troubleshooting,04.architecture}
|
|
268
|
+
mkdir -p claudeos-core/{database,mcp-guide,generated,memory}
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
> **Nota v2.1.0:** El directorio `claudeos-core/plan/` ya no se crea. La generación de Master plan se eliminó porque los master plans eran un backup interno que Claude Code nunca leía en runtime, y agregarlos disparaba fallos `Prompt is too long`. Usa `git` para backup/restore.
|
|
272
|
+
|
|
273
|
+
#### Paso 3: Ejecutar plan-installer (análisis del proyecto)
|
|
274
|
+
|
|
275
|
+
Esto escanea tu proyecto, detecta el stack, encuentra dominios, los divide en grupos y genera prompts.
|
|
276
|
+
|
|
277
|
+
```bash
|
|
278
|
+
node claudeos-core-tools/plan-installer/index.js
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
**Salida (en `claudeos-core/generated/`):**
|
|
282
|
+
- `project-analysis.json` — stack detectado, dominios, info de frontend
|
|
283
|
+
- `domain-groups.json` — grupos de dominios para Pass 1
|
|
284
|
+
- `pass1-backend-prompt.md` / `pass1-frontend-prompt.md` — prompts de análisis
|
|
285
|
+
- `pass2-prompt.md` — prompt de merge
|
|
286
|
+
- `pass3-prompt.md` — plantilla de prompt de Pass 3 con el bloque Phase 1 "Read Once, Extract Facts" anteanteado (Rules A–E). El pipeline automatizado divide Pass 3 en múltiples etapas en runtime; esta plantilla alimenta cada etapa.
|
|
287
|
+
- `pass3-context.json` — resumen slim del proyecto (< 5 KB, construido tras Pass 2) que los prompts de Pass 3 prefieren frente al `pass2-merged.json` completo (v2.1.0)
|
|
288
|
+
- `pass4-prompt.md` — prompt de scaffolding de memory L4 (v2.0.0; usa el mismo `staging-override.md` para las escrituras de reglas `60.memory/`)
|
|
289
|
+
|
|
290
|
+
Puedes inspeccionar estos archivos para verificar la precisión de la detección antes de continuar.
|
|
291
|
+
|
|
292
|
+
#### Paso 4: Pass 1 — Análisis profundo del código (por grupo de dominios)
|
|
293
|
+
|
|
294
|
+
Ejecuta Pass 1 por cada grupo de dominios. Consulta `domain-groups.json` para saber cuántos grupos hay.
|
|
295
|
+
|
|
296
|
+
```bash
|
|
297
|
+
# Comprueba cuántos grupos hay
|
|
298
|
+
cat claudeos-core/generated/domain-groups.json | node -e "
|
|
299
|
+
const g = JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
|
|
300
|
+
g.groups.forEach((g,i) => console.log('Group '+(i+1)+': ['+g.domains.join(', ')+'] ('+g.type+', ~'+g.estimatedFiles+' files)'));
|
|
301
|
+
"
|
|
302
|
+
|
|
303
|
+
# Ejecuta Pass 1 para cada grupo (reemplaza los dominios y el número de grupo)
|
|
304
|
+
# Nota: v1.6.1+ usa String.replace() de Node.js en vez de perl — perl ya
|
|
305
|
+
# no es necesario, y la semántica de funciones de reemplazo previene la inyección
|
|
306
|
+
# regex de los caracteres $/&/$1 que pudieran aparecer en los nombres de dominio.
|
|
307
|
+
#
|
|
308
|
+
# Para el grupo 1:
|
|
309
|
+
DOMAIN_LIST="user, order, product" PASS_NUM=1 node -e "
|
|
310
|
+
const fs = require('fs');
|
|
311
|
+
const tpl = fs.readFileSync('claudeos-core/generated/pass1-backend-prompt.md','utf-8');
|
|
312
|
+
const out = tpl
|
|
313
|
+
.replace(/\{\{DOMAIN_GROUP\}\}/g, () => process.env.DOMAIN_LIST)
|
|
314
|
+
.replace(/\{\{PASS_NUM\}\}/g, () => process.env.PASS_NUM);
|
|
315
|
+
process.stdout.write(out);
|
|
316
|
+
" | claude -p --dangerously-skip-permissions
|
|
317
|
+
|
|
318
|
+
# Para el grupo 2 (si existe):
|
|
319
|
+
DOMAIN_LIST="payment, system, delivery" PASS_NUM=2 node -e "
|
|
320
|
+
const fs = require('fs');
|
|
321
|
+
const tpl = fs.readFileSync('claudeos-core/generated/pass1-backend-prompt.md','utf-8');
|
|
322
|
+
const out = tpl
|
|
323
|
+
.replace(/\{\{DOMAIN_GROUP\}\}/g, () => process.env.DOMAIN_LIST)
|
|
324
|
+
.replace(/\{\{PASS_NUM\}\}/g, () => process.env.PASS_NUM);
|
|
325
|
+
process.stdout.write(out);
|
|
326
|
+
" | claude -p --dangerously-skip-permissions
|
|
327
|
+
|
|
328
|
+
# Para grupos frontend, sustituye pass1-backend-prompt.md → pass1-frontend-prompt.md
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
**Verificar:** `ls claudeos-core/generated/pass1-*.json` debería mostrar un JSON por grupo.
|
|
332
|
+
|
|
333
|
+
#### Paso 5: Pass 2 — Combinar resultados del análisis
|
|
334
|
+
|
|
335
|
+
```bash
|
|
336
|
+
cat claudeos-core/generated/pass2-prompt.md \
|
|
337
|
+
| claude -p --dangerously-skip-permissions
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
**Verificar:** `claudeos-core/generated/pass2-merged.json` debe existir con 9+ claves de nivel superior.
|
|
341
|
+
|
|
342
|
+
#### Paso 6: Pass 3 — Generar toda la documentación (dividido en varias etapas)
|
|
343
|
+
|
|
344
|
+
**Nota v2.1.0:** Pass 3 **siempre se ejecuta en modo split** por parte del pipeline automatizado. Cada etapa es una llamada `claude -p` separada con una ventana de contexto nueva, así que el overflow por acumulación de salida es estructuralmente imposible sin importar el tamaño del proyecto. La plantilla `pass3-prompt.md` se ensambla por etapa con una directiva `STAGE:` que le indica a Claude qué subconjunto de archivos debe emitir. En modo manual, el camino más simple sigue siendo alimentar la plantilla completa y dejar que Claude genere todo en una sola llamada — pero esto solo es fiable en proyectos pequeños (≤5 dominios). Para cualquier cosa más grande, usa `npx claudeos-core init` para que el runner de split gestione la orquestación de etapas.
|
|
345
|
+
|
|
346
|
+
**Modo de llamada única (solo proyectos pequeños, ≤5 dominios):**
|
|
347
|
+
|
|
348
|
+
```bash
|
|
349
|
+
cat claudeos-core/generated/pass3-prompt.md \
|
|
350
|
+
| claude -p --dangerously-skip-permissions
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
**Modo etapa por etapa (recomendado para todos los tamaños de proyecto):**
|
|
354
|
+
|
|
355
|
+
El pipeline automatizado ejecuta estas etapas. La lista de etapas es:
|
|
356
|
+
|
|
357
|
+
| Etapa | Escribe | Notas |
|
|
358
|
+
|---|---|---|
|
|
359
|
+
| `3a` | `pass3a-facts.md` (fact sheet destilado de 5–10 KB) | Lee `pass2-merged.json` una sola vez; las etapas posteriores referencian este archivo |
|
|
360
|
+
| `3b-core` | `CLAUDE.md`, `standard/` común, `.claude/rules/` común | Archivos transversales al proyecto; sin salida específica de dominio |
|
|
361
|
+
| `3b-1..N` | `standard/60.domains/*.md` específicos de dominio + reglas de dominio | Lote de ≤15 dominios por etapa (auto-dividido a partir de ≥16 dominios) |
|
|
362
|
+
| `3c-core` | `guide/` (9 archivos), `skills/00.shared/MANIFEST.md`, orquestadores `skills/*/` | Skills compartidos y todas las guías de cara al usuario |
|
|
363
|
+
| `3c-1..N` | Sub-skills de dominio bajo `skills/20.frontend-page/scaffold-page-feature/` | Lote de ≤15 dominios por etapa |
|
|
364
|
+
| `3d-aux` | `database/`, `mcp-guide/` | Tamaño fijo, independiente del número de dominios |
|
|
365
|
+
|
|
366
|
+
Para un proyecto de 1–15 dominios esto se expande a 4 etapas (`3a`, `3b-core`, `3c-core`, `3d-aux` — sin sub-división por lotes). Para 16–30 dominios se expande a 8 etapas (`3b` y `3c` cada una sub-dividida en 2 lotes). Ver [Auto-escalado por tamaño del proyecto](#auto-escalado-por-tamaño-del-proyecto) para la tabla completa.
|
|
367
|
+
|
|
368
|
+
**Verificar:** `CLAUDE.md` debe existir en la raíz de tu proyecto, y debe escribirse el marcador `claudeos-core/generated/pass3-complete.json`. En modo split, el marcador contiene `mode: "split"` y un array `groupsCompleted` que lista cada etapa que terminó — la lógica de marcador parcial usa esto para reanudar desde la etapa correcta tras un crash en lugar de reiniciar desde `3a` (lo que duplicaría el coste en tokens).
|
|
369
|
+
|
|
370
|
+
> **Nota de staging:** Pass 3 escribe los archivos de reglas primero en `claudeos-core/generated/.staged-rules/` porque la política de rutas sensibles de Claude Code bloquea las escrituras directas a `.claude/`. El pipeline automatizado gestiona el movimiento automáticamente tras cada etapa. Si ejecutas una etapa manualmente, tendrás que mover el árbol staged tú mismo: `mv claudeos-core/generated/.staged-rules/* .claude/rules/` (preservando los sub-paths).
|
|
371
|
+
|
|
372
|
+
#### Paso 7: Pass 4 — Scaffolding de memory
|
|
373
|
+
|
|
374
|
+
```bash
|
|
375
|
+
cat claudeos-core/generated/pass4-prompt.md \
|
|
376
|
+
| claude -p --dangerously-skip-permissions
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
**Verificar:** `claudeos-core/memory/` debe contener 4 archivos (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`), `.claude/rules/60.memory/` debe contener 4 archivos de reglas, y `CLAUDE.md` debe tener ahora una sección `## Memory (L4)` añadida. Marcador: `claudeos-core/generated/pass4-memory.json`.
|
|
380
|
+
|
|
381
|
+
> **Gap-fill v2.1.0:** Pass 4 también asegura que `claudeos-core/skills/00.shared/MANIFEST.md` exista. Si Pass 3c lo omitió (posible en proyectos skill-sparse porque las plantillas `pass3.md` de cada stack listan `MANIFEST.md` entre los targets de generación sin marcarlo como REQUIRED), el gap-fill crea un stub mínimo para que `.claude/rules/50.sync/03.skills-sync.md` siempre tenga un target de referencia válido. Idempotente: omite el paso si el archivo ya tiene contenido real (>20 caracteres).
|
|
382
|
+
|
|
383
|
+
> **Nota:** Si `claude -p` falla o `pass4-prompt.md` está ausente, el pipeline automatizado cae a un scaffold estático vía `lib/memory-scaffold.js` (con traducción por Claude cuando `--lang` no es inglés). El fallback estático solo se ejecuta dentro de `npx claudeos-core init` — el modo manual requiere que Pass 4 tenga éxito.
|
|
384
|
+
|
|
385
|
+
#### Paso 8: Ejecutar las herramientas de verificación
|
|
386
|
+
|
|
387
|
+
```bash
|
|
388
|
+
# Generar metadata (requerido antes de otras comprobaciones)
|
|
389
|
+
node claudeos-core-tools/manifest-generator/index.js
|
|
390
|
+
|
|
391
|
+
# Ejecutar todas las comprobaciones
|
|
392
|
+
node claudeos-core-tools/health-checker/index.js
|
|
393
|
+
|
|
394
|
+
# O ejecutar comprobaciones individuales:
|
|
395
|
+
node claudeos-core-tools/plan-validator/index.js --check # Consistencia Plan ↔ disco
|
|
396
|
+
node claudeos-core-tools/sync-checker/index.js # Archivos no registrados/huérfanos
|
|
397
|
+
node claudeos-core-tools/content-validator/index.js # Comprobaciones de calidad de archivos (incl. sección memory/ [9/9])
|
|
398
|
+
node claudeos-core-tools/pass-json-validator/index.js # Comprobaciones de JSON Pass 1–4 + marcador de finalización
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
#### Paso 9: Verificar los resultados
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
# Contar archivos generados
|
|
405
|
+
find .claude claudeos-core -type f | grep -v node_modules | grep -v '/generated/' | wc -l
|
|
406
|
+
|
|
407
|
+
# Revisar CLAUDE.md
|
|
408
|
+
head -30 CLAUDE.md
|
|
409
|
+
|
|
410
|
+
# Revisar un archivo standard
|
|
411
|
+
cat claudeos-core/standard/00.core/01.project-overview.md | head -20
|
|
412
|
+
|
|
413
|
+
# Revisar reglas
|
|
414
|
+
ls .claude/rules/*/
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
> **Consejo:** Si algún paso falla, puedes corregir el problema y volver a ejecutar solo ese paso. Los resultados de Pass 1/2 se cachean — si `pass1-N.json` o `pass2-merged.json` ya existe, el pipeline automatizado los omite. Usa `npx claudeos-core init --force` para eliminar resultados previos y empezar desde cero.
|
|
418
|
+
|
|
419
|
+
### Empezar a Usar
|
|
420
|
+
|
|
421
|
+
```
|
|
422
|
+
# En Claude Code — simplemente pregunta de forma natural:
|
|
423
|
+
"Crea un CRUD para el dominio order"
|
|
424
|
+
"Añade un API de autenticación de usuarios"
|
|
425
|
+
"Refactoriza este código para que coincida con los patrones del proyecto"
|
|
426
|
+
|
|
427
|
+
# Claude Code referencia automáticamente tus Standards, Rules y Skills generados.
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
---
|
|
431
|
+
|
|
432
|
+
## Cómo Funciona — Pipeline de 4 Passes
|
|
433
|
+
|
|
434
|
+
```
|
|
435
|
+
npx claudeos-core init
|
|
436
|
+
│
|
|
437
|
+
├── [1] npm install ← Dependencias (~10s)
|
|
438
|
+
├── [2] Estructura de directorios ← Crear carpetas (~1s)
|
|
439
|
+
├── [3] plan-installer (Node.js) ← Escaneo del proyecto (~5s)
|
|
440
|
+
│ ├── Auto-detecta stack (multi-stack aware)
|
|
441
|
+
│ ├── Extrae la lista de dominios (tagged: backend/frontend)
|
|
442
|
+
│ ├── Divide en grupos de dominios (por tipo)
|
|
443
|
+
│ ├── Construye pass3-context.json (resumen slim, v2.1.0)
|
|
444
|
+
│ └── Selecciona prompts específicos del stack (por tipo)
|
|
445
|
+
│
|
|
446
|
+
├── [4] Pass 1 × N (claude -p) ← Análisis profundo del código (~2-8min)
|
|
447
|
+
│ ├── ⚙️ Grupos backend → prompt específico de backend
|
|
448
|
+
│ └── 🎨 Grupos frontend → prompt específico de frontend
|
|
449
|
+
│
|
|
450
|
+
├── [5] Pass 2 × 1 (claude -p) ← Merge del análisis (~1min)
|
|
451
|
+
│ └── Consolida TODOS los resultados de Pass 1 en pass2-merged.json
|
|
452
|
+
│
|
|
453
|
+
├── [6] Pass 3 (modo split, v2.1.0) ← Genera todo
|
|
454
|
+
│ │
|
|
455
|
+
│ ├── 3a × 1 (claude -p) ← Extracción de hechos (~5-10min)
|
|
456
|
+
│ │ └── Lee pass2-merged.json una vez → pass3a-facts.md
|
|
457
|
+
│ │
|
|
458
|
+
│ ├── 3b-core × 1 (claude -p) ← CLAUDE.md + standard/rules comunes
|
|
459
|
+
│ ├── 3b-1..N × N (claude -p) ← Standards/reglas de dominio (≤15 dominios/lote)
|
|
460
|
+
│ │
|
|
461
|
+
│ ├── 3c-core × 1 (claude -p) ← Guides + skills compartidos + MANIFEST.md
|
|
462
|
+
│ ├── 3c-1..N × N (claude -p) ← Sub-skills de dominio (≤15 dominios/lote)
|
|
463
|
+
│ │
|
|
464
|
+
│ └── 3d-aux × 1 (claude -p) ← Stubs de database/ + mcp-guide/
|
|
465
|
+
│
|
|
466
|
+
├── [7] Pass 4 × 1 (claude -p) ← Memory scaffolding (~30s-5min)
|
|
467
|
+
│ ├── Seedea memory/ (decision-log, failure-patterns, …)
|
|
468
|
+
│ ├── Genera reglas 60.memory/
|
|
469
|
+
│ ├── Añade la sección "Memory (L4)" al CLAUDE.md
|
|
470
|
+
│ └── Gap-fill: asegura que skills/00.shared/MANIFEST.md exista (v2.1.0)
|
|
471
|
+
│
|
|
472
|
+
└── [8] Verificación ← Auto-ejecuta el health checker
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
### ¿Por qué 4 Passes?
|
|
476
|
+
|
|
477
|
+
**Pass 1** es el único pass que lee tu código fuente. Selecciona archivos representativos por dominio y extrae patrones de 55–95 categorías de análisis (según el stack). Para proyectos grandes, Pass 1 se ejecuta varias veces — una por cada grupo de dominios. En proyectos multi-stack (por ejemplo, Java backend + React frontend), los dominios backend y frontend usan **prompts de análisis diferentes** adaptados a cada stack.
|
|
478
|
+
|
|
479
|
+
**Pass 2** combina todos los resultados de Pass 1 en un análisis unificado: patrones comunes (100% compartidos), patrones mayoritarios (50%+ compartidos), patrones específicos de dominio, anti-patrones por severidad y preocupaciones transversales (naming, seguridad, BD, testing, logging, rendimiento). Los resultados de backend y frontend se combinan.
|
|
480
|
+
|
|
481
|
+
**Pass 3** (modo split, v2.1.0) toma el análisis combinado y genera todo el ecosistema de archivos (CLAUDE.md, reglas, standards, skills, guides) a través de múltiples llamadas `claude -p` secuenciales. La clave es que el overflow por acumulación de salida no es predecible desde el tamaño de entrada: el Pass 3 de llamada única funcionaba bien en proyectos de 2 dominios y fallaba de forma confiable a ~5 dominios, y la frontera de fallo variaba según lo verboso que resultara cada archivo. El modo split esquiva esto por completo — cada etapa arranca con una ventana de contexto nueva y escribe un subconjunto acotado de archivos. La consistencia entre etapas (que era la principal ventaja del enfoque de llamada única) se preserva mediante `pass3a-facts.md`, un fact sheet destilado de 5–10 KB que todas las etapas posteriores referencian.
|
|
482
|
+
|
|
483
|
+
La plantilla de prompt de Pass 3 también incluye un **bloque Phase 1 "Read Once, Extract Facts"** con cinco reglas que acotan aún más el volumen de salida:
|
|
484
|
+
|
|
485
|
+
- **Rule A** — Referencia la tabla de hechos; no releas `pass2-merged.json`.
|
|
486
|
+
- **Rule B** — Escritura idempotente de archivos (omitir si el target existe con contenido real), haciendo Pass 3 seguro de re-ejecutar tras una interrupción.
|
|
487
|
+
- **Rule C** — Consistencia entre archivos aplicada a través de la tabla de hechos como única fuente de verdad.
|
|
488
|
+
- **Rule D** — Concisión de salida: una línea (`[WRITE]`/`[SKIP]`) entre escrituras de archivo, sin restatear la tabla de hechos, sin echoar el contenido del archivo.
|
|
489
|
+
- **Rule E** — Comprobación idempotente por lote: un único `Glob` al inicio de PHASE 2 en vez de llamadas `Read` por cada target.
|
|
490
|
+
|
|
491
|
+
**Pass 4** scaffoldea la capa Memory L4: archivos persistentes de conocimiento de equipo (decision-log, failure-patterns, compaction policy, auto-rule-update) más las reglas `60.memory/` que indican a sesiones futuras cuándo y cómo leer/escribir esos archivos. La capa de memory es lo que permite que Claude Code acumule lecciones entre sesiones en lugar de redescubrirlas cada vez. Cuando `--lang` no es inglés, el contenido estático de fallback se traduce vía Claude antes de ser escrito. v2.1.0 añade un gap-fill para `skills/00.shared/MANIFEST.md` por si Pass 3c lo omitió.
|
|
492
|
+
|
|
493
|
+
---
|
|
494
|
+
|
|
495
|
+
## Estructura de Archivos Generados
|
|
496
|
+
|
|
497
|
+
```
|
|
498
|
+
your-project/
|
|
499
|
+
│
|
|
500
|
+
├── CLAUDE.md ← Punto de entrada de Claude Code
|
|
501
|
+
│
|
|
502
|
+
├── .claude/
|
|
503
|
+
│ └── rules/ ← Reglas disparadas por glob
|
|
504
|
+
│ ├── 00.core/
|
|
505
|
+
│ ├── 10.backend/
|
|
506
|
+
│ ├── 20.frontend/
|
|
507
|
+
│ ├── 30.security-db/
|
|
508
|
+
│ ├── 40.infra/
|
|
509
|
+
│ ├── 50.sync/ ← Reglas de recordatorio de sync
|
|
510
|
+
│ └── 60.memory/ ← Reglas de scope on-demand de memory L4 (v2.0.0)
|
|
511
|
+
│
|
|
512
|
+
├── claudeos-core/ ← Directorio principal de salida
|
|
513
|
+
│ ├── generated/ ← JSON de análisis + prompts dinámicos + marcadores de Pass (añadir a gitignore)
|
|
514
|
+
│ │ ├── project-analysis.json ← Info del stack (multi-stack aware)
|
|
515
|
+
│ │ ├── domain-groups.json ← Grupos con type: backend/frontend
|
|
516
|
+
│ │ ├── pass1-backend-prompt.md ← Prompt de análisis backend
|
|
517
|
+
│ │ ├── pass1-frontend-prompt.md ← Prompt de análisis frontend (si detectado)
|
|
518
|
+
│ │ ├── pass2-prompt.md ← Prompt de merge
|
|
519
|
+
│ │ ├── pass2-merged.json ← Salida de Pass 2 (consumido solo por Pass 3a)
|
|
520
|
+
│ │ ├── pass3-context.json ← Resumen slim (< 5 KB) para Pass 3 (v2.1.0)
|
|
521
|
+
│ │ ├── pass3-prompt.md ← Plantilla de prompt de Pass 3 (bloque Phase 1 anteanteado)
|
|
522
|
+
│ │ ├── pass3a-facts.md ← Fact sheet escrito por Pass 3a, leído por 3b/3c/3d (v2.1.0)
|
|
523
|
+
│ │ ├── pass4-prompt.md ← Prompt de scaffolding de memory (v2.0.0)
|
|
524
|
+
│ │ ├── pass3-complete.json ← Marcador de finalización de Pass 3 (modo split: incluye groupsCompleted, v2.1.0)
|
|
525
|
+
│ │ ├── pass4-memory.json ← Marcador de finalización de Pass 4 (salta en resume)
|
|
526
|
+
│ │ ├── rule-manifest.json ← Índice de archivos para las herramientas de verificación
|
|
527
|
+
│ │ ├── sync-map.json ← Mapeo Plan ↔ disco (vacío en v2.1.0; se conserva por compat con sync-checker)
|
|
528
|
+
│ │ ├── stale-report.json ← Resultados consolidados de verificación
|
|
529
|
+
│ │ ├── .i18n-cache-<lang>.json ← Caché de traducción (no inglés `--lang`)
|
|
530
|
+
│ │ └── .staged-rules/ ← Dir de staging transitorio para escrituras de `.claude/rules/` (auto-movido + limpiado)
|
|
531
|
+
│ ├── standard/ ← Estándares de codificación (15-19 archivos + por dominio en 60.domains/)
|
|
532
|
+
│ │ ├── 00.core/ ← Visión general, arquitectura, naming
|
|
533
|
+
│ │ ├── 10.backend-api/ ← Patrones de API (específicos del stack)
|
|
534
|
+
│ │ ├── 20.frontend-ui/ ← Patrones frontend (si detectado)
|
|
535
|
+
│ │ ├── 30.security-db/ ← Seguridad, esquema BD, utilidades
|
|
536
|
+
│ │ ├── 40.infra/ ← Config, logging, CI/CD
|
|
537
|
+
│ │ ├── 50.verification/ ← Build verification, testing
|
|
538
|
+
│ │ ├── 60.domains/ ← Standards por dominio (escritos por Pass 3b-N, v2.1.0)
|
|
539
|
+
│ │ └── 90.optional/ ← Convenciones opcionales (extras específicos del stack)
|
|
540
|
+
│ ├── skills/ ← Skills de scaffolding CRUD/page
|
|
541
|
+
│ │ └── 00.shared/MANIFEST.md ← Única fuente de verdad para los skills registrados
|
|
542
|
+
│ ├── guide/ ← Onboarding, FAQ, troubleshooting (9 archivos)
|
|
543
|
+
│ ├── database/ ← Esquema de BD, guía de migración
|
|
544
|
+
│ ├── mcp-guide/ ← Guía de integración de servidor MCP
|
|
545
|
+
│ └── memory/ ← L4: conocimiento de equipo (4 archivos) — commitea estos
|
|
546
|
+
│ ├── decision-log.md ← El "porqué" detrás de las decisiones de diseño
|
|
547
|
+
│ ├── failure-patterns.md ← Errores recurrentes y sus fixes (auto-scored — `npx claudeos-core memory score`)
|
|
548
|
+
│ ├── compaction.md ← Estrategia de compaction de 4 etapas (ejecuta `npx claudeos-core memory compact`)
|
|
549
|
+
│ └── auto-rule-update.md ← Propuestas de mejora de reglas (`npx claudeos-core memory propose-rules`)
|
|
550
|
+
│
|
|
551
|
+
└── claudeos-core-tools/ ← Este toolkit (no modificar)
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
Cada archivo standard incluye ✅ ejemplos correctos, ❌ ejemplos incorrectos y una tabla resumen de reglas — todo derivado de los patrones reales de tu código, no de plantillas genéricas.
|
|
555
|
+
|
|
556
|
+
> **Nota v2.1.0:** `claudeos-core/plan/` ya no se genera. Los master plans eran un backup interno que Claude Code no consumía en runtime, y agregarlos en Pass 3 era una causa principal de overflow por acumulación de salida. Usa `git` para backup/restore en su lugar. Los proyectos que hagan upgrade desde v2.0.x pueden borrar sin problema cualquier directorio `claudeos-core/plan/` existente.
|
|
557
|
+
|
|
558
|
+
### Recomendaciones de gitignore
|
|
559
|
+
|
|
560
|
+
**Sí commitear** (conocimiento de equipo — pensado para compartir):
|
|
561
|
+
- `CLAUDE.md` — punto de entrada de Claude Code
|
|
562
|
+
- `.claude/rules/**` — reglas auto-cargadas
|
|
563
|
+
- `claudeos-core/standard/**`, `skills/**`, `guide/**`, `database/**`, `mcp-guide/**`, `plan/**` — documentación generada
|
|
564
|
+
- `claudeos-core/memory/**` — historial de decisiones, patrones de fallo, propuestas de reglas
|
|
565
|
+
|
|
566
|
+
**NO commitear** (artefactos de build regenerables):
|
|
567
|
+
|
|
568
|
+
```gitignore
|
|
569
|
+
# ClaudeOS-Core — análisis generado y caché de traducción
|
|
570
|
+
claudeos-core/generated/
|
|
571
|
+
```
|
|
572
|
+
|
|
573
|
+
El directorio `generated/` contiene el JSON de análisis (`pass1-*.json`, `pass2-merged.json`), prompts (`pass1/2/3/4-prompt.md`), marcadores de finalización de Pass (`pass3-complete.json`, `pass4-memory.json`), caché de traducción (`.i18n-cache-<lang>.json`) y el directorio transitorio de staging (`.staged-rules/`) — todo reconstruible volviendo a ejecutar `npx claudeos-core init`.
|
|
574
|
+
|
|
575
|
+
---
|
|
576
|
+
|
|
577
|
+
## Auto-escalado por Tamaño del Proyecto
|
|
578
|
+
|
|
579
|
+
El modo split de Pass 3 escala el número de etapas en función del número de dominios. La sub-división por lotes entra en acción a partir de 16 dominios para mantener cada etapa por debajo de ~50 archivos de salida, que es el rango empíricamente seguro de `claude -p` antes de que empiece el overflow por acumulación de salida.
|
|
580
|
+
|
|
581
|
+
| Tamaño del proyecto | Dominios | Etapas de Pass 3 | Total `claude -p` | Tiempo Est. |
|
|
582
|
+
|---|---|---|---|---|
|
|
583
|
+
| Pequeño | 1–4 | 4 (`3a`, `3b-core`, `3c-core`, `3d-aux`) | 7 (Pass 1 + 2 + 4 etapas de Pass 3 + Pass 4) | ~10–15 min |
|
|
584
|
+
| Medio | 5–15 | 4 | 8–9 | ~25–45 min |
|
|
585
|
+
| Grande | 16–30 | **8** (3b, 3c cada uno dividido en 2 lotes) | 11–12 | **~60–105 min** |
|
|
586
|
+
| X-Large | 31–45 | 10 | 13–14 | ~100–150 min |
|
|
587
|
+
| XX-Large | 46–60 | 12 | 15–16 | ~150–200 min |
|
|
588
|
+
| XXX-Large | 61+ | 14+ | 17+ | 200 min+ |
|
|
589
|
+
|
|
590
|
+
Fórmula de conteo de etapas (cuando hay lotes): `1 (3a) + 1 (3b-core) + N (3b-1..N) + 1 (3c-core) + N (3c-1..N) + 1 (3d-aux) = 2N + 4`, donde `N = ceil(totalDomains / 15)`.
|
|
591
|
+
|
|
592
|
+
Pass 4 (memory scaffolding) añade ~30 segundos a 5 minutos encima según si se ejecuta la generación dirigida por Claude o el fallback estático. Para proyectos multi-stack (ej: Java + React), los dominios backend y frontend se cuentan juntos. Un proyecto con 6 dominios backend + 4 frontend = 10 en total = tier Medio.
|
|
593
|
+
|
|
594
|
+
### Caso real de producción: admin frontend de 18 dominios (2026-04-20)
|
|
595
|
+
|
|
596
|
+
Un admin frontend React 19 + Vite 6 + TypeScript con 18 dominios y 6 grupos de dominios se completó de principio a fin en **102 minutos con 101 archivos generados**. Desglose por etapa:
|
|
597
|
+
|
|
598
|
+
| Etapa | Archivos | Tiempo | Archivos/min |
|
|
599
|
+
|---|---|---|---|
|
|
600
|
+
| `3a` (extracción de hechos) | 1 (`pass3a-facts.md`) | 8m 44s | — |
|
|
601
|
+
| `3b-core` (CLAUDE.md + común) | 24 | 22m 10s | 1.1 |
|
|
602
|
+
| `3b-1` (15 dominios) | 30 | 10m 6s | **3.0** |
|
|
603
|
+
| `3b-2` (3 dominios) | 6 | 4m 34s | 1.3 |
|
|
604
|
+
| `3c-core` (guides + compartidos) | 11 | 8m 31s | 1.3 |
|
|
605
|
+
| `3c-1` (15 dominios) | 8 | 5m 11s | **1.5** |
|
|
606
|
+
| `3c-2` (3 dominios) | 3 | 3m 50s | 0.8 |
|
|
607
|
+
| `3d-aux` (database + mcp) | 3 | 2m 52s | 1.0 |
|
|
608
|
+
| Pass 4 | 12 | 5m 36s | 2.1 |
|
|
609
|
+
|
|
610
|
+
El throughput es notablemente más alto en las etapas de dominio por lote (3b-1: 3.0 archivos/min vs. 3b-core: 1.1 archivos/min) porque las etapas con contexto nuevo se benefician de patrones ajustados y repetibles por dominio. Verificación todo-verde: `plan-validator`, `sync-checker`, `content-validator`, `pass-json-validator` — cero fallos por overflow, cero truncados.
|
|
611
|
+
|
|
612
|
+
---
|
|
613
|
+
|
|
614
|
+
## Herramientas de Verificación
|
|
615
|
+
|
|
616
|
+
ClaudeOS-Core incluye 5 herramientas de verificación integradas que se ejecutan automáticamente después de la generación:
|
|
617
|
+
|
|
618
|
+
```bash
|
|
619
|
+
# Ejecutar todas las comprobaciones a la vez (recomendado)
|
|
620
|
+
npx claudeos-core health
|
|
621
|
+
|
|
622
|
+
# Comandos individuales
|
|
623
|
+
npx claudeos-core validate # Comparación Plan ↔ disco
|
|
624
|
+
npx claudeos-core refresh # Sync Disco → Plan
|
|
625
|
+
npx claudeos-core restore # Restore Plan → Disco
|
|
626
|
+
|
|
627
|
+
# O usar node directamente (usuarios de git clone)
|
|
628
|
+
node claudeos-core-tools/health-checker/index.js
|
|
629
|
+
node claudeos-core-tools/manifest-generator/index.js
|
|
630
|
+
node claudeos-core-tools/plan-validator/index.js --check
|
|
631
|
+
node claudeos-core-tools/sync-checker/index.js
|
|
632
|
+
```
|
|
633
|
+
|
|
634
|
+
| Herramienta | Qué hace |
|
|
635
|
+
|---|---|
|
|
636
|
+
| **manifest-generator** | Construye el JSON de metadata (`rule-manifest.json`, `sync-map.json`, inicializa `stale-report.json`); indexa 7 directorios incluyendo `memory/` (`totalMemory` en summary). v2.1.0: `plan-manifest.json` ya no se genera dado que los master plans fueron eliminados. |
|
|
637
|
+
| **plan-validator** | Valida los bloques `<file>` del master plan contra el disco para proyectos que aún tengan `claudeos-core/plan/` (caso de upgrade legacy). v2.1.0: omite la emisión de `plan-sync-status.json` cuando `plan/` está ausente o vacío — `stale-report.json` sigue registrando un no-op aprobado. |
|
|
638
|
+
| **sync-checker** | Detecta archivos no registrados (en disco pero no en el plan) y entradas huérfanas — cubre 7 directorios (añadido `memory/` en v2.0.0). Sale limpiamente cuando `sync-map.json` no tiene mapeos (estado por defecto de v2.1.0). |
|
|
639
|
+
| **content-validator** | Comprobación de calidad en 9 secciones — archivos vacíos, ejemplos ✅/❌ ausentes, secciones requeridas, más integridad del scaffold de memory L4 (fechas de encabezados de decision-log, campos requeridos de failure-pattern, parsing fence-aware) |
|
|
640
|
+
| **pass-json-validator** | Valida la estructura del JSON de Pass 1–4 más los marcadores de finalización `pass3-complete.json` (forma de modo split, v2.1.0) y `pass4-memory.json` |
|
|
641
|
+
|
|
642
|
+
---
|
|
643
|
+
|
|
644
|
+
## Cómo Usa Claude Code tu Documentación
|
|
645
|
+
|
|
646
|
+
ClaudeOS-Core genera documentación que Claude Code realmente lee — así es cómo:
|
|
647
|
+
|
|
648
|
+
### Qué lee Claude Code automáticamente
|
|
649
|
+
|
|
650
|
+
| Archivo | Cuándo | Garantizado |
|
|
651
|
+
|---|---|---|
|
|
652
|
+
| `CLAUDE.md` | En el inicio de cada conversación | Siempre |
|
|
653
|
+
| `.claude/rules/00.core/*` | Cuando se edita cualquier archivo (`paths: ["**/*"]`) | Siempre |
|
|
654
|
+
| `.claude/rules/10.backend/*` | Cuando se edita cualquier archivo (`paths: ["**/*"]`) | Siempre |
|
|
655
|
+
| `.claude/rules/20.frontend/*` | Cuando se edita cualquier archivo frontend (limitado a rutas de component/page/style) | Condicional |
|
|
656
|
+
| `.claude/rules/30.security-db/*` | Cuando se edita cualquier archivo (`paths: ["**/*"]`) | Siempre |
|
|
657
|
+
| `.claude/rules/40.infra/*` | Solo al editar archivos de config/infra (rutas limitadas) | Condicional |
|
|
658
|
+
| `.claude/rules/50.sync/*` | Solo al editar archivos de claudeos-core (rutas limitadas) | Condicional |
|
|
659
|
+
| `.claude/rules/60.memory/*` | Cuando se edita `claudeos-core/memory/*` (limitado a rutas de memory) — indica **cómo** leer/escribir la capa de memory on-demand | Condicional (v2.0.0) |
|
|
660
|
+
|
|
661
|
+
### Qué lee Claude Code on-demand a través de referencias de reglas
|
|
662
|
+
|
|
663
|
+
Cada archivo de regla enlaza a su standard correspondiente mediante una sección `## Reference`. Claude lee solo el standard relevante para la tarea actual:
|
|
664
|
+
|
|
665
|
+
- `claudeos-core/standard/**` — patrones de codificación, ejemplos ✅/❌, convenciones de naming
|
|
666
|
+
- `claudeos-core/database/**` — esquema BD (para queries, mappers, migrations)
|
|
667
|
+
- `claudeos-core/memory/**` (v2.0.0) — capa de conocimiento de equipo L4; **no** se auto-carga (sería demasiado ruidoso en cada conversación). En su lugar, las reglas `60.memory/*` indican a Claude *cuándo* leer estos archivos: al inicio de sesión (skim del `decision-log.md` reciente + `failure-patterns.md` de alta importancia), y append-on-demand al tomar decisiones o al encontrar errores recurrentes.
|
|
668
|
+
|
|
669
|
+
El `00.standard-reference.md` sirve como directorio de todos los archivos standard para descubrir standards que no tienen una regla correspondiente.
|
|
670
|
+
|
|
671
|
+
### Qué NO lee Claude Code (ahorra contexto)
|
|
672
|
+
|
|
673
|
+
Estas carpetas están excluidas explícitamente mediante la sección `DO NOT Read` en la regla standard-reference:
|
|
674
|
+
|
|
675
|
+
| Carpeta | Por qué se excluye |
|
|
676
|
+
|---|---|
|
|
677
|
+
| `claudeos-core/plan/` | Backups de Master Plan de proyectos legacy (v2.0.x y anteriores). No se genera en v2.1.0. Si está presente, Claude Code no la carga automáticamente — read-on-demand únicamente. |
|
|
678
|
+
| `claudeos-core/generated/` | JSON de metadata de build, prompts, marcadores de Pass, caché de traducción, `.staged-rules/`. No es para codificar. |
|
|
679
|
+
| `claudeos-core/guide/` | Guías de onboarding para humanos. |
|
|
680
|
+
| `claudeos-core/mcp-guide/` | Docs del servidor MCP. No es para codificar. |
|
|
681
|
+
| `claudeos-core/memory/` (auto-load) | **Auto-load deshabilitado** por diseño — inflaría el contexto en cada conversación. En su lugar, se lee on-demand vía las reglas `60.memory/*` (ej: escaneo al inicio de sesión de `failure-patterns.md`). Commitea siempre estos archivos. |
|
|
682
|
+
|
|
683
|
+
---
|
|
684
|
+
|
|
685
|
+
## Flujo de Trabajo Diario
|
|
686
|
+
|
|
687
|
+
### Después de la instalación
|
|
688
|
+
|
|
689
|
+
```
|
|
690
|
+
# Simplemente usa Claude Code como de costumbre — referencia tus standards automáticamente:
|
|
691
|
+
"Crea un CRUD para el dominio order"
|
|
692
|
+
"Añade un API de actualización de perfil de usuario"
|
|
693
|
+
"Refactoriza este código para que coincida con los patrones del proyecto"
|
|
694
|
+
```
|
|
695
|
+
|
|
696
|
+
### Después de editar Standards manualmente
|
|
697
|
+
|
|
698
|
+
```bash
|
|
699
|
+
# Después de editar archivos de standards o reglas:
|
|
700
|
+
npx claudeos-core refresh
|
|
701
|
+
|
|
702
|
+
# Verifica que todo es consistente
|
|
703
|
+
npx claudeos-core health
|
|
704
|
+
```
|
|
705
|
+
|
|
706
|
+
### Cuando los docs se corrompen
|
|
707
|
+
|
|
708
|
+
```bash
|
|
709
|
+
# Recomendación v2.1.0: usa git para restaurar (dado que los master plans ya no se
|
|
710
|
+
# generan). Commitea tus docs generados regularmente para poder revertir archivos
|
|
711
|
+
# concretos sin regenerar:
|
|
712
|
+
git checkout HEAD -- .claude/rules/ claudeos-core/
|
|
713
|
+
|
|
714
|
+
# Legacy (proyectos v2.0.x con claudeos-core/plan/ aún presente):
|
|
715
|
+
npx claudeos-core restore
|
|
716
|
+
```
|
|
717
|
+
|
|
718
|
+
### Mantenimiento de la capa Memory (v2.0.0)
|
|
719
|
+
|
|
720
|
+
La capa Memory L4 (`claudeos-core/memory/`) acumula conocimiento de equipo entre sesiones. Tres subcomandos de CLI la mantienen en buen estado:
|
|
721
|
+
|
|
722
|
+
```bash
|
|
723
|
+
# Compact: aplica la política de compaction de 4 etapas (ejecutar periódicamente — ej: mensualmente)
|
|
724
|
+
npx claudeos-core memory compact
|
|
725
|
+
# Etapa 1: resume entradas antiguas (>30 días, cuerpo → una línea)
|
|
726
|
+
# Etapa 2: combina encabezados duplicados (frecuencia sumada, se mantiene el fix más reciente)
|
|
727
|
+
# Etapa 3: descarta baja-importancia + antiguas (importancia <3 Y lastSeen >60 días)
|
|
728
|
+
# Etapa 4: aplica tope de 400 líneas por archivo (se descarta primero lo más antiguo y de menor importancia)
|
|
729
|
+
|
|
730
|
+
# Score: re-rankea las entradas de failure-patterns.md por importancia
|
|
731
|
+
npx claudeos-core memory score
|
|
732
|
+
# importance = round(frequency × 1.5 + recency × 5), cap 10
|
|
733
|
+
# Ejecutar después de añadir varios nuevos patrones de fallo
|
|
734
|
+
|
|
735
|
+
# Propose-rules: propone adiciones de reglas a partir de fallos recurrentes
|
|
736
|
+
npx claudeos-core memory propose-rules
|
|
737
|
+
# Lee entradas de failure-patterns.md con frequency ≥ 3
|
|
738
|
+
# Calcula confianza (sigmoid sobre evidencia ponderada × multiplicador de anchor)
|
|
739
|
+
# Escribe propuestas en memory/auto-rule-update.md (NO se aplican auto)
|
|
740
|
+
# Confidence ≥ 0.70 merece revisión seria; acepta → edita regla + registra decisión
|
|
741
|
+
|
|
742
|
+
# v2.1.0: `memory --help` ahora enruta a la ayuda del subcomando (antes mostraba top-level)
|
|
743
|
+
npx claudeos-core memory --help
|
|
744
|
+
```
|
|
745
|
+
|
|
746
|
+
> **Fixes v2.1.0:** `memory score` ya no deja líneas `importance` duplicadas tras la primera ejecución (antes la línea auto-scored se añadía arriba mientras la original plana se dejaba debajo). El marcador de resumen de la Etapa 1 de `memory compact` ahora es un elemento de lista markdown propio (`- _Summarized on ..._`) para que se renderice limpiamente y se vuelva a parsear correctamente en las siguientes compactaciones.
|
|
747
|
+
|
|
748
|
+
Cuándo escribir en memory (Claude lo hace on-demand, pero también puedes editar manualmente):
|
|
749
|
+
- **`decision-log.md`** — añade una nueva entrada cada vez que elijas entre patrones en competencia, selecciones una biblioteca, definas una convención de equipo o decidas NO hacer algo. Append-only; nunca edites entradas históricas.
|
|
750
|
+
- **`failure-patterns.md`** — añade en la **segunda ocurrencia** de un error recurrente o de una root cause no obvia. Los errores de primera vez no necesitan una entrada.
|
|
751
|
+
- `compaction.md` y `auto-rule-update.md` — generados/gestionados por los subcomandos de CLI indicados arriba; no los edites a mano.
|
|
752
|
+
|
|
753
|
+
### Integración CI/CD
|
|
754
|
+
|
|
755
|
+
```yaml
|
|
756
|
+
# Ejemplo de GitHub Actions
|
|
757
|
+
- run: npx claudeos-core validate
|
|
758
|
+
# Exit code 1 bloquea el PR
|
|
759
|
+
|
|
760
|
+
# Opcional: housekeeping mensual de memory (workflow cron separado)
|
|
761
|
+
- run: npx claudeos-core memory compact
|
|
762
|
+
- run: npx claudeos-core memory score
|
|
763
|
+
```
|
|
764
|
+
|
|
765
|
+
---
|
|
766
|
+
|
|
767
|
+
## ¿En Qué Se Diferencia?
|
|
768
|
+
|
|
769
|
+
### vs otras herramientas de Claude Code
|
|
770
|
+
|
|
771
|
+
| | ClaudeOS-Core | Everything Claude Code (50K+ ⭐) | Harness | specs-generator | Claude `/init` |
|
|
772
|
+
|---|---|---|---|---|---|
|
|
773
|
+
| **Enfoque** | Código analiza primero, luego el LLM genera | Presets de configuración preconstruidos | El LLM diseña equipos de agentes | El LLM genera specs | El LLM escribe CLAUDE.md |
|
|
774
|
+
| **Lee tu código fuente** | ✅ Análisis estático determinístico | ❌ | ❌ | ❌ (lee el LLM) | ❌ (lee el LLM) |
|
|
775
|
+
| **Detección de stack** | El código confirma (ORM, BD, build tool, pkg manager) | N/A (stack-agnostic) | El LLM adivina | El LLM adivina | El LLM adivina |
|
|
776
|
+
| **Detección de dominios** | El código confirma (Java 5 patrones, Kotlin CQRS, Next.js FSD) | N/A | El LLM adivina | N/A | N/A |
|
|
777
|
+
| **Mismo proyecto → Mismo resultado** | ✅ Análisis determinístico | ✅ (archivos estáticos) | ❌ (el LLM varía) | ❌ (el LLM varía) | ❌ (el LLM varía) |
|
|
778
|
+
| **Gestión de proyectos grandes** | División en grupos de dominios (4 dominios / 40 archivos por grupo) | N/A | Sin división | Sin división | Límite de ventana de contexto |
|
|
779
|
+
| **Salida** | CLAUDE.md + Rules + Standards + Skills + Guides + Plans (40-50+ archivos) | Agents + Skills + Commands + Hooks | Agents + Skills | 6 docs de spec | CLAUDE.md (1 archivo) |
|
|
780
|
+
| **Ubicación de salida** | `.claude/rules/` (auto-cargado por Claude Code) | `.claude/` variados | `.claude/agents/` + `.claude/skills/` | `.claude/steering/` + `specs/` | `CLAUDE.md` |
|
|
781
|
+
| **Verificación post-generación** | ✅ 5 validadores automáticos | ❌ | ❌ | ❌ | ❌ |
|
|
782
|
+
| **Salida multi-idioma** | ✅ 10 idiomas | ❌ | ❌ | ❌ | ❌ |
|
|
783
|
+
| **Multi-stack** | ✅ Backend + Frontend simultáneo | ❌ Stack-agnostic | ❌ | ❌ | Parcial |
|
|
784
|
+
| **Capa de memory persistente** | ✅ L4 — decision log + failure patterns + propuestas de reglas auto-scored (v2.0.0) | ❌ | ❌ | ❌ | ❌ |
|
|
785
|
+
| **Orquestación de agentes** | ❌ | ✅ 28 agentes | ✅ 6 patrones | ❌ | ❌ |
|
|
786
|
+
|
|
787
|
+
### La diferencia clave en una frase
|
|
788
|
+
|
|
789
|
+
**Otras herramientas dan a Claude "instrucciones generalmente buenas". ClaudeOS-Core da a Claude "instrucciones extraídas de tu código real".**
|
|
790
|
+
|
|
791
|
+
Por eso Claude Code deja de generar código JPA en tu proyecto MyBatis,
|
|
792
|
+
deja de usar `success()` cuando tu codebase usa `ok()`,
|
|
793
|
+
y deja de crear directorios `user/controller/` cuando tu proyecto usa `controller/user/`.
|
|
794
|
+
|
|
795
|
+
### Complementarias, no competidoras
|
|
796
|
+
|
|
797
|
+
ClaudeOS-Core se centra en **reglas y standards específicos del proyecto**.
|
|
798
|
+
Otras herramientas se centran en **orquestación y workflows de agentes**.
|
|
799
|
+
|
|
800
|
+
Puedes usar ClaudeOS-Core para generar las reglas de tu proyecto, y encima usar ECC o Harness para equipos de agentes y automatización de workflows. Resuelven problemas diferentes.
|
|
801
|
+
|
|
802
|
+
---
|
|
803
|
+
|
|
804
|
+
## FAQ
|
|
805
|
+
|
|
806
|
+
**P: ¿Modifica mi código fuente?**
|
|
807
|
+
No. Solo crea `CLAUDE.md`, `.claude/rules/` y `claudeos-core/`. Tu código existente nunca se modifica.
|
|
808
|
+
|
|
809
|
+
**P: ¿Cuánto cuesta?**
|
|
810
|
+
Llama a `claude -p` varias veces a lo largo de 4 passes. En el modo split de v2.1.0, Pass 3 por sí solo se expande en 4–14+ etapas según el tamaño del proyecto (ver [Auto-escalado](#auto-escalado-por-tamaño-del-proyecto)). Un proyecto pequeño típico (1–15 dominios) usa 8–9 llamadas `claude -p` en total; un proyecto de 18 dominios usa 11; un proyecto de 60 dominios usa 15–17. Cada etapa se ejecuta con una ventana de contexto nueva — el coste en tokens por llamada es en realidad más bajo que el del Pass 3 de llamada única, porque ninguna etapa tiene que sostener el árbol de archivos completo en un único contexto. Cuando `--lang` no es inglés, el path de fallback estático puede invocar algunas llamadas adicionales a `claude -p` para traducir; los resultados se cachean en `claudeos-core/generated/.i18n-cache-<lang>.json` para que las ejecuciones posteriores los reutilicen. Esto entra dentro del uso normal de Claude Code.
|
|
811
|
+
|
|
812
|
+
**P: ¿Qué es el modo split de Pass 3 y por qué se añadió en v2.1.0?**
|
|
813
|
+
Antes de v2.1.0, Pass 3 hacía una única llamada `claude -p` que debía emitir todo el árbol de archivos generados (`CLAUDE.md`, standards, reglas, skills, guides — típicamente 30–60 archivos) en una sola respuesta. Esto funcionaba en proyectos pequeños pero chocaba de forma confiable con fallos `Prompt is too long` por acumulación de salida a ~5 dominios. El fallo no era predecible desde el tamaño de entrada — dependía de lo verboso que resultara cada archivo generado, y podía darse en el mismo proyecto de forma intermitente. El modo split esquiva el problema de forma estructural: Pass 3 se descompone en etapas secuenciales (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`), cada una una llamada `claude -p` separada con una ventana de contexto nueva. La consistencia entre etapas se preserva mediante `pass3a-facts.md`, un fact sheet destilado de 5–10 KB que cada etapa posterior referencia en lugar de releer `pass2-merged.json`. El marcador `pass3-complete.json` lleva un array `groupsCompleted` para que un crash durante `3c-2` reanude desde `3c-2` (no desde `3a`), evitando doblar el coste en tokens. Verificado empíricamente hasta 18 dominios × 101 archivos × 102 minutos sin ningún overflow — ver [Auto-escalado](#auto-escalado-por-tamaño-del-proyecto) para el desglose real de producción.
|
|
814
|
+
|
|
815
|
+
**P: ¿Debería commitear los archivos generados a Git?**
|
|
816
|
+
Sí, recomendado. Tu equipo puede compartir los mismos standards de Claude Code. Considera añadir `claudeos-core/generated/` a `.gitignore` (el JSON de análisis es regenerable).
|
|
817
|
+
|
|
818
|
+
**P: ¿Qué pasa con proyectos de stack mixto (ej: Java backend + React frontend)?**
|
|
819
|
+
Totalmente soportado. ClaudeOS-Core auto-detecta ambos stacks, etiqueta los dominios como `backend` o `frontend`, y usa prompts de análisis específicos del stack para cada uno. Pass 2 combina todo, y Pass 3 genera tanto los standards de backend como los de frontend a lo largo de sus etapas de split — los dominios backend van a algunos lotes 3b/3c, los frontend a otros, todos referenciando el mismo `pass3a-facts.md` para mantener la consistencia.
|
|
820
|
+
|
|
821
|
+
**P: ¿Funciona con monorepos Turborepo / pnpm workspaces / Lerna?**
|
|
822
|
+
Sí. ClaudeOS-Core detecta `turbo.json`, `pnpm-workspace.yaml`, `lerna.json`, o `package.json#workspaces` y escanea automáticamente los `package.json` de los sub-paquetes para dependencias de framework/ORM/BD. El escaneo de dominios cubre los patrones `apps/*/src/` y `packages/*/src/`. Ejecuta desde la raíz del monorepo.
|
|
823
|
+
|
|
824
|
+
**P: ¿Qué pasa al volver a ejecutar?**
|
|
825
|
+
Si existen resultados previos de Pass 1/2, un prompt interactivo te permite elegir: **Continue** (reanudar desde donde se detuvo) o **Fresh** (borrar todo y empezar de nuevo). Usa `--force` para saltarte el prompt y empezar siempre desde cero. En el modo split de v2.1.0, el resume de Pass 3 funciona a granularidad de etapa — si la ejecución crasheó durante `3c-2`, el siguiente `init` reanuda desde `3c-2` en lugar de reiniciar desde `3a` (lo que doblaría el coste en tokens). El marcador `pass3-complete.json` registra `mode: "split"` más un array `groupsCompleted` para dirigir esta lógica.
|
|
826
|
+
|
|
827
|
+
**P: ¿NestJS tiene su propia plantilla o usa la de Express?**
|
|
828
|
+
NestJS usa una plantilla dedicada `node-nestjs` con categorías de análisis específicas de NestJS: decorators `@Module`, `@Injectable`, `@Controller`, Guards, Pipes, Interceptors, contenedor DI, patrones CQRS y `Test.createTestingModule`. Los proyectos Express usan la plantilla separada `node-express`.
|
|
829
|
+
|
|
830
|
+
**P: ¿Qué pasa con proyectos Vue / Nuxt?**
|
|
831
|
+
Vue/Nuxt usa una plantilla dedicada `vue-nuxt` que cubre Composition API, `<script setup>`, defineProps/defineEmits, Pinia stores, `useFetch`/`useAsyncData`, rutas de servidor Nitro y `@nuxt/test-utils`. Los proyectos Next.js/React usan la plantilla `node-nextjs`.
|
|
832
|
+
|
|
833
|
+
**P: ¿Soporta Kotlin?**
|
|
834
|
+
Sí. ClaudeOS-Core auto-detecta Kotlin a partir de `build.gradle.kts` o del plugin kotlin en `build.gradle`. Usa una plantilla dedicada `kotlin-spring` con análisis específico de Kotlin (data classes, sealed classes, coroutines, extension functions, MockK, etc.).
|
|
835
|
+
|
|
836
|
+
**P: ¿Qué pasa con arquitectura CQRS / BFF?**
|
|
837
|
+
Totalmente soportado para proyectos Kotlin multi-módulo. ClaudeOS-Core lee `settings.gradle.kts`, detecta los tipos de módulo (command, query, bff, integration) a partir de los nombres de módulo, y agrupa el mismo dominio entre los módulos Command/Query. Los standards generados incluyen reglas separadas para command controllers vs query controllers, patrones BFF/Feign y convenciones de comunicación entre módulos.
|
|
838
|
+
|
|
839
|
+
**P: ¿Qué pasa con monorepos Gradle multi-módulo?**
|
|
840
|
+
ClaudeOS-Core escanea todos los submódulos (`**/src/main/kotlin/**/*.kt`) independientemente de la profundidad de anidamiento. Los tipos de módulo se infieren de las convenciones de naming (ej: `reservation-command-server` → dominio: `reservation`, tipo: `command`). Las bibliotecas compartidas (`shared-lib`, `integration-lib`) también se detectan.
|
|
841
|
+
|
|
842
|
+
**P: ¿Qué es la capa Memory L4 (v2.0.0)? ¿Debo commitear `claudeos-core/memory/`?**
|
|
843
|
+
Sí — **commitea siempre** `claudeos-core/memory/`. Es conocimiento persistente del equipo: `decision-log.md` registra el *porqué* detrás de las decisiones arquitectónicas (append-only), `failure-patterns.md` registra errores recurrentes con importancia puntuada para que las sesiones futuras los eviten, `compaction.md` define la política de compaction de 4 etapas y `auto-rule-update.md` recopila propuestas de mejora de reglas generadas por la máquina. A diferencia de las reglas (auto-cargadas por path), los archivos de memory son **on-demand** — Claude los lee solo cuando las reglas `60.memory/*` se lo indican (ej: escaneo al inicio de sesión de fallos de alta importancia). Esto mantiene bajo el coste de contexto conservando el conocimiento a largo plazo.
|
|
844
|
+
|
|
845
|
+
**P: ¿Qué pasa si Pass 4 falla?**
|
|
846
|
+
El pipeline automatizado (`npx claudeos-core init`) tiene un fallback estático: si `claude -p` falla o `pass4-prompt.md` está ausente, scaffoldea la capa de memory directamente vía `lib/memory-scaffold.js`. Cuando `--lang` no es inglés, el fallback estático **debe** traducir vía la CLI `claude` — si también falla, la ejecución se aborta con `InitError` (sin fallback silencioso a inglés). Vuelve a ejecutar cuando `claude` esté autenticado, o usa `--lang en` para saltarte la traducción. Los resultados de traducción se cachean en `claudeos-core/generated/.i18n-cache-<lang>.json` para que las ejecuciones posteriores los reutilicen.
|
|
847
|
+
|
|
848
|
+
**P: ¿Qué hacen `memory compact` / `memory score` / `memory propose-rules`?**
|
|
849
|
+
Ver la sección [Mantenimiento de la capa Memory](#mantenimiento-de-la-capa-memory-v200) arriba. Versión corta: `compact` ejecuta la política de 4 etapas (resume antiguas, combina duplicadas, descarta baja-importancia antiguas, aplica tope de 400 líneas); `score` re-rankea `failure-patterns.md` por importancia (frecuencia × recencia); `propose-rules` propone adiciones de reglas a partir de fallos recurrentes en `auto-rule-update.md` (no se aplican auto — revisa y acepta/rechaza manualmente).
|
|
850
|
+
|
|
851
|
+
**P: ¿Por qué `--force` (o el modo resume "fresh") borra `.claude/rules/`?**
|
|
852
|
+
v2.0.0 añadió tres guards de silent-failure en Pass 3 (Guard 3 cubre dos variantes de salida incompleta: H2 para `guide/` y H1 para `standard/skills`). Guard 1 ("movimiento parcial de staged-rules") y Guard 3 ("salida incompleta — archivos guide ausentes/vacíos o sentinel de standard ausente / skills vacío") no dependen de reglas existentes, pero Guard 2 ("cero reglas detectadas") sí — se dispara cuando Claude ignora la directiva `staging-override.md` e intenta escribir directamente en `.claude/` (donde la política de rutas sensibles de Claude Code lo bloquea). Las reglas obsoletas de una ejecución anterior harían que Guard 2 produjera falsos negativos — por eso `--force`/`fresh` borra `.claude/rules/` para asegurar una detección limpia. **Las ediciones manuales de archivos de reglas se perderán** con `--force`/`fresh`; haz un backup antes si es necesario. (Nota v2.1.0: Guard 3 H1 ya no comprueba `plan/` dado que los master plans ya no se generan.)
|
|
853
|
+
|
|
854
|
+
**P: ¿Qué es `claudeos-core/generated/.staged-rules/` y por qué existe?**
|
|
855
|
+
La política de rutas sensibles de Claude Code rechaza las escrituras directas a `.claude/` desde el subproceso `claude -p` (incluso con `--dangerously-skip-permissions`). v2.0.0 evita esto haciendo que los prompts de Pass 3/4 redirijan todas las escrituras de `.claude/rules/` al directorio de staging; el orquestador Node.js (que no está sujeto a esa política) luego mueve el árbol staged a `.claude/rules/` después de cada pass. Esto es transparente para el usuario — el directorio se auto-crea, se auto-limpia y se auto-mueve. Si una ejecución previa crashea a mitad del movimiento, la siguiente ejecución limpia el dir de staging antes de reintentar. En el modo split de v2.1.0, el runner de etapas mueve las reglas staged a `.claude/rules/` tras cada etapa (no solo al final), así que un crash a mitad de Pass 3 deja las reglas de las etapas previamente completadas en su sitio.
|
|
856
|
+
|
|
857
|
+
**P: ¿Puedo ejecutar Pass 3 manualmente en lugar de `npx claudeos-core init`?**
|
|
858
|
+
Sí para proyectos pequeños (≤5 dominios) — las instrucciones manuales de llamada única del [Paso 6](#paso-6-pass-3--generar-toda-la-documentación-dividido-en-varias-etapas) siguen funcionando. Para proyectos más grandes deberías usar `npx claudeos-core init` porque el runner de split es lo que orquesta la ejecución etapa-a-etapa con contextos nuevos, gestiona la sub-división por lotes a ≥16 dominios, escribe la forma correcta del marcador `pass3-complete.json` (`mode: "split"` + `groupsCompleted`) y mueve las reglas staged entre etapas. Reproducir esa orquestación a mano es posible pero tedioso. Si tienes una razón para ejecutar etapas manualmente (ej: debuggear una etapa concreta), puedes templatizar `pass3-prompt.md` con la directiva `STAGE:` apropiada y pasarlo a `claude -p` directamente — pero recuerda mover `.staged-rules/` tras cada etapa y actualizar el marcador tú mismo.
|
|
859
|
+
|
|
860
|
+
**P: Mi proyecto es un upgrade desde v2.0.x y tiene un directorio `claudeos-core/plan/` existente. ¿Qué hago?**
|
|
861
|
+
Nada requerido — las herramientas de v2.1.0 ignoran `plan/` cuando está ausente o vacío, y `plan-validator` sigue gestionando los proyectos legacy con directorios `plan/` poblados por retrocompatibilidad. Puedes borrar sin problemas `claudeos-core/plan/` si no necesitas los backups de master plan (el historial de git es un mejor backup de todos modos). Si conservas `plan/`, ejecutar `npx claudeos-core init` no lo actualizará — el contenido nuevo ya no se agrega en master plans en v2.1.0. Las herramientas de verificación gestionan ambos casos limpiamente.
|
|
862
|
+
|
|
863
|
+
---
|
|
864
|
+
|
|
865
|
+
## Estructura de Plantillas
|
|
866
|
+
|
|
867
|
+
```
|
|
868
|
+
pass-prompts/templates/
|
|
869
|
+
├── common/ # Header/footer compartido + pass4 + staging-override
|
|
870
|
+
├── java-spring/ # Java / Spring Boot
|
|
871
|
+
├── kotlin-spring/ # Kotlin / Spring Boot (CQRS, BFF, multi-módulo)
|
|
872
|
+
├── node-express/ # Node.js / Express
|
|
873
|
+
├── node-nestjs/ # Node.js / NestJS (Module, DI, Guard, Pipe, Interceptor)
|
|
874
|
+
├── node-fastify/ # Node.js / Fastify
|
|
875
|
+
├── node-nextjs/ # Next.js / React (App Router, RSC)
|
|
876
|
+
├── node-vite/ # Vite SPA (React, client-side routing, VITE_ env, Vitest)
|
|
877
|
+
├── vue-nuxt/ # Vue / Nuxt (Composition API, Pinia, Nitro)
|
|
878
|
+
├── angular/ # Angular
|
|
879
|
+
├── python-django/ # Python / Django (DRF)
|
|
880
|
+
├── python-fastapi/ # Python / FastAPI
|
|
881
|
+
└── python-flask/ # Python / Flask (Blueprint, app factory, Jinja2)
|
|
882
|
+
```
|
|
883
|
+
|
|
884
|
+
`plan-installer` auto-detecta tu stack(s), y luego ensambla prompts específicos del tipo. NestJS, Vue/Nuxt, Vite SPA y Flask usan cada uno plantillas dedicadas con categorías de análisis específicas del framework (ej: `@Module`/`@Injectable`/Guards para NestJS; `<script setup>`/Pinia/useFetch para Vue; client-side routing/`VITE_` env para Vite; Blueprint/`app.factory`/Flask-SQLAlchemy para Flask). Para proyectos multi-stack, se generan `pass1-backend-prompt.md` y `pass1-frontend-prompt.md` por separado, mientras que `pass3-prompt.md` combina los targets de generación de ambos stacks. En v2.1.0, la plantilla de Pass 3 se anteanteponte con `common/pass3-phase1.md` (el bloque "Read Once, Extract Facts" con Rules A–E) antes de ser troceada por etapa en modo split. Pass 4 usa la plantilla compartida `common/pass4.md` (memory scaffolding) independientemente del stack.
|
|
885
|
+
|
|
886
|
+
---
|
|
887
|
+
|
|
888
|
+
## Soporte de Monorepo
|
|
889
|
+
|
|
890
|
+
ClaudeOS-Core auto-detecta setups de monorepo JS/TS y escanea sub-paquetes buscando dependencias.
|
|
891
|
+
|
|
892
|
+
**Marcadores de monorepo soportados** (auto-detectados):
|
|
893
|
+
- `turbo.json` (Turborepo)
|
|
894
|
+
- `pnpm-workspace.yaml` (pnpm workspaces)
|
|
895
|
+
- `lerna.json` (Lerna)
|
|
896
|
+
- `package.json#workspaces` (npm/yarn workspaces)
|
|
897
|
+
|
|
898
|
+
**Ejecuta desde la raíz del monorepo** — ClaudeOS-Core lee `apps/*/package.json` y `packages/*/package.json` para descubrir dependencias de framework/ORM/BD entre sub-paquetes:
|
|
899
|
+
|
|
900
|
+
```bash
|
|
901
|
+
cd my-monorepo
|
|
902
|
+
npx claudeos-core init
|
|
903
|
+
```
|
|
904
|
+
|
|
905
|
+
**Qué se detecta:**
|
|
906
|
+
- Dependencias de `apps/web/package.json` (ej: `next`, `react`) → stack frontend
|
|
907
|
+
- Dependencias de `apps/api/package.json` (ej: `express`, `prisma`) → stack backend
|
|
908
|
+
- Dependencias de `packages/db/package.json` (ej: `drizzle-orm`) → ORM/BD
|
|
909
|
+
- Paths de workspace personalizados desde `pnpm-workspace.yaml` (ej: `services/*`)
|
|
910
|
+
|
|
911
|
+
**El escaneo de dominios también cubre layouts de monorepo:**
|
|
912
|
+
- `apps/api/src/modules/*/` y `apps/api/src/*/` para dominios backend
|
|
913
|
+
- `apps/web/app/*/`, `apps/web/src/app/*/`, `apps/web/pages/*/` para dominios frontend
|
|
914
|
+
- `packages/*/src/*/` para dominios de paquetes compartidos
|
|
915
|
+
|
|
916
|
+
```
|
|
917
|
+
my-monorepo/ ← Ejecuta aquí: npx claudeos-core init
|
|
918
|
+
├── turbo.json ← Auto-detectado como Turborepo
|
|
919
|
+
├── apps/
|
|
920
|
+
│ ├── web/ ← Next.js detectado desde apps/web/package.json
|
|
921
|
+
│ │ ├── app/dashboard/ ← Dominio frontend detectado
|
|
922
|
+
│ │ └── package.json ← { "dependencies": { "next": "^14" } }
|
|
923
|
+
│ └── api/ ← Express detectado desde apps/api/package.json
|
|
924
|
+
│ ├── src/modules/users/ ← Dominio backend detectado
|
|
925
|
+
│ └── package.json ← { "dependencies": { "express": "^4" } }
|
|
926
|
+
├── packages/
|
|
927
|
+
│ ├── db/ ← Drizzle detectado desde packages/db/package.json
|
|
928
|
+
│ └── ui/
|
|
929
|
+
└── package.json ← { "workspaces": ["apps/*", "packages/*"] }
|
|
930
|
+
```
|
|
931
|
+
|
|
932
|
+
> **Nota:** Para monorepos Kotlin/Java, la detección multi-módulo usa `settings.gradle.kts` (ver [Detección de Dominios Kotlin Multi-Módulo](#detección-de-dominios-kotlin-multi-módulo) arriba) y no requiere marcadores de monorepo JS.
|
|
933
|
+
|
|
934
|
+
## Troubleshooting
|
|
935
|
+
|
|
936
|
+
**"claude: command not found"** — La CLI de Claude Code no está instalada o no está en el PATH. Ver [docs de Claude Code](https://code.claude.com/docs/en/overview).
|
|
937
|
+
|
|
938
|
+
**"npm install failed"** — La versión de Node.js puede ser demasiado baja. Requiere v18+.
|
|
939
|
+
|
|
940
|
+
**"0 domains detected"** — La estructura de tu proyecto puede no ser estándar. Ver los patrones de detección anteriores para tu stack.
|
|
941
|
+
|
|
942
|
+
**"0 domains detected" en proyecto Kotlin** — Asegúrate de que tu proyecto tiene `build.gradle.kts` (o `build.gradle` con plugin kotlin) en la raíz, y los archivos fuente están bajo `**/src/main/kotlin/`. Para proyectos multi-módulo, asegúrate de que `settings.gradle.kts` contiene sentencias `include()`. Los proyectos Kotlin de un solo módulo (sin `settings.gradle`) también están soportados — los dominios se extraen de la estructura de paquete/clase bajo `src/main/kotlin/`.
|
|
943
|
+
|
|
944
|
+
**"Language detected as java instead of kotlin"** — ClaudeOS-Core comprueba primero el `build.gradle(.kts)` raíz, luego los archivos de build de los submódulos. Si el archivo de build raíz usa el plugin `java` sin `kotlin`, pero los submódulos usan Kotlin, la herramienta comprueba hasta 5 archivos de build de submódulos como fallback. Si aun así no se detecta, asegúrate de que al menos un `build.gradle.kts` contiene `kotlin("jvm")` u `org.jetbrains.kotlin`.
|
|
945
|
+
|
|
946
|
+
**"CQRS not detected"** — La detección de arquitectura depende de que los nombres de módulos contengan las palabras clave `command` y `query`. Si tus módulos usan otros naming (ej: `write-server`, `read-server`), la arquitectura CQRS no se auto-detectará. Puedes ajustar manualmente los prompts generados después de que plan-installer se ejecute.
|
|
947
|
+
|
|
948
|
+
**"Pass 3 produced 0 rule files under .claude/rules/" (v2.0.0)** — Se disparó el Guard 2: Claude ignoró la directiva `staging-override.md` e intentó escribir directamente en `.claude/`, donde la política de rutas sensibles de Claude Code bloquea las escrituras. Vuelve a ejecutar con `npx claudeos-core init --force`. Si el error persiste, inspecciona `claudeos-core/generated/pass3-prompt.md` para verificar que el bloque `staging-override.md` está al principio.
|
|
949
|
+
|
|
950
|
+
**"Pass 3 finished but N rule file(s) could not be moved from staging" (v2.0.0)** — Se disparó el Guard 1: el movimiento de staging se topó con un file lock transitorio (normalmente antivirus de Windows o file-watcher). El marcador NO se escribe, así que la siguiente ejecución de `init` reintenta Pass 3 automáticamente. Simplemente vuelve a ejecutar `npx claudeos-core init`.
|
|
951
|
+
|
|
952
|
+
**"Pass 3 produced CLAUDE.md and rules but N/9 guide files are missing or empty" (v2.0.0)** — Se disparó el Guard 3 (H2): Claude truncó la respuesta a mitad de camino tras escribir CLAUDE.md + reglas pero antes de terminar (o empezar) la sección `claudeos-core/guide/` (se esperan 9 archivos). También se dispara ante un archivo con solo BOM o solo whitespace (se escribió el encabezado pero el cuerpo quedó truncado). Sin este guard, el marcador de finalización se escribiría igual, dejando `guide/` permanentemente vacío en ejecuciones posteriores. Aquí el marcador NO se escribe, así que la siguiente ejecución de `init` reintenta Pass 3 a partir de los mismos resultados de Pass 2. Si se repite, vuelve a ejecutar con `npx claudeos-core init --force` para regenerar desde cero.
|
|
953
|
+
|
|
954
|
+
**"Pass 3 finished but the following required output(s) are missing or empty" (v2.0.0, actualizado en v2.1.0)** — Se disparó el Guard 3 (H1): Claude truncó DESPUÉS de `claudeos-core/guide/` pero antes (o durante) `claudeos-core/standard/` o `claudeos-core/skills/`. Requisitos: (a) `standard/00.core/01.project-overview.md` existe y no está vacío (sentinel escrito por el prompt Pass 3 de cada stack), (b) `skills/` tiene ≥1 `.md` no vacío. `database/` y `mcp-guide/` se excluyen intencionadamente (algunos stacks legítimamente producen cero archivos). `plan/` ya no se comprueba a partir de v2.1.0 (los master plans fueron eliminados). Mismo camino de recuperación que Guard 3 (H2): vuelve a ejecutar `init`, o `--force` si persiste.
|
|
955
|
+
|
|
956
|
+
**"Pass 3 split stage crashed partway through (v2.1.0)"** — Cuando una de las etapas de split (ej: `3b-1`, `3c-2`) falla a mitad de ejecución, el marcador a nivel de etapa NO se escribe, pero las etapas completadas SÍ se registran en `pass3-complete.json.groupsCompleted`. La siguiente ejecución de `init` lee este array y reanuda desde la primera etapa no completada, saltándose todo el trabajo previo ya completado. No tienes que hacer nada manualmente — simplemente vuelve a ejecutar `npx claudeos-core init`. Si el resume sigue fallando en la misma etapa, inspecciona `claudeos-core/generated/pass3-prompt.md` en busca de contenido malformado, y luego prueba `--force` para un reinicio completo. La forma de `pass3-complete.json` (`mode: "split"`, `groupsCompleted: [...]`) es estable; un marcador ausente o malformado provoca que Pass 3 completo se vuelva a ejecutar desde `3a`.
|
|
957
|
+
|
|
958
|
+
**"Pass 3 stale marker (shape mismatch) — treating as incomplete" (v2.1.0)** — Se está interpretando un `pass3-complete.json` de una ejecución de llamada única pre-v2.1.0 bajo las nuevas reglas de modo split. La comprobación de forma busca `mode: "split"` y un array `groupsCompleted`; si falta alguno, el marcador se trata como parcial y Pass 3 se vuelve a ejecutar en modo split. Si hiciste upgrade desde v2.0.x, esto es esperado una sola vez — la siguiente ejecución escribirá la forma correcta de marcador. No se requiere acción.
|
|
959
|
+
|
|
960
|
+
**"pass2-merged.json exists but is malformed or incomplete (<5 top-level keys), re-running" (v2.0.0)** — Log informativo, no un error. En resume, `init` ahora parsea y valida `pass2-merged.json` (se requieren ≥5 claves de nivel superior, coincidiendo con el umbral `INSUFFICIENT_KEYS` de `pass-json-validator`). Un `{}` esqueleto o un JSON mal formado de una ejecución previa crasheada se borra automáticamente y Pass 2 se vuelve a ejecutar. No se necesita acción manual — el pipeline se auto-repara. Si sigue recurriendo, inspecciona `claudeos-core/generated/pass2-prompt.md` y reintenta con `--force`.
|
|
961
|
+
|
|
962
|
+
**"Static fallback failed while translating to lang='ko'" (v2.0.0)** — Cuando `--lang` no es inglés, Pass 4 / fallback estático / gap-fill requieren todos la CLI `claude` para traducir. Si la traducción falla (CLI no autenticada, timeout de red, o la validación estricta rechazó la salida: longitud <40%, code fences rotos, frontmatter perdido, etc.), la ejecución se aborta en vez de escribir silenciosamente en inglés. Solución: asegúrate de que `claude` está autenticado, o vuelve a ejecutar con `--lang en` para saltarte la traducción.
|
|
963
|
+
|
|
964
|
+
**"pass4-memory.json exists but memory/ is empty" (v2.0.0)** — Una ejecución previa escribió el marcador pero el usuario (o un script de limpieza) borró `claudeos-core/memory/`. La CLI auto-detecta este marcador obsoleto y vuelve a ejecutar Pass 4 en el siguiente `init`. No se necesita acción manual.
|
|
965
|
+
|
|
966
|
+
**"pass4-memory.json exists but is malformed (missing passNum/memoryFiles) — re-running Pass 4" (v2.0.0)** — Log informativo, no un error. El contenido del marcador de Pass 4 ahora se valida (`passNum === 4` + array `memoryFiles` no vacío), no solo su existencia. Un fallo parcial de Claude que emitiera algo como `{"error":"timeout"}` como cuerpo del marcador previamente se aceptaba como éxito para siempre; ahora el marcador se borra y Pass 4 se vuelve a ejecutar automáticamente.
|
|
967
|
+
|
|
968
|
+
**"Could not delete stale pass3-complete.json / pass4-memory.json" InitError (v2.0.0)** — `init` detectó un marcador obsoleto (Pass 3: CLAUDE.md fue borrado externamente; Pass 4: memory/ vacío o cuerpo del marcador mal formado) y trató de eliminarlo, pero la llamada `unlinkSync` falló — típicamente porque el antivirus de Windows o un file-watcher (editor, indexador IDE) está reteniendo el file handle. Anteriormente esto se ignoraba silenciosamente, haciendo que el pipeline saltara el pass y reutilizara el marcador obsoleto. Ahora falla de forma explícita. Solución: cierra cualquier editor/AV scanner que pueda tener el archivo abierto, y vuelve a ejecutar `npx claudeos-core init`.
|
|
969
|
+
|
|
970
|
+
**"CLAUDEOS_SKIP_TRANSLATION=1 is set but --lang='ko' requires translation" InitError (v2.0.0)** — Tienes la variable de entorno de solo-test `CLAUDEOS_SKIP_TRANSLATION=1` configurada en tu shell (probablemente un resto de setup de CI/test) Y elegiste un `--lang` no-inglés. Esta env var cortocircuita el path de traducción del que dependen el fallback estático y el gap-fill de Pass 4 para la salida no-inglesa. `init` detecta el conflicto en el momento de la selección de idioma y aborta inmediatamente (en vez de crashear a mitad de Pass 4 con un error anidado confuso). Solución: o bien `unset CLAUDEOS_SKIP_TRANSLATION` antes de ejecutar, o usa `npx claudeos-core init --lang en`.
|
|
971
|
+
|
|
972
|
+
---
|
|
973
|
+
|
|
974
|
+
## Contribuir
|
|
975
|
+
|
|
976
|
+
¡Las contribuciones son bienvenidas! Áreas donde más se necesita ayuda:
|
|
977
|
+
|
|
978
|
+
- **Nuevas plantillas de stack** — Ruby/Rails, Go (Gin/Fiber/Echo), PHP (Laravel/Symfony), Rust (Axum/Actix), Svelte/SvelteKit, Remix
|
|
979
|
+
- **Integración IDE** — extensión de VS Code, plugin de IntelliJ
|
|
980
|
+
- **Plantillas de CI/CD** — GitLab CI, CircleCI, ejemplos de Jenkins (GitHub Actions ya incluido — ver `.github/workflows/test.yml`)
|
|
981
|
+
- **Test coverage** — Ampliar la suite de tests (actualmente 563 tests en 29 archivos de test cubriendo scanners, stack detection, domain grouping, plan parsing, prompt generation, CLI selectors, monorepo detection, Vite SPA detection, verification tools, memory scaffold L4, validación de resume de Pass 2, Pass 3 Guards 1/2/3 (H1 sentinel + H2 BOM-aware empty-file + estricto stale-marker unlink), sub-división por lotes de Pass 3 en modo split, resume de Pass 3 con marcador parcial (v2.1.0), validación del contenido del marcador de Pass 4 + rigor del stale-marker unlink + gap-fill de scaffoldSkillsManifest (v2.1.0), guard env-skip de traducción + early fail-fast + workflow CI, movimiento de staged-rules, fallback lang-aware de traducción, suite de regresión por eliminación de master plan (v2.1.0), regresión de formato de memory score/compact (v2.1.0), y estructura de la plantilla AI Work Rules)
|
|
982
|
+
|
|
983
|
+
Ver [`CONTRIBUTING.md`](./CONTRIBUTING.md) para la lista completa de áreas, estilo de código, convención de commits y la guía paso a paso para añadir una nueva plantilla de stack.
|
|
984
|
+
|
|
985
|
+
---
|
|
986
|
+
|
|
987
|
+
## Autor
|
|
988
|
+
|
|
989
|
+
Creado por **claudeos-core** — [GitHub](https://github.com/claudeos-core) · [Email](mailto:claudeoscore@gmail.com)
|
|
990
|
+
|
|
991
|
+
## Licencia
|
|
992
|
+
|
|
993
|
+
ISC
|