From 4e97f5810a60837924c6de6d7e92e89d3990d91f Mon Sep 17 00:00:00 2001 From: Egutierrez Date: Sat, 28 Mar 2026 01:59:17 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20a=C3=B1adir=20CLAUDE.md=20con=20guia=20?= =?UTF-8?q?del=20repositorio?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- .claude/CLAUDE.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 .claude/CLAUDE.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 00000000..d9886dbc --- /dev/null +++ b/.claude/CLAUDE.md @@ -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 # 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`