You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/best-practices.md
+62Lines changed: 62 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,6 +33,16 @@ For large projects, use imports:
33
33
```
34
34
Rules with `globs:` frontmatter load eagerly at session start. For lazy loading (on file match only), use `paths:` as unquoted CSV with `alwaysApply: false`.
35
35
36
+
## CLAUDE.md Modularization with @include
37
+
38
+
Instead of monolithic CLAUDE.md files, use the `@include` directive:
39
+
-`@./relative/path.md` — include relative to current file
40
+
-`@~/path.md` — include from home directory
41
+
-`@/absolute/path.md` — include absolute path
42
+
- Max depth: 5 levels (circular refs prevented)
43
+
- Only works in leaf text nodes (NOT inside code blocks)
44
+
- Use `claudeMdExcludes` in settings.json to toggle includes without deleting
Hooks can run in the background without blocking tool execution:
85
+
-`{"type": "command", "command": "script.sh", "async": true}` in settings.json
86
+
- Or stream `{"async":true}` as the first JSON line from hook stdout
87
+
-`asyncRewake: true` — hook can wake the agent after background completion
88
+
- Background hooks survive new user prompts but are killed on hard cancel (Escape)
89
+
- Best for: long-running validations, external API calls, metrics collection
90
+
72
91
### Domain rules — Project knowledge layer
73
92
74
93
Domain rules live in `.claude/rules/domain/` and represent accumulated knowledge about the project's specific domain (business logic, architectural decisions, non-obvious constraints). Unlike stack rules (how to code), domain rules encode what the project does and why.
@@ -244,6 +263,18 @@ Paste full stack trace + relevant code + context of when it occurs.
244
263
- block-destructive hook always active
245
264
- No Bash(*) — explicit permissions
246
265
266
+
## Auto-Mode Permission Stripping
267
+
268
+
When users activate auto/YOLO mode, these allow patterns are **silently removed**:
**Impact**: `Bash(python3 *)` in your allow list stops working without warning.
276
+
**Fix**: Use specific tool commands instead: `Bash(pytest *)`, `Bash(uvicorn *)`, `Bash(vitest *)`, `Bash(sam *)`.
277
+
247
278
---
248
279
249
280
# Mejores Prácticas — Claude Code (Marzo 2026)
@@ -279,6 +310,16 @@ Para proyectos grandes, usar imports:
279
310
```
280
311
Las rules con frontmatter `globs:` se cargan eager al inicio de sesión. Para lazy loading (solo cuando se toca un archivo que matchea), usar `paths:` como CSV sin quotes con `alwaysApply: false`.
281
312
313
+
## Modularización de CLAUDE.md con @include
314
+
315
+
En vez de CLAUDE.md monolíticos, usar la directiva `@include`:
316
+
-`@./relative/path.md` — include relativo al archivo actual
Los hooks pueden correr en segundo plano sin bloquear la ejecución de tools:
362
+
-`{"type": "command", "command": "script.sh", "async": true}` en settings.json
363
+
- O streamear `{"async":true}` como primera línea JSON desde stdout del hook
364
+
-`asyncRewake: true` — el hook puede despertar al agente al completarse
365
+
- Los hooks en background sobreviven nuevos prompts del usuario pero se matan con cancel duro (Escape)
366
+
- Ideal para: validaciones largas, llamadas a APIs externas, recolección de métricas
367
+
318
368
### Domain rules — Capa de conocimiento del proyecto
319
369
320
370
Las domain rules viven en `.claude/rules/domain/` y representan conocimiento acumulado sobre el dominio específico del proyecto (lógica de negocio, decisiones arquitectónicas, restricciones no-obvias). A diferencia de las stack rules (cómo codificar), las domain rules codifican qué hace el proyecto y por qué.
Copy file name to clipboardExpand all lines: docs/guia-uso.md
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -57,6 +57,10 @@ cd ~/Documents/GitHub/claude-kit # o donde tengas clonado claude-kit
57
57
58
58
**Multiplataforma:** Linux, macOS, WSL, Git Bash. Usa copias como fallback si los symlinks no funcionan.
59
59
60
+
### Contexto de Ejecución de Skills
61
+
62
+
Los skills pesados (>150 líneas, ~5K+ tokens) usan `context: fork` en su frontmatter. Esto ejecuta el skill en un subagente aislado, evitando que consuma la ventana de contexto de la conversación principal. Skills con `context: fork`: plugin-generator, bootstrap-project, init-project, domain-extract, audit-project.
0 commit comments