Añadir una funcionalidad¶
Cuatro formas de cambio, y cada una tiene un ejemplo desarrollado en otro sitio. Esta página es el mapa: qué tiene que tocar un cambio de esa forma, y dónde está la versión larga.
Añadir un endpoint de API nuevo¶
Un recorrido, en las guías
Añadir un endpoint de API es el ejemplo desarrollado — schema, modelo, repositorio, servicio, dependencia, ruta, router, migración, pruebas. Deliberadamente no hay aquí una segunda copia: dos copias escritas para el mismo lector son dos copias que se contradicen.
La forma que enseña, en un párrafo: un schema por operación
(*Create/*Update/*Read/*List), un modelo sobre Base, TimestampMixin
con un __repr__, un repositorio de funciones sin estado que usan
flush()/refresh() y nunca commit(), un servicio que solo guarda la
sesión y lanza excepciones de dominio, una dependencia Annotated en
api/deps.py, y una ruta que devuelve -> Any con response_model
encargándose de la serialización.
Añadir un comando propio a la CLI¶
Los comandos se descubren automáticamente desde app/commands/.
# app/commands/my_command.py
import click
from app.commands import command, success
@command("my-command", help="What this does")
@click.option("--name", "-n", required=True, help="Whose name")
def my_command(name: str) -> None:
"""One line, because `--help` prints it."""
success(f"Done: {name}")
success, error, warning e info son los ayudantes de salida — un comando
dice lo que ha pasado a través de ellos y no de print, de modo que todos los
comandos de la CLI se lean igual. Ejecútalo con:
Un comando nuevo le debe una fila a docs/commands.md
Esa página es la referencia que lee quien opera el sistema; un comando que no está en ella es un comando que nadie encuentra.
Añadir una herramienta que el agent pueda llamar¶
No hay un módulo de agent único donde colgar un @agent.tool. Aquí los agents son
datos, ensamblados por run a partir de las capabilities que nombra su spec, así
que una herramienta nueva llega como parte de una capability:
- Una nueva → Añadir una capability.
- Una herramienta más sobre una capability que ya existe → Añadir una herramienta a una capability existente.
- Una API de terceros que ya publica un servidor MCP → nada de código, mira MCP.
Una herramienta que el registro no declara no se puede controlar ni renombrar
La lista de @register(tools=...) es sobre lo que se apoyan la aprobación por
herramienta y el renombrado por agent. Una herramienta no declarada se ejecuta
igualmente — solo que se ejecuta sin control, que es el fallo que merece la
pena evitar.
Lo que se entrega hoy está en el catálogo de capabilities.
Añadir una migración de base de datos¶
make db-check se salta a sí mismo cuando no hay ninguna base de datos escuchando
alembic check necesita una, así que el target imprime un aviso y sale con
0 si no hay base de datos en CHECK_DB_PORT — un cambio de modelo sin
migración pasa entonces el make check local. El job test de CI tiene un
Postgres al lado y por eso no se salta, que es donde ese error se detecta de
verdad. Ejecuta make docker-db primero si quieres la respuesta local.
Autogenerate es un borrador, no una respuesta
Lee la revisión antes de hacer commit, y dale un downgrade que realmente la
revierta — make test-migrations recorre toda la cadena en ambos sentidos.