merge: quick/claude-md-rewrite — CLAUDE.md con guia SQL y reglas de registro
This commit is contained in:
+182
-64
@@ -2,86 +2,204 @@
|
||||
|
||||
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
|
||||
|
||||
```
|
||||
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)
|
||||
functions/ # Codigo y docs de funciones
|
||||
core/ # Utilidades genericas (filter, map, pipeline, retry...)
|
||||
finance/ # Indicadores, riesgo, IO de mercado
|
||||
datascience/ # Estadistica, DSP, IO de datos
|
||||
cybersecurity/ # Crypto, analisis de red, IO de seguridad
|
||||
pipelines/ # Composiciones de funciones, siempre impuras
|
||||
components/ # Componentes React (.tsx)
|
||||
types/ # Tipos algebraicos (product y sum)
|
||||
core/ # Result, Option, Pair, Error
|
||||
finance/ # OHLCV, Tick, BollingerResult, DrawdownResult
|
||||
datascience/ # OutlierResult
|
||||
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
|
||||
|
||||
```bash
|
||||
# Requiere CGO y tag fts5 para SQLite FTS5
|
||||
CGO_ENABLED=1 go build -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)
|
||||
|
||||
```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
|
||||
fn index # Regenera registry.db desde los .md
|
||||
fn search "texto" # Busqueda FTS
|
||||
fn search -k function -p pure -d core "slice"
|
||||
fn list # Lista todo
|
||||
fn list -d finance -k function # Lista por dominio y kind
|
||||
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`
|
||||
|
||||
Reference in New Issue
Block a user