docs: simplificar CLAUDE.md de 284 a 97 líneas
Se condensa el archivo principal de contexto eliminando redundancia con las reglas detalladas que ya viven en .claude/rules/*.md. Cambios: - Eliminar secciones duplicadas (dev-scripts, env vars, dependencias, extensiones pendientes) que ya están documentadas en otros archivos - Mantener los dos pilares (FP + TBD) como secciones principales - Condensar estructura de directorios, agentes, build y preferencias - Referenciar .claude/rules/index.md para guías detalladas No se pierde información: todo lo eliminado existe en rules/, MEMORY.md, o README.md. El archivo queda más enfocado y dentro de límites razonables para el contexto de LLMs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
+62
-249
@@ -1,284 +1,97 @@
|
|||||||
# CLAUDE.md — Contexto del proyecto agents_and_robots
|
# CLAUDE.md — agents_and_robots
|
||||||
|
|
||||||
## Qué es este proyecto
|
Monorepo Go para bots Matrix autonomos. Modulo: `github.com/enmanuel/agents`.
|
||||||
|
|
||||||
Monorepo en Go para gestionar bots Matrix. Cada bot es un agente autónomo con personalidad, reglas de decisión y acceso a herramientas (LLM, SSH, HTTP, MCP). Los bots se comunican entre sí y con humanos a través de Matrix (mautrix-go).
|
**Homeserver:** `https://matrix-af2f3d.organic-machine.com` | **Server name:** `matrix-af2f3d.organic-machine.com`
|
||||||
|
|
||||||
**Homeserver activo:** `https://matrix-af2f3d.organic-machine.com`
|
## Los dos pilares — SIEMPRE APLICAR
|
||||||
**Server name:** `matrix-af2f3d.organic-machine.com`
|
|
||||||
|
|
||||||
## Filosofía de diseño — LA REGLA MÁS IMPORTANTE
|
### 1. Functional PRogramming: Pure core / Impure shell
|
||||||
|
|
||||||
El proyecto usa el patrón **pure core / impure shell** estrictamente:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
pkg/ → PURE: solo tipos, funciones puras, cero side effects
|
pkg/ → PURO: tipos, funciones puras, cero side effects
|
||||||
shell/ → IMPURE: todo I/O, red, filesystem, procesos
|
shell/ → IMPURO: todo I/O (Matrix, LLM, SSH, filesystem)
|
||||||
agents/ → composición: reglas puras + ensamblado con shell en runtime.go
|
agents/ → composicion: reglas puras + ensamblado con shell
|
||||||
|
tools/ → Def (puro) + Exec (impuro)
|
||||||
```
|
```
|
||||||
|
|
||||||
**Nunca** añadir side effects (I/O, red, llamadas a APIs) dentro de `pkg/`.
|
**Nunca** side effects en `pkg/`. El core produce `[]decision.Action` (datos puros), el shell los interpreta.
|
||||||
**Siempre** que el core necesite "hacer algo", produce un `[]decision.Action` (datos puros) que el shell interpreta.
|
|
||||||
|
|
||||||
El flujo es siempre:
|
|
||||||
```
|
```
|
||||||
Matrix event → Parse (pure) → Evaluate rules (pure) → []Action (pure data)
|
Matrix event → Parse (pure) → Evaluate rules (pure) → []Action (pure data)
|
||||||
→ Runner.Execute (impure) → efectos reales
|
→ Runner.Execute (impure) → efectos reales
|
||||||
```
|
```
|
||||||
|
|
||||||
## Módulo Go
|
### 2. TBD: Trunk-based development
|
||||||
|
|
||||||
`github.com/enmanuel/agents`
|
**master** es el unico branch estable. Nunca trabajar directamente en master.
|
||||||
|
|
||||||
## Estructura de directorios
|
|
||||||
|
|
||||||
```
|
```
|
||||||
pkg/decision/ → motor de reglas puro (Evaluate, Rule, MatchFunc, Action)
|
master ← siempre deployable
|
||||||
pkg/llm/ → tipos de LLM puros (CompleteFunc, CompletionRequest, Route)
|
|
||||||
pkg/tools/ → specs declarativas de herramientas (SSHCommandSpec, etc.)
|
|
||||||
pkg/message/ → parse y format de mensajes Matrix (puros)
|
|
||||||
pkg/personality/ → tipos de personalidad (Personality, Tone, etc.)
|
|
||||||
|
|
||||||
shell/llm/ → clientes LLM reales (anthropic.go, openai.go, factory.go)
|
|
||||||
shell/matrix/ → cliente Matrix mautrix-go (client.go, listener.go)
|
|
||||||
shell/ssh/ → ejecutor SSH real (executor.go)
|
|
||||||
shell/effects/ → Runner que interpreta []Action → side effects
|
|
||||||
shell/bus/ → comunicación inter-agente via Go channels
|
|
||||||
shell/protocols/ → adaptadores MCP (mcp.go)
|
|
||||||
|
|
||||||
agents/runtime.go → Agent{}: ensambla core + shell, maneja eventos
|
|
||||||
agents/assistant-bot/ → reglas puras + config del assistant-bot
|
|
||||||
|
|
||||||
internal/config/schema.go → tipos completos del YAML de configuración
|
|
||||||
internal/config/loader.go → Load() con expand env vars, LoadMeta() sin validación
|
|
||||||
cmd/launcher/main.go → inicia agentes, tiene rulesRegistry
|
|
||||||
cmd/agentctl/main.go → CLI de gestión (list, start, stop, remove)
|
|
||||||
cmd/register/main.go → registra bots en Synapse via admin API
|
|
||||||
dev-scripts/ → scripts bash para operaciones del día a día
|
|
||||||
dev-scripts/server/ → gestión del launcher (start, stop, restart, ps, logs, dashboard)
|
|
||||||
dev-scripts/agent/ → gestión de agentes (new, register, verify, avatar, remove, list)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Reglas para LLMs
|
|
||||||
|
|
||||||
Las reglas guían cómo ejecutar tareas específicas respetando la arquitectura del proyecto.
|
|
||||||
Ver índice completo en `.claude/rules/index.md`.
|
|
||||||
|
|
||||||
| Regla | Cuándo aplicarla |
|
|
||||||
|-------|------------------|
|
|
||||||
| `.claude/rules/create_agent.md` | Al crear un nuevo bot/agente Matrix |
|
|
||||||
| `.claude/rules/create_tool.md` | Al añadir una nueva tool para function calling |
|
|
||||||
| `.claude/rules/create_command.md` | Al añadir un comando directo (!xxx) a un agente |
|
|
||||||
| `.claude/rules/create_issue.md` | Al crear un nuevo issue en `dev/issues/` |
|
|
||||||
| `.claude/rules/fix_issue.md` | Al implementar/arreglar un issue existente |
|
|
||||||
|
|
||||||
Documentación detallada para humanos en `docs/creating-agents.md`.
|
|
||||||
|
|
||||||
## Agentes existentes
|
|
||||||
|
|
||||||
| ID | Estado | LLM | Descripción |
|
|
||||||
|----------------|-----------|---------|------------------------------------------|
|
|
||||||
| assistant-bot | activo | GPT-4o | Asistente general, responde DMs |
|
|
||||||
| asistente-2 | activo | GPT-4o | Asistente con tools (current_time) |
|
|
||||||
|
|
||||||
## Dependencias clave
|
|
||||||
|
|
||||||
```
|
|
||||||
maunium.net/go/mautrix v0.21.1 → Matrix client
|
|
||||||
github.com/sashabaranov/go-openai → OpenAI + Ollama-compatible
|
|
||||||
github.com/mark3labs/mcp-go → MCP protocol server/client
|
|
||||||
golang.org/x/crypto/ssh → SSH execution
|
|
||||||
github.com/spf13/cobra → CLI
|
|
||||||
gopkg.in/yaml.v3 → Config parsing
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuración de agentes
|
|
||||||
|
|
||||||
Cada agente vive en `agents/<id>/`:
|
|
||||||
- `config.yaml` — configuración completa (ver schema en `internal/config/schema.go`)
|
|
||||||
- `agent.go` — reglas puras que implementan `Rules() []decision.Rule`
|
|
||||||
- `prompts/system.md` — system prompt del LLM
|
|
||||||
- `data/` — datos de runtime (SQLite, crypto, logs) — en .gitignore
|
|
||||||
|
|
||||||
El `config.yaml` soporta variables de entorno con `${VAR}` y `$VAR`. El loader usa `os.ExpandEnv`.
|
|
||||||
|
|
||||||
Secciones principales del config: `agent`, `personality`, `llm`, `tools`, `matrix`, `agents` (peers), `ssh`, `security`, `schedules`, `observability`, `resilience`, `storage`.
|
|
||||||
|
|
||||||
## Cómo añadir un nuevo bot
|
|
||||||
|
|
||||||
Guía rápida (detalle completo en `docs/creating-agents.md`, regla en `.claude/rules/create_agent.md`):
|
|
||||||
|
|
||||||
1. Crear scaffold: `./dev-scripts/agent/new-agent.sh <id> "Display Name"` o manual en `agents/<id>/`
|
|
||||||
2. Crear `agent.go` (reglas puras), `config.yaml`, `prompts/system.md`
|
|
||||||
3. Registrar en `cmd/launcher/main.go` → import + `rulesRegistry`
|
|
||||||
4. Registrar en Matrix: `./dev-scripts/agent/register.sh <id> "Display Name"`
|
|
||||||
5. Avatar y nombre: `./dev-scripts/agent/avatar.sh <id> static/<imagen>.jpg`
|
|
||||||
6. Verificación E2EE: `go run -tags goolm ./cmd/verify --homeserver ... --username <id> --password ... --token ...`
|
|
||||||
7. Arrancar: `./dev-scripts/server/start.sh <id>`
|
|
||||||
|
|
||||||
## Dev-scripts disponibles
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# === server/ — gestión del launcher ===
|
|
||||||
./dev-scripts/server/start.sh # iniciar el launcher
|
|
||||||
./dev-scripts/server/stop.sh # detener el launcher
|
|
||||||
./dev-scripts/server/restart.sh # reiniciar el launcher
|
|
||||||
./dev-scripts/server/ps.sh # procesos con detalle (PID, mem, CPU, uptime)
|
|
||||||
./dev-scripts/server/logs.sh [lines] # tail -f de logs
|
|
||||||
./dev-scripts/server/dashboard.sh # TUI interactiva
|
|
||||||
|
|
||||||
# Gestión unificada (wrapper)
|
|
||||||
./dev-scripts/server/server.sh start # iniciar
|
|
||||||
./dev-scripts/server/server.sh stop # detener
|
|
||||||
./dev-scripts/server/server.sh restart # reiniciar
|
|
||||||
./dev-scripts/server/server.sh status # resumen general del servidor
|
|
||||||
./dev-scripts/server/server.sh ps # procesos con detalle
|
|
||||||
./dev-scripts/server/server.sh logs # tail -f de logs
|
|
||||||
./dev-scripts/server/server.sh kill # SIGKILL forzado (emergencia)
|
|
||||||
|
|
||||||
# === agent/ — gestión de agentes ===
|
|
||||||
./dev-scripts/agent/list.sh # ver todos los bots y estado
|
|
||||||
./dev-scripts/agent/new-agent.sh <id> [name] # scaffold completo
|
|
||||||
./dev-scripts/agent/register.sh <id> [name] # registrar bot en Matrix
|
|
||||||
./dev-scripts/agent/verify.sh [agent-id] # verificación E2EE
|
|
||||||
./dev-scripts/agent/avatar.sh <id> <img> # subir avatar
|
|
||||||
./dev-scripts/agent/reset-password.sh <id> # resetear password
|
|
||||||
./dev-scripts/agent/remove.sh <agent-id> # deshabilitar (sin borrar datos)
|
|
||||||
```
|
|
||||||
|
|
||||||
PID files: `run/<id>.pid` | Log files: `run/<id>.log`
|
|
||||||
|
|
||||||
## Gestión de procesos
|
|
||||||
|
|
||||||
Los bots corren como procesos independientes lanzados por `agentctl` o `dev-scripts/server/start.sh`.
|
|
||||||
Cada proceso escribe su PID en `run/<id>.pid` y su log en `run/<id>.log`.
|
|
||||||
`is_running()` usa `kill -0 <pid>` para verificar sin matar el proceso.
|
|
||||||
|
|
||||||
## Variables de entorno críticas
|
|
||||||
|
|
||||||
```bash
|
|
||||||
MATRIX_HOMESERVER # URL del servidor Matrix
|
|
||||||
MATRIX_SERVER_NAME # nombre del servidor (parte después de :)
|
|
||||||
MATRIX_ADMIN_TOKEN # token admin para registrar bots (cmd/register)
|
|
||||||
MATRIX_TOKEN_<BOT> # access token de cada bot
|
|
||||||
OPENAI_API_KEY # OpenAI
|
|
||||||
ANTHROPIC_API_KEY # Anthropic/Claude
|
|
||||||
```
|
|
||||||
|
|
||||||
Nunca commitear `.env`. Plantilla en `.env.example`.
|
|
||||||
|
|
||||||
## Trunk-based development (TBD)
|
|
||||||
|
|
||||||
El proyecto usa trunk-based development estricto. **master** es el único branch estable y siempre deployable.
|
|
||||||
|
|
||||||
### Flujo de trabajo
|
|
||||||
|
|
||||||
```
|
|
||||||
master (trunk) ← siempre deployable, único branch permanente
|
|
||||||
↑
|
↑
|
||||||
└── issue/<NNNN>-<slug> ← rama efímera (horas, no días)
|
└── issue/<NNNN>-<slug> ← rama efimera (horas)
|
||||||
├── commit: feat: ...
|
commits atomicos (feat:, fix:, test:, docs:, refactor:, chore:)
|
||||||
├── commit: test: ...
|
|
||||||
└── commit: docs: ...
|
|
||||||
merge --no-ff → master → push → delete branch
|
merge --no-ff → master → push → delete branch
|
||||||
```
|
```
|
||||||
|
|
||||||
1. **`/git-branch`** — crea rama `issue/<NNNN>-<slug>` desde master actualizado
|
- `/git-branch` — crea rama desde master
|
||||||
2. Implementar en la rama con commits granulares por bloque lógico
|
- `/git-push` — tests → merge --no-ff → push → elimina rama
|
||||||
3. **`/git-push`** — tests → merge `--no-ff` a master → push → eliminar rama
|
- Commits atomicos por bloque logico, titulo corto + cuerpo en espanol
|
||||||
|
- No WIP, no squash, no rebase -i
|
||||||
|
|
||||||
### Convención de commits
|
**Feature flags** (solo para features multi-issue): codigo completo y testeado, mergeado pero desactivado. Flag != WIP. Archivo: `dev/feature_flags.json`.
|
||||||
|
|
||||||
Dentro de la rama, cada commit es **atómico por bloque lógico** (no mezclar feat + test en uno):
|
## Estructura
|
||||||
|
|
||||||
| Prefijo | Uso |
|
|
||||||
|---------|-----|
|
|
||||||
| `feat:` | nueva funcionalidad |
|
|
||||||
| `fix:` | corrección de error |
|
|
||||||
| `refactor:` | cambio estructural sin cambio funcional |
|
|
||||||
| `docs:` | documentación |
|
|
||||||
| `chore:` | mantenimiento |
|
|
||||||
| `test:` | tests nuevos o modificados |
|
|
||||||
| `merge:` | commit de merge (generado por `--no-ff`) |
|
|
||||||
|
|
||||||
- **Título** (`-m` corto): resumen del bloque
|
|
||||||
- **Cuerpo** (`-m` largo): en español, explica qué, por qué, impacto y alcance
|
|
||||||
- **No hacer commits WIP**: nada de "wip", "tmp", "fix fix" — cada commit debe tener mensaje real
|
|
||||||
- **No squash**: `--no-ff` preserva los commits individuales; `git log --first-parent master` da la vista limpia (un merge = un issue)
|
|
||||||
|
|
||||||
### Reglas de ramas
|
|
||||||
|
|
||||||
- **Nunca trabajar directamente en master** — siempre crear rama con `/git-branch`
|
|
||||||
- **Una rama por issue** — no mezclar issues en la misma rama
|
|
||||||
- **Ramas cortas** — idealmente horas, no días
|
|
||||||
- **Nunca pushear la rama** — solo se pushea master después del merge
|
|
||||||
- **No rebase interactivo** — si los commits ya son limpios, no hay nada que reescribir
|
|
||||||
|
|
||||||
### Feature flags — features grandes en TBD
|
|
||||||
|
|
||||||
En TBD no existen ramas largas. Para features que no caben en una sola rama, se usan **feature flags**: código completo y testeado que se mergea a master pero desactivado hasta que todas las piezas estén listas.
|
|
||||||
|
|
||||||
**Feature flag ≠ WIP.** Un flag protege código terminado; un WIP es código a medias. Nunca commitear código incompleto.
|
|
||||||
|
|
||||||
**Cuándo usar feature flags:**
|
|
||||||
- Feature multi-issue que requiere varias ramas para completarse
|
|
||||||
- Cambio con riesgo que necesita poder desactivarse en producción
|
|
||||||
- Despliegue gradual (activar para un agente primero, después para todos)
|
|
||||||
|
|
||||||
**Cuándo NO usarlos:**
|
|
||||||
- Issue autocontenido que se completa en una rama → mergear directo
|
|
||||||
- Bug fix, refactor, docs → no necesitan flag
|
|
||||||
|
|
||||||
**Flujo para features multi-issue:**
|
|
||||||
|
|
||||||
```
|
```
|
||||||
Feature grande (ej: 0015 Telegram)
|
pkg/decision/ motor de reglas puro
|
||||||
├── issue/0015a-telegram-types → pkg/ types, flag OFF → merge
|
pkg/llm/ tipos LLM puros
|
||||||
├── issue/0015b-telegram-client → shell/ client, flag OFF → merge
|
pkg/message/ parse/format mensajes
|
||||||
├── issue/0015c-telegram-listener → integration, flag OFF → merge
|
pkg/personality/ tipos de personalidad
|
||||||
└── issue/0015d-telegram-enable → flag ON, cleanup → merge
|
shell/llm/ clientes LLM (anthropic, openai)
|
||||||
|
shell/matrix/ cliente Matrix (mautrix-go)
|
||||||
|
shell/ssh/ ejecutor SSH
|
||||||
|
shell/effects/ Runner: []Action → side effects
|
||||||
|
shell/bus/ comunicacion inter-agente
|
||||||
|
agents/runtime.go Agent{}: ensambla core + shell
|
||||||
|
agents/<id>/ agent.go (reglas puras) + config.yaml + prompts/system.md
|
||||||
|
tools/ tool registry + tool implementations (subpackages)
|
||||||
|
internal/config/ schema.go + loader.go
|
||||||
|
cmd/launcher/ entrypoint principal (rulesRegistry)
|
||||||
|
cmd/agentctl/ CLI de gestion
|
||||||
|
dev-scripts/server/ start, stop, restart, ps, logs, dashboard
|
||||||
|
dev-scripts/agent/ new, register, verify, avatar, remove, list
|
||||||
```
|
```
|
||||||
|
|
||||||
Cada rama es corta, cada merge es seguro, master nunca se rompe.
|
## Reglas operativas
|
||||||
|
|
||||||
**Archivo:** `dev/feature_flags.json`
|
Guias detalladas en `.claude/rules/index.md`:
|
||||||
|
|
||||||
```json
|
| Regla | Cuando |
|
||||||
{
|
|-------|--------|
|
||||||
"flags": {
|
| `create_agent.md` | Crear nuevo bot/agente |
|
||||||
"telegram-support": {
|
| `create_tool.md` | Añadir tool para function calling |
|
||||||
"enabled": false,
|
| `create_command.md` | Añadir comando !xxx |
|
||||||
"issue": "0015",
|
| `create_issue.md` | Crear issue en dev/issues/ |
|
||||||
"description": "Soporte multi-plataforma Telegram",
|
| `fix_issue.md` | Implementar un issue existente |
|
||||||
"added": "2026-03-07"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Comandos disponibles
|
## Agentes
|
||||||
|
|
||||||
- `/git-branch` — crear rama de trabajo (`.claude/commands/git-branch.md`)
|
| ID | LLM | Descripcion |
|
||||||
- `/git-push` — integrar rama a master y publicar (`.claude/commands/git-push.md`)
|
|----|-----|-------------|
|
||||||
|
| assistant-bot | GPT-4o | Asistente general, DMs |
|
||||||
|
| asistente-2 | GPT-4o | Asistente con tools |
|
||||||
|
|
||||||
## Preferencias del usuario
|
## Build
|
||||||
|
|
||||||
- **Idioma**: español en configs/comentarios de dominio, inglés en código Go
|
- Go 1.23.5 (`/usr/local/go/bin`), siempre compilar con `-tags goolm`
|
||||||
- **Estilo**: FP estricto (pure core / impure shell), sin abstracción prematura
|
- CGO_ENABLED=0 (pure-Go SQLite via modernc, shim en `cmd/launcher/sqlite.go`)
|
||||||
- **Desarrollo**: trunk-based, Gitea como remote
|
- Secrets via env vars (`.env.example`), nunca commitear `.env`
|
||||||
- **Go version**: 1.23.5 en `/usr/local/go/bin`
|
|
||||||
- **No usar** frameworks de agentes externos — arquitectura propia
|
|
||||||
|
|
||||||
## Documentacion de desarrollo
|
## Preferencias
|
||||||
|
|
||||||
Ver `dev/README.md` para el indice de documentacion interna (issues pendientes, diseños tecnicos, etc.).
|
- Espanol en configs/comentarios de dominio, ingles en codigo Go
|
||||||
Issues detallados en `dev/issues/`.
|
- FP estricto, sin abstraccion prematura
|
||||||
|
- Trunk-based, Gitea como remote
|
||||||
## Próximas extensiones naturales
|
- Arquitectura propia, sin frameworks de agentes externos
|
||||||
|
- Issues en `dev/issues/`, docs internas en `dev/README.md`
|
||||||
- Scheduling: cron runner en `shell/` para `ScheduleCfg`
|
|
||||||
- Conversation history: mantener `[]Message` por room en memoria/SQLite
|
|
||||||
- RBAC real: conectar `SecurityCfg.Roles` al listener
|
|
||||||
- E2EE: habilitar `encryption.enabled: true` con crypto store de mautrix
|
|
||||||
- MCP: exponer tools de los agentes como MCP server en el puerto configurado
|
|
||||||
- A2A: agent card HTTP endpoint para comunicación con agentes externos
|
|
||||||
|
|||||||
Reference in New Issue
Block a user