dataforge/fn_registry
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity
Files
master
fn_registry/dev/issues/0086-claude-md-delegation-and-capability-groups.md
T

14 KiB
Raw Permalink Blame History

id, title, status, type, domain, scope, priority, depends, blocks, related, created, updated, tags
id title status type domain scope priority depends blocks related created updated tags
0086 Refactor incremental de CLAUDE.md — delegacion agresiva a fn-constructor + capability groups por tags completado feature
meta
multi-app alta
0069
0085
2026-05-13 2026-05-17

Cierre 2026-05-14

15 capability groups en docs/capabilities/INDEX.md con descripcion + ejemplo canonico + fronteras: metabase, mantine, deploy, ssh, systemd, registry, bigquery, nlp, docker, android, doctor, notebook, cpp-windows, git. Hook gate post-creacion (hook_capability_tag_gate.sh) + vista session_capability_growth (migration 005) + linea CAPABILITY-GROWTH en UserPromptSubmit ya operativos. Reglas delegation.md + capability_groups.md presentes en .claude/rules/INDEX.md. CLAUDE.md tiene bloque "Delegacion + Capability Groups (REGLA DURA)" al principio.

Contexto

.claude/CLAUDE.md (proyecto) cubre bien el "que" (BDs, sync, MCP-first, antipatrones) pero NO documenta el bucle que multiplica capacidades de Claude:

detectar gap -> spawn fn-constructor -> indexar -> importar -> invocar (mismo turno)

Hoy Claude:

  • Detecta logica reutilizable y la escribe inline en el artefacto (o heredoc). No delega.
  • Cuando si delega, suele hacerlo secuencial aunque las funciones sean independientes.
  • Tras crear funciones nuevas, no las invoca en el mismo turno — quedan recien indexadas sin primer uso.
  • No marca con tags de grupo las nuevas funciones, asi que el siguiente turno (o siguiente sesion) no encuentra el cluster facilmente. Resultado: re-descubrimiento via FTS5 cada vez.
  • No hay documentacion de capability groups (ej. "metabase", "android-emu", "deploy", "notebook") — los tags existen sueltos pero sin pagina madre que liste el grupo, su API y ejemplos.

Issue 0085 ya da la base de telemetria (call_monitor + writes). Falta:

  1. Doctrina en CLAUDE.md que obligue al ciclo crear-usar-tagear-documentar en el mismo turno.
  2. Capability groups: tags canonicos + docs/capabilities/<group>.md autogenerable que liste funciones, firmas, ejemplos.
  3. Loop closure: paralelizar fn-constructor, auto-verificar con fn doctor, usar las nuevas funciones antes de cerrar turno.

Objetivo

Que Claude, en cada turno, multiplique su capacidad util registrando funciones nuevas y reusandolas inmediatamente — no acumular funciones huerfanas ni reescribir logica inline.

Tres entregables:

  1. Refactor incremental de .claude/CLAUDE.md (no reescritura completa): mantener estructura actual, comprimir secciones referenciales hacia docs/, anadir bloque nuevo "Delegacion + Capability Groups" al principio.
  2. Sistema de capability groups basado en tags + docs/capabilities/<group>.md generado por fn doctor capabilities (nuevo subcomando) o pipeline dedicado.
  3. Reglas duras nuevas en .claude/rules/ que el hook PreToolUse/UserPromptSubmit pueda verificar.

Diseno

Fase 1 — Bloque nuevo en CLAUDE.md (top del archivo)

Despues del parrafo "fn-registry" y antes de "Dos bases de datos SQLite", insertar bloque dedicado:

## Delegacion + Capability Groups (REGLA DURA)

Claude **multiplica capacidades** delegando creacion de funciones a `fn-constructor`
y reusandolas inmediatamente. NO escribir logica reutilizable inline.

### Cuando un patron es candidato a funcion

- Aparece >=2 veces en la sesion actual o en heredocs recientes.
- Firma es generica (no depende de tipos internos del artefacto).
- Tiene 1 responsabilidad clara (CRUD, parse, transform, http call, etc.).

