docs: añadir CLAUDE.md con guia del repositorio

Documenta para el agente el funcionamiento completo del repo: convenciones de naming e IDs, reglas de purity, estructura de directorios, tablas del schema, y flujo de trabajo esperado. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-28 01:59:17 +01:00
parent 727c706ebf
commit 4e97f5810a
1 changed files with 79 additions and 0 deletions
@@ -0,0 +1,79 @@
+# fn-registry
+
+Registry personal de codigo reutilizable con busqueda FTS. Diseñado para composicion funcional y agentes.
+
+## Que es esto
+
+Un warehouse de funciones, tipos, pipelines y componentes React organizados por dominio. Cada pieza de codigo tiene su archivo de implementacion (.go, .py, .tsx) y su archivo de documentacion (.md). Una BD SQLite con FTS5 indexa la documentacion para busqueda rapida.
+
+## Estructura del repositorio
+
+```
+fn-registry/
+  functions/          # Codigo y docs de funciones
+    core/             # Utilidades genericas (filter, map, clamp...)
+    finance/          # Dominio financiero (parse_ohlcv, indicators...)
+    io/               # Funciones impuras de IO (fetch, write...)
+    pipelines/        # Composiciones de funciones, siempre impuras
+    components/       # Componentes React (.tsx)
+  types/              # Tipos algebraicos (product y sum)
+    core/             # Tipos genericos (Result, Option...)
+    finance/          # Tipos de dominio (OHLCV, Tick, Order...)
+  cmd/fn/             # CLI para buscar, añadir e indexar
+  docs/               # Schema de documentacion (fuente de verdad del diseño)
+  registry.db         # Indice SQLite FTS5 (regenerable, no commitear)
+```
+
+## Convenciones
+
+- **Lenguaje principal:** Go. Tambien soporta Python, TypeScript, SQL.
+- **IDs:** formato `{name}_{lang}_{domain}` (ej: `filter_slice_go_core`)
+- **Nombres:** snake_case para funciones, PascalCase para tipos
+- **Rutas:** siempre relativas a la raiz del registry
+- **Purity:** `pure` (sin side effects) o `impure` (con side effects)
+  - Las funciones puras NUNCA dependen de funciones impuras
+  - Los pipelines son SIEMPRE impuros
+  - Los tipos no tienen purity
+
+## Tablas del registry
+
+### functions
+Almacena funciones atomicas, pipelines y componentes. Campo `kind`: `function` | `pipeline` | `component`. Ver `docs/functions.md` para el schema completo.
+
+### types
+Tipos algebraicos: `product` (struct, todos los campos presentes) o `sum` (union, un caso activo a la vez). Ver `docs/types.md` para el schema completo.
+
+## Reglas de integridad (ver docs/integrity.md)
+
+- `kind: pipeline` -> purity siempre impure, uses_functions no vacio
+- `purity: pure` -> returns_optional siempre false, error_type vacio
+- `purity: impure` -> error_type obligatorio
+- `tested: true` -> test_file_path y tests obligatorios
+- Todas las referencias cruzadas (uses_functions, uses_types, returns, error_type) deben apuntar a IDs existentes
+
+## Fuentes de verdad
+
+- **Codigo:** archivos .go / .py / .tsx
+- **Documentacion:** archivos .md junto al codigo
+- **Diseño del schema:** carpeta docs/
+- **registry.db:** solo indice, regenerable con `fn index`
+
+## CLI (cmd/fn)
+
+```bash
+fn search "texto"          # Busqueda FTS
+fn search -k function -p pure "slice"
+fn add                     # Añadir nueva entrada
+fn show <id>               # Ver entrada completa
+fn list                    # Listar todas
+fn index                   # Regenerar registry.db desde los .md
+```
+
+## Para el agente
+
+Al trabajar en este repo:
+1. Consultar docs/ antes de crear funciones o tipos — el schema manda
+2. Cada funcion/tipo necesita DOS archivos: implementacion + .md de documentacion
+3. Respetar la regla de purity: puras en el centro, impuras en los bordes
+4. Los IDs se generan automaticamente: `{name}_{lang}_{domain}`
+5. No editar registry.db a mano — siempre regenerar con `fn index`