dataforge/fn_registry
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

docs: reescribir CLAUDE.md con guia de exploracion SQL y reglas para añadir funciones

Browse Source 
Reescribe completamente .claude/CLAUDE.md para que el agente LLM:
- Consulte SIEMPRE registry.db antes de escribir codigo (queries SQL listas)
- Sepa exactamente como crear funciones y tipos nuevos (formato, reglas, flujo)
- Entienda las reglas de integridad que el indexer valida
- Conozca la convencion de returns (IDs del registry, no tipos nativos)
- Tenga ejemplos de queries FTS, por dominio, por purity, por tags, por dependencias

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Egutierrez
2026-03-28 02:34:23 +01:00
parent 7443098774
commit 3693aed210
1 changed files with 182 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/CLAUDE.md
+182 -64
View File
@@ -2,86 +2,204 @@
Registry personal de codigo reutilizable con busqueda FTS. Diseñado para composicion funcional y agentes. Registry personal de codigo reutilizable con busqueda FTS. Diseñado para composicion funcional y agentes.
## Que es esto ## Explorar el registry (USAR SIEMPRE)
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. La BD SQLite `registry.db` es tu mapa del repositorio. Antes de escribir codigo, SIEMPRE consultala para saber que existe, evitar duplicados y descubrir funciones reutilizables.
```bash
# Buscar funciones por texto libre (FTS5)
sqlite3 registry.db "SELECT id, kind, purity, description FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'slice') ORDER BY name;"
# Listar todas las funciones de un dominio
sqlite3 registry.db "SELECT id, purity, signature FROM functions WHERE domain = 'finance' ORDER BY name;"
# Listar solo puras de un dominio
sqlite3 registry.db "SELECT id, signature FROM functions WHERE domain = 'core' AND purity = 'pure' ORDER BY name;"
# Listar solo impuras
sqlite3 registry.db "SELECT id, domain, error_type FROM functions WHERE purity = 'impure' ORDER BY domain, name;"
# Buscar tipos por dominio
sqlite3 registry.db "SELECT id, algebraic, description FROM types WHERE domain = 'cybersecurity';"
# Ver que funciones usa un pipeline o funcion compuesta
sqlite3 registry.db "SELECT id, uses_functions, uses_types FROM functions WHERE uses_functions != '[]';"
# Ver funciones que dependen de un tipo concreto
sqlite3 registry.db "SELECT id FROM functions WHERE uses_types LIKE '%ohlcv_go_finance%';"
# Buscar por tag
sqlite3 registry.db "SELECT id, tags FROM functions WHERE tags LIKE '%generic%';"
# Contar entradas por dominio
sqlite3 registry.db "SELECT domain, COUNT(*) FROM functions GROUP BY domain;"
# Ver todo el schema
sqlite3 registry.db ".schema"
```
La BD usa WAL mode — puedes leerla mientras se escribe sin bloqueos.
## Estructura del repositorio ## Estructura del repositorio
``` ```
fn-registry/ fn-registry/
functions/ # Codigo y docs de funciones functions/ # Codigo y docs de funciones
core/ # Utilidades genericas (filter, map, clamp...) core/ # Utilidades genericas (filter, map, pipeline, retry...)
finance/ # Dominio financiero (parse_ohlcv, indicators...) finance/ # Indicadores, riesgo, IO de mercado
io/ # Funciones impuras de IO (fetch, write...) datascience/ # Estadistica, DSP, IO de datos
pipelines/ # Composiciones de funciones, siempre impuras cybersecurity/ # Crypto, analisis de red, IO de seguridad
components/ # Componentes React (.tsx) pipelines/ # Composiciones de funciones, siempre impuras
types/ # Tipos algebraicos (product y sum) components/ # Componentes React (.tsx)
core/ # Tipos genericos (Result, Option...) types/ # Tipos algebraicos (product y sum)
finance/ # Tipos de dominio (OHLCV, Tick, Order...) core/ # Result, Option, Pair, Error
cmd/fn/ # CLI para buscar, añadir e indexar finance/ # OHLCV, Tick, BollingerResult, DrawdownResult
docs/ # Schema de documentacion (fuente de verdad del diseño) datascience/ # OutlierResult
registry.db # Indice SQLite FTS5 (regenerable, no commitear) cybersecurity/ # CIDRBlock, ThreatResult, PortResult
registry/ # Libreria Go: modelos, SQLite, parser, indexer, validacion
cmd/fn/ # CLI
docs/ # Schema de documentacion v1.0 (fuente de verdad del diseño)
docs/templates/ # Plantillas de frontmatter para function, pipeline, component, type
registry.db # Indice SQLite FTS5+WAL (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`
## Build ## Build
```bash ```bash
# Requiere CGO y tag fts5 para SQLite FTS5
CGO_ENABLED=1 go build -tags fts5 ./... CGO_ENABLED=1 go build -tags fts5 ./...
CGO_ENABLED=1 go test -tags fts5 ./... CGO_ENABLED=1 go test -tags fts5 ./...
CGO_ENABLED=1 go build -tags fts5 -o fn ./cmd/fn/
``` ```
## Reglas para añadir funciones nuevas
### Antes de crear
1. **Consulta la BD** para verificar que no existe algo similar:
```bash
sqlite3 registry.db "SELECT id, description FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'tu busqueda');"
```
2. **Identifica el dominio** correcto: core, finance, datascience, cybersecurity, o crea uno nuevo si no encaja
3. **Decide la purity**: pure si no tiene side effects, impure si tiene IO/estado/goroutines/tiempo
### Archivos a crear
Cada funcion requiere EXACTAMENTE dos archivos:
1. **Implementacion** `functions/{domain}/{name}.go` — codigo real, compilable
2. **Documentacion** `functions/{domain}/{name}.md` — frontmatter YAML con metadata
### Formato del .md (frontmatter YAML)
```yaml
---
name: nombre_snake_case
kind: function # function | pipeline | component
lang: go # go | python | typescript | sql
domain: core # core | finance | datascience | cybersecurity | ...
version: "1.0.0"
purity: pure # pure | impure
signature: "func NombreCompleto(...) ..."
description: "Descripcion en español de que hace y cuando usarla."
tags: [tag1, tag2, tag3]
uses_functions: [] # IDs de funciones del registry que invoca
uses_types: [] # IDs de tipos del registry que recibe
returns: [] # IDs de tipos del registry que devuelve
returns_optional: false
error_type: "" # ID de tipo de error, obligatorio si impure
imports: [] # dependencias externas fuera del registry
tested: false
tests: []
test_file_path: ""
file_path: "functions/{domain}/{name}.go"
---
## Ejemplo
` `` go
resultado := MiFuncion(input)
` ``
## Notas
Explicacion adicional si es necesario.
```
### Reglas de integridad (el indexer las valida)
| Regla | Condicion |
|---|---|
| Pipeline siempre impuro | `kind: pipeline` -> `purity: impure` + `uses_functions` no vacio |
| Pura sin side effects | `purity: pure` -> `returns_optional: false` + `error_type: ""` |
| Impura declara errores | `purity: impure` -> `error_type` obligatorio (usar `error_go_core`) |
| Tests coherentes | `tested: true` -> `test_file_path` y `tests` obligatorios |
| Referencias validas | `uses_functions`, `uses_types`, `returns`, `error_type` deben apuntar a IDs existentes |
| Component tiene framework | `kind: component` -> `framework` obligatorio, `returns` vacio (usar `emits`) |
| Rutas relativas | `file_path` siempre relativa a la raiz, nunca absoluta |
| IDs unicos | Formato `{name}_{lang}_{domain}`, colisiones rechazadas |
### Campo `returns` vs tipo nativo
El campo `returns` en el .md es para IDs de tipos del registry (ej: `ohlcv_go_finance`), NO para tipos nativos de Go (`float64`, `string`, `bool`). Si la funcion devuelve tipos nativos, deja `returns: []`.
### Despues de crear
```bash
# Regenerar el indice
./fn index
# o
CGO_ENABLED=1 go build -tags fts5 -o fn ./cmd/fn/ && ./fn index
# Verificar que se indexo sin errores
./fn show {name}_{lang}_{domain}
```
## Reglas para añadir tipos nuevos
Cada tipo requiere dos archivos: `types/{domain}/{name}.go` y `types/{domain}/{name}.md`.
```yaml
---
name: nombre_snake_case
lang: go
domain: core
version: "1.0.0"
algebraic: product # product (struct) | sum (interface/union)
definition: |
type MiTipo struct { ... }
description: "Descripcion en español."
tags: [tag1, tag2]
uses_types: [] # IDs de otros tipos que compone (sin auto-referencias)
file_path: "types/{domain}/{name}.go"
---
```
## Convenciones
- **IDs:** `{name}_{lang}_{domain}` (ej: `filter_slice_go_core`)
- **Nombres:** snake_case para funciones, PascalCase para tipos en Go
- **Paquete Go:** el nombre del directorio (core, finance, datascience, cybersecurity)
- **Tipos en firmas:** usar tipos nativos (float64, []float64, string) para evitar imports circulares entre paquetes de funciones. Documentar los tipos del registry en `uses_types`/`returns` del .md
- **Purity:** puras en el centro, impuras en los bordes. Una pura NUNCA depende de una impura
- **Stubs impuros:** si la implementacion real requiere dependencias externas no disponibles, crear stub con `return ..., fmt.Errorf("not implemented")` y documentar completamente el .md
## Fuentes de verdad
| Que | Donde |
|---|---|
| Codigo | archivos .go / .py / .tsx |
| Documentacion | archivos .md junto al codigo |
| Diseño del schema | carpeta docs/ |
| Indice de busqueda | registry.db (regenerable con `fn index`) |
## CLI (cmd/fn) ## CLI (cmd/fn)
```bash ```bash
fn search "texto" # Busqueda FTS fn index # Regenera registry.db desde los .md
fn search -k function -p pure "slice" fn search "texto" # Busqueda FTS
fn add # Añadir nueva entrada fn search -k function -p pure -d core "slice"
fn show <id> # Ver entrada completa fn list # Lista todo
fn list # Listar todas fn list -d finance -k function # Lista por dominio y kind
fn index # Regenerar registry.db desde los .md fn show filter_slice_go_core # Muestra entrada completa
fn add -k function # Muestra template para copiar
``` ```
## 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`