### Flujo obligatorio (mismo turno)

1. **Detectar gap**. Si vas a escribir 5+ lineas de logica reutilizable inline -> STOP.
2. **Spawn `fn-constructor` inmediato** via `Agent(subagent_type="fn-constructor", ...)`.
   - Sin preguntar al usuario.
   - Si hay >1 funcion independiente -> **una sola llamada al Agent tool con N tool_use blocks paralelos**.
3. **Tagear con grupo de capacidad**. Cada funcion nueva lleva al menos UN tag de grupo
   (ej. `metabase`, `android-emu`, `notebook`, `deploy`, `osint`). Ver `docs/capabilities/`.
4. **`fn index`** para registrar.
5. **Importar y USAR en el mismo turno** — no dejar funcion huerfana recien creada.
6. **Auto-verificar**: `fn doctor uses-functions` y `fn doctor unused` para detectar drift.

### Anti-patrones (auditables)

| Anti-patron | Consecuencia | Sustituir por |
|---|---|---|
| Escribir helper inline en artefacto en vez de delegar | Re-invento por sesion | Spawn fn-constructor |
| Crear N funciones serialmente cuando son independientes | Latencia x N | Multiples Agent() en mismo mensaje |
| Crear funcion y no usarla en el turno | Funcion huerfana, calls_90d=0 desde dia 1 | Importar + invocar antes de cerrar turno |
| Crear funcion sin tag de grupo | Imposible descubrir en bloque la siguiente sesion | Anadir tag de capability group |
| Reescribir logica inline en heredoc que ya existe como funcion | Capitalizacion perdida | `mcp__registry__fn_search` antes de escribir |

### Capability groups

Cada grupo tiene una pagina madre en `docs/capabilities/<group>.md` con:
- Lista de funciones (ID + firma corta).
- 1-2 ejemplos canonicos de uso.
- Que NO hace el grupo (fronteras).

Generada/actualizada por `fn doctor capabilities --update`. Grupos vigentes:
ver `docs/capabilities/INDEX.md`.

Cuando Claude entra en una tarea de un dominio conocido, lee `docs/capabilities/<grupo>.md`
ANTES de buscar funciones sueltas. Eso desbloquea el grupo entero (no funcion a funcion).

Fase 2 — Comprimir secciones referenciales

Mover de CLAUDE.md a docs/:

Seccion actual Destino
Schema rapido (functions/types/unit_tests/pc_locations + FTS5) docs/schema.md
CLI completa (fn index, fn ops *, fn doctor, fn run, fn sync, fn proposal) docs/cli.md
Anadir funciones / Anadir tipos (paso a paso) docs/contributing.md
Analysis (estructura + crear + usar + helpers) docs/analysis.md
Bucle reactivo 5 fases (detalle ExecuteAndReact) docs/reactive_loop.md

CLAUDE.md queda como mapa (~150-180 lineas): identidad del repo + top reglas + tres patrones canonicos + punteros al INDEX de rules y a docs/.

Fase 3 — Capability groups (tags + docs autogeneradas)

3.1 Tags canonicos de grupo

Reservar un namespace de tags para "capability groups". Convencion: tag plano (sin prefijo) coincide con el slug del grupo:

Grupo Tag Cubre
metabase metabase Cliente HTTP, refresh metadata, dashboards, cards
android-emu android-emu adb, emulator, input events, screenshots
deploy deploy rsync, systemd, gitea webhook, vps setup
notebook notebook jupyter discover/read/exec/write/kernel
osint osint gliner/glirel, graph_explorer ingestion
frontend-ui frontend-ui @fn_library wrappers Mantine
sqlite-helpers sqlite-helpers open/migrate/wal/fts5
http-server http-server router, json response, middleware
... ... ...

fn doctor capabilities (nuevo subcomando) audita tags vs grupos declarados en docs/capabilities/INDEX.md.

