Notas prácticas: Deja de mirar a tu agente de programación: construye un sistema en el que puedas confiar
Guía práctica paso a paso: Deje de depender de su agente de programación: cree un sistema en el que pueda confiar, con contratos, verificaciones y espacios para código listo para uso destinados a los equipos que implementan este patrón.
Úselo como una versión reestructurada dirigida a los operadores de las ideas presentadas en “Deja de vigilar a tu agente de programación: construye un sistema en el que puedas confiar”: etapas claras, espacios ordenados para el código y notas de recuperación que perduran tras la transferencia de tareas. La etapa de Resumen funciona mejor cuando se trata como una superficie medible. Registra una transcripción clave, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiere unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado.
El problema: probablemente sigues haciendo la mitad del trabajo
Para la etapa en la que te encuentras, define las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Considera esta etapa como un contrato entre las entradas y los resultados validados. Nombra los artefactos, define las verificaciones de éxito y rechaza cualquier completación parcial silenciosa. Incluye la aprobación humana en aquellos casos que impliquen gastos o cambios en los datos de producción. La conexión durante la compilación no equivale a la completitud del proceso empresarial.
You: Fix the login bug.
Agent: Done.
You: opens browser
You: It still doesn't work.
Agent: Ah. I found the problem.
You: No, that's not it.
Agent: You're right. I found the REAL problem.
You: sends screenshot
Agent: Ah...
1. Proporciona al agente una sola orden para indicar que está “listo”
En la fase 1 de asignación al agente, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Implemente la aprobación humana en aquellos casos en que se gasten fondos o se modifiquen datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
scripts/verify.sh
#!/usr/bin/env bash
set -euo pipefail
echo "== Python lint =="
uv run ruff check backend
echo "== Python types =="
uv run mypy backend
echo "== Python tests =="
uv run pytest -q
echo "== Frontend lint =="
npm --prefix frontend run lint
echo "== Frontend tests =="
npm --prefix frontend test -- --run
echo "Verification passed."
#!/usr/bin/env bash
set -euo pipefail
echo "== Python lint =="
python -m ruff check backend
echo "== Python types =="
python -m mypy backend
echo "== Python tests =="
python -m pytest -q
echo "== Frontend lint =="
npm --prefix frontend run lint
echo "== Frontend tests =="
npm --prefix frontend test -- --run
echo "Verification passed."
chmod +x scripts/verify.sh
verify:
./scripts/verify.sh
make verify
inspect
↓
change code
↓
verify
↓
failure
↓
inspect
↓
change code
↓
verify
2. En el caso de errores, exija pruebas antes de aplicar la corrección
En la fase de corrección de errores de 2 For, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Coloque la aprobación humana en aquellos procesos que implican gastos o modifican datos de producción. La conexión realizada en tiempo de compilación no equivale a una solución completa desde el punto de vista empresarial. En la fase de corrección de errores de 2 For, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado.
def parse_timeout(value: str) -> float:
if value.endswith("s"):
return float(value[:-1])
if value.endswith("m"):
return float(value[:-1]) * 60
return float(value)
250ms is interpreted incorrectly.
def test_parse_timeout_milliseconds():
assert parse_timeout("250ms") == 0.25
uv run pytest tests/test_timeout.py -q
python -m pytest tests/test_timeout.py -q
def parse_timeout(value: str) -> float:
if value.endswith("ms"):
return float(value[:-2]) / 1000
if value.endswith("s"):
return float(value[:-1])
if value.endswith("m"):
return float(value[:-1]) * 60
return float(value)
reported bug
↓
observed failure
↓
code change
↓
observed success
3. Proporcionar al agente un manual de incorporación
Al trabajar en la fase 3 de Proporcionar al agente, anote primero el contrato: los datos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener la transparencia en los cambios posteriores del código. Considere esta fase como un contrato entre las entradas y las salidas validadas. Asigne nombres a los elementos, defina comprobaciones de éxito y evite completaciones parciales silenciosas. Haga una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior.
# Project
FastAPI backend + React frontend.
Python dependencies are managed with uv.
## Important directories
backend/app/api/ HTTP endpoints
backend/app/services/ business logic
frontend/src/features/ feature code
tests/ backend tests
## Commands
Fast Python tests:
uv run pytest -q tests/unit
Full verification:
make verify
Development:
make dev
## Working rules
Before editing:
1. Reproduce the problem.
2. Inspect the implementation involved.
3. Find similar existing code before creating a new pattern.
4. Identify or add a test.
Before completion:
1. Run relevant tests.
2. Run `make verify`.
3. Inspect `git diff`.
4. Report exactly what was verified.
Fast Python tests:
python -m pytest -q tests/unit
4. Convertir las lecciones recurrentes en habilidades
Al trabajar en la fase de las lecciones recurrentes de 4 turnos, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo de tokens o consultas junto a los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Haga una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
skills/debug-with-evidence/SKILL.md
# Debug with evidence
Before modifying production code:
1. Capture the exact symptom.
2. Reproduce it.
3. Find the narrowest failing case.
4. Inspect the code actually executed.
5. Form hypotheses only after gathering evidence.
6. Prefer experiments that distinguish competing explanations.
7. Add a regression test when practical.
8. Make the smallest justified fix.
9. Rerun the reproduction.
10. Run full verification.
For Python projects managed by uv, run Python tools with `uv run`.
Report:
- observed failure
- root cause
- evidence
- files changed
- verification performed
#!/usr/bin/env bash
set -euo pipefail
echo "=== STATUS ==="
git status --short
echo
echo "=== RECENT COMMITS ==="
git log --oneline -10
echo
echo "=== DIFF ==="
git diff --stat
echo
echo "=== TESTS ==="
uv run pytest -q --tb=short
python -m pytest -q --tb=short
if rg 'app\.database' frontend/src
then
echo "Frontend may not import app.database"
exit 1
fi
"Don't import X here."
→ dependency check
"Every endpoint needs authorization."
→ middleware + test
"Don't forget to regenerate the schema."
→ CI check
"Every bug fix needs a regression test."
→ workflow rule
"Don't modify generated files."
→ generated-file check
uv run ruff check .
uv run mypy .
uv run pytest
python -m ruff check .
python -m mypy .
python -m pytest
6. Hacer que la solución más sencilla sea la correcta
Al trabajar en la etapa de “Hacerlo lo más sencillo” de las 6, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un único lugar que los operadores puedan auditar sin tener que leer todo el sistema. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior. Al trabajar en la etapa de “Hacerlo lo más sencillo” de las 6, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Prefiera unidades pequeñas y probables a scripts extensos. Cuando un paso falla, el fallo debe indicar una única responsabilidad y no un proceso complicado.
components/
services/
hooks/
types/
validation/
screens/
features/
├── billing/
│ ├── api.ts
│ ├── model.ts
│ ├── BillingPage.tsx
│ └── BillingPage.test.tsx
│
└── login/
├── api.ts
├── model.ts
├── LoginPage.tsx
└── LoginPage.test.tsx
7. Utilice un agente nuevo como revisor
La etapa 7 “Utilice un agente nuevo” funciona mejor cuando se trata como una métrica cuantificable. Capture una transcripción exitosa, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Mantenga el estado del grafo simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
Agent A
↓
implements
↓
Agent B
↓
reviews from fresh context
Check:
1. Does the change actually satisfy the task?
2. Can you reproduce the original bug?
3. Are edge cases missing?
4. Were tests weakened?
5. Is there unnecessary complexity?
6. Are architectural boundaries violated?
7. Is existing functionality duplicated?
8. Do the tests verify behavior?
For Python changes, run the relevant checks yourself:
uv run ruff check .
uv run mypy .
uv run pytest
python -m ruff check .
python -m mypy .
python -m pytest
confirmed defect
plausible concern
stylistic preference
8. Paralice el trabajo con estructuras organizadas, no con caos
La etapa de 8 Parallelize with worktrees funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos. Mantenga el estado del grafo simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
git worktree add ../app-auth -b agent/auth
git worktree add ../app-search -b agent/search
git worktree add ../app-billing -b agent/billing
app-auth/
app-search/
app-billing/
uv sync
uv run pytest
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m pytest
Agent 1: investigate authentication bug
Agent 2: implement CSV export
Agent 3: profile search performance
Agent 1: refactor authentication
Agent 2: refactor authentication differently
Agent 3: rename files both others are editing
9. Trate cada corrección realizada por un humano como datos
El principio de “Trata cada etapa humana como una superficie medible” funciona mejor cuando se aborda de esta manera. Registra un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantén la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Mantén el estado del sistema plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en el proceso posterior. El principio de “Trata cada etapa humana como una superficie medible” funciona mejor cuando se aborda de esta manera. Registra un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiere unidades pequeñas y verificables en lugar de scripts extensos. Cuando falla un paso, el error debe apuntar a una sola responsabilidad y no a un proceso complicado.
Agent lacked project knowledge?
→ improve AGENTS.md
Agent didn't know the procedure?
→ create a Skill
Bug escaped?
→ regression test
Same architectural mistake again?
→ CI/static rule
Task was ambiguous?
→ improve task template
Agent trusted its own solution too easily?
→ independent reviewer
agent makes mistake
↓
human understands why
↓
lesson becomes process
↓
process becomes Skill/test/CI
↓
future agent avoids whole category of mistake
La configuración que deberías crear primero
Para la configuración que se implementará, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Incluya la aprobación humana en aquellos casos en los que se gastan fondos o se modifican datos de producción. La conexión durante la compilación no equivale a la completitud del proceso empresarial.
pyproject.toml
uv.lock
AGENTS.md
Makefile
scripts/verify.sh
skills/debug-with-evidence/SKILL.md
skills/review-change/SKILL.md
uv init
uv sync
uv add --dev pytest ruff mypy
uv run pytest
uv run ruff check .
uv run mypy .
pip install pytest ruff mypy
python -m pytest
python -m ruff check .
python -m mypy .
1. Investigate.
2. Reproduce.
3. Write failing test.
4. Implement smallest fix.
5. Run fast tests.
6. Run full verification.
7. Fresh agent reviews diff.
8. Human corrections become permanent rules.
Own this task end to end.
Before editing:
- inspect the relevant implementation,
- reproduce the problem,
- examine similar existing code.
During implementation:
- make the smallest coherent change,
- add or update tests,
- use `uv run` for Python tools,
- verify while iterating.
Before completion:
- run full verification,
- inspect the final diff,
- independently check the original requirement.
Report what changed, what was verified,
and any remaining uncertainty.
La idea general
En la fase de la idea general, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos. Implemente la aprobación humana en aquellos casos en que se gasten fondos o se modifiquen datos de producción. La conexión durante la compilación no equivale a una solución completa desde el punto de vista empresarial.
prompt → code
requirement
↓
agent
↓
code
↓
execution
↓
verification
↓
review
↓
feedback
↓
better Skills / tests / architecture
↺
uv run pytest tests/test_bug.py -q
uv run ruff check .
uv run mypy .
make verify
python -m pytest tests/test_bug.py -q
python -m ruff check .
python -m mypy .
make verify
Lista de verificación operativa
Al trabajar en la fase de la lista de verificación operativa, primero escriba el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista garantiza que los cambios posteriores en el código se realicen de manera transparente.
Dokumente tanto el camino óptimo como el de recuperación. Los intentos repetidos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores.
Haga un punto de control después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior.
Fije las versiones de las dependencias y registre el resumen de la imagen que ejecutó la demostración. La reproducibilidad es mejor que el conocimiento basado en prácticas internas.
Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe apuntar a una única responsabilidad y no a un proceso complicado.
Haga un punto de control después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior.
Antes de promocionar el stack, congele las versiones, capture una transcripción de referencia para la ruta crítica y confirme los pasos de reversión. Los entornos compartidos requieren límites de velocidad, verificaciones de tenencia y un responsable claro para la rotación de secretos. Prefiera una fiabilidad sólida a demostraciones ingeniosas pero puntuales.
Nota para 780e678b0ae3: mantenga las claves del proveedor fuera del repositorio, establezca un límite para tokens por sesión y almacene las transcripciones junto a los fixtures de evaluación para que los cambios posteriores en el modelo sigan siendo comparables.
Lecturas relacionadas
- Notas prácticas: IA agente en la práctica: Un estudio de caso en sistemas multi-agente — Guía detallada de Notas prácticas: IA agente en la práctica: Un estudio de caso en sistemas multi-agente: contratos, verificaciones y espacios para código listo para usar para los equipos que implementan este patrón.