3.2 Pagina madre por grupo

docs/capabilities/<grupo>.md autogenerable. Ejemplo docs/capabilities/notebook.md:

# Capability: notebook

Operar Jupyter Lab colaborativo desde cualquier sesion de Claude.

## Funciones

| ID | Firma | Que hace |
|---|---|---|
| jupyter_discover_py_notebook | `discover(host, port) -> JupyterInfo` | Lista instancias + kernels + sesiones |
| jupyter_read_py_notebook | `read(path, cell?) -> list[Cell]` | Lee celdas / metadata |
| jupyter_exec_py_notebook | `exec(mode, path, code, cell?)` | append/cell/kernel exec |
| jupyter_write_py_notebook | `write(action, path, content, cell?)` | append/insert/edit/delete |
| jupyter_kernel_py_notebook | `kernel(action, kernel_id?)` | list/start/restart/shutdown |

## Ejemplo canonico

\`\`\`bash
PY="python/.venv/bin/python3"
$PY python/functions/notebook/jupyter_discover.py --json
$PY python/functions/notebook/jupyter_exec.py append notebooks/01.ipynb "df.describe()"
\`\`\`

## Fronteras

NO incluye: ejecutar notebooks via papermill, scheduling, conversion a HTML.
Para eso ver `docs/capabilities/scheduling.md` o crear funcion nueva.

3.3 Autogeneracion

Nuevo pipeline generate_capability_doc_bash_pipelines <grupo>:

  • Query a registry.db: SELECT id, signature, description FROM functions WHERE tags LIKE '%"<grupo>"%'
  • Render template Markdown.
  • Escribir a docs/capabilities/<grupo>.md (preservando seccion "Ejemplo canonico" y "Fronteras" si existen — son curated, no autogenerables).

fn doctor capabilities:

  • Lista grupos en docs/capabilities/INDEX.md.
  • Para cada grupo, cuenta funciones taggeadas vs documentadas.
  • Avisa de drift: tag sin pagina, pagina sin funciones, funcion sin grupo.

Fase 4 — Reglas duras nuevas en .claude/rules/

Crear .claude/rules/delegation.md:

  • "Si vas a escribir >=5 lineas de logica reutilizable inline -> STOP -> spawn fn-constructor"
  • "Funciones independientes -> Agent paralelo en mismo mensaje"
  • "Funcion creada -> tag de grupo obligatorio -> usar en el mismo turno -> fn doctor uses-functions"

Crear .claude/rules/capability_groups.md:

  • Lista de grupos canonicos.
  • Como crear grupo nuevo (cuando hay >=3 funciones que comparten dominio + no encajan en grupo existente).
  • Como leer docs/capabilities/<grupo>.md antes de buscar funciones sueltas.

Actualizar .claude/rules/INDEX.md con las dos nuevas filas.

Fase 5 — Telemetria (reutiliza issue 0085, NO tabla nueva)

Anadir vista a call_monitor:

-- Funciones creadas + usadas en la misma sesion (multiplicador real)
CREATE VIEW IF NOT EXISTS session_capability_growth AS
SELECT
    w.session_id,
    w.function_id,
    w.created_at as first_write,
    MIN(c.ts) as first_call,
    COUNT(c.id) as calls_in_session
FROM code_writes w
LEFT JOIN calls c
    ON c.function_id = w.function_id
    AND c.session_id = w.session_id
    AND c.ts >= w.created_at
WHERE w.is_creation = 1
GROUP BY w.session_id, w.function_id;

Dashboard tab "Capability growth": cuantas funciones creo Claude por sesion, cuantas uso, cuantas quedaron huerfanas.

Hook UserPromptSubmit extiende su contexto con:

CAPABILITY-GROWTH: created_this_session=X used=Y orphan=Z. Si orphan>0 -> usa esas funciones o documenta por que no.

Decisiones tomadas (2026-05-14)

  • Minimo por grupo: 3-4 funciones para crear pagina madre. Tags con <3 funciones se mantienen sueltos.
  • Ubicacion docs: docs/capabilities/ (no .claude/capabilities/). Asi documentar, init y resto de agentes los leen igual que el resto de docs/.
  • Auto-tagging masivo: SI. Pasada inicial sobre todas las funciones existentes (clustering por dominio + signature similarity + co-ocurrencia en uses_functions). Las nuevas a partir de hoy llevan tag obligatorio.
  • Hook CAPABILITY-GROWTH: siempre on. Cada UserPromptSubmit inyecta linea CAPABILITY-GROWTH: created_this_session=X used=Y orphan=Z, incluso con valores 0/0/0. Razon: presencia constante crea disciplina, el banner muerto (0/0/0) es por si solo signal — recuerda que el bucle existe.

Pasos

  1. Inventario actual de tags en registry.db (SELECT tag, COUNT(*) FROM functions_tags GROUP BY tag) — identificar candidatos a grupo (tags con >=3 funciones).
  2. Auto-tagging masivo retroactivo: pipeline auto_tag_capabilities_bash_pipelines que:
    • Clusteriza funciones por domain + signature embedding + co-ocurrencia en uses_functions.
    • Propone tag de grupo para cada cluster con >=3 funciones.
    • Aplica via fn proposal add --kind add_tag (revision humana en bloque) o directo con --apply si confianza >0.9.
    • Idempotente: re-correr no duplica tags.
  3. Crear docs/capabilities/INDEX.md + 1 pagina piloto (ej. notebook.md) a mano para fijar formato.
  4. Implementar generate_capability_doc_bash_pipelines + fn doctor capabilities (audita drift tag<->doc).
  5. Refactor incremental de .claude/CLAUDE.md (insertar bloque + comprimir + mover a docs/).
  6. Crear .claude/rules/delegation.md + capability_groups.md + actualizar INDEX.
  7. Anadir vista session_capability_growth a call_monitor.
  8. Extender hook UserPromptSubmit con linea CAPABILITY-GROWTH (modo a definir).
  9. Gate post-creacion: hook PostToolUse sobre Agent(subagent_type=fn-constructor) que verifica que la funcion creada lleva al menos un tag de grupo antes de cerrar turno.
  10. Pilotar 3 grupos: notebook, metabase, deploy. Verificar que Claude (siguiente sesion) entra a docs/capabilities/metabase.md antes de buscar metabase_* sueltas.

Criterio de exito

  • CLAUDE.md baja a <=200 lineas, sin perder informacion (movida a docs/).
  • 5+ capability groups documentados con pagina madre.
  • En una sesion piloto, Claude crea >=2 funciones nuevas y las invoca en el mismo turno (vista session_capability_growth lo confirma).
  • fn doctor capabilities corre sin warnings tras la migracion inicial.
  • Reduccion medible de patrones inline repetidos (vista patterns del call_monitor) tras 1 semana.

Riesgos

  • Sobre-fragmentar en grupos pequenos: cada grupo con 2 funciones genera ruido. Minimo 3-4 funciones por grupo para crear pagina madre.
  • Tags duplicados / drift: metabase vs mb vs metabase-client. fn doctor capabilities debe avisar y proponer normalizacion.
  • Funciones nuevas huerfanas pese a la regla: si el "usar en mismo turno" es solo aspiracional, la regla muere. La vista de telemetria + hook de UserPromptSubmit son el gate real.
  • Refactor de CLAUDE.md rompe punteros existentes: revisar que .claude/commands/, subagentes.md, etc. no referencien secciones movidas. Dejar redirects breves.

Notas

  • Issue 0085 ya provee call_monitor + tablas calls, code_writes, patterns, violations. Esta issue NO crea tablas nuevas, solo vistas + reglas + docs.
  • El sistema de capability groups es analogo a "skills" de Claude Code pero a nivel de funciones del registry — un grupo desbloquea un conjunto de capacidades aprendido del codigo ya existente, no externo.
Reference in New Issue View Git Blame Copy Permalink