Context Engineering

1. Objetivos de la semana

2. ¿Qué es Context Engineering?

Cuando hablamos de trabajar con IA solemos hablar mucho de prompt engineering. Pero para desarrollar software de forma profesional el problema es mucho más grande.

Prompt

↓

Respuesta

Objetivo
+
Reglas
+
Repositorio
+
Arquitectura
+
Documentación
+
Estado actual
+
Herramientas
+
Historial
+
Restricciones

↓

Agente

↓

Decisión / Acción

Ejemplo

Imagina que dices:

Implementa el login.

El agente tiene que tomar muchas decisiones:

• ¿Qué framework?
• ¿Qué arquitectura?
• ¿Qué sistema de autenticación?
• ¿Dónde están los usuarios?
• ¿Cómo se almacenan las contraseñas?
• ¿Qué API existe?
• ¿Qué diseño utiliza la aplicación?
• ¿Qué tests existen?
• ¿Qué convenciones utiliza el proyecto?

Ahora imagina que el repositorio contiene:

README.md

AGENTS.md

docs/
    architecture.md
    security.md
    database.md
    api.md

src/

tests/

.env.example

La IA tiene mucha más información para tomar decisiones coherentes.

3. Cómo trabaja realmente un agente

Un agente moderno no es simplemente un chatbot que escribe código. Puede:

• Leer archivos.
• Buscar información.
• Analizar código.
• Crear archivos.
• Modificar archivos.
• Ejecutar comandos.
• Ejecutar tests.
• Analizar errores.
• Iterar.
• Utilizar herramientas.

Ciclo básico

1. OBJETIVO

      ↓

2. OBSERVAR

Leer proyecto y contexto.

      ↓

3. RAZONAR

Determinar qué debe hacerse.

      ↓

4. PLANIFICAR

Crear plan de implementación.

      ↓

5. ACTUAR

Modificar archivos.

      ↓

6. VALIDAR

Ejecutar tests / comprobar resultado.

      ↓

7. CORREGIR

Resolver errores.

      ↓

8. REPETIR

4. ¿Qué es un repositorio AI-Ready?

Un repositorio AI-Ready está organizado de forma que un agente pueda comprender rápidamente:

• qué es el proyecto;
• cómo está organizado;
• qué reglas debe seguir;
• cómo ejecutar el proyecto;
• cómo ejecutar tests;
• qué arquitectura utiliza;
• qué decisiones se han tomado;
• qué restricciones existen.

Arquitectura documental recomendada

my-project/
│
├── README.md
│
├── AGENTS.md
│
├── CONTRIBUTING.md
│
├── CHANGELOG.md
│
├── .env.example
│
├── docs/
│   │
│   ├── product.md
│   ├── architecture.md
│   ├── database.md
│   ├── api.md
│   ├── security.md
│   ├── testing.md
│   ├── decisions/
│   │   ├── ADR-001.md
│   │   └── ADR-002.md
│   │
│   └── requirements/
│       ├── US-001.md
│       └── US-002.md
│
├── src/
│
├── tests/
│
└── scripts/

5. Project Instructions

Las instrucciones del proyecto establecen cómo debe comportarse la IA cuando trabaja en nuestro repositorio.

Ejemplo

# Project Instructions

## General

Before modifying code:

1. Read the relevant documentation.
2. Inspect existing implementation.
3. Check existing tests.
4. Do not invent architecture.
5. Prefer existing components.

## Code

- Reuse existing utilities.
- Avoid duplicated logic.
- Keep functions focused.
- Do not introduce dependencies without justification.

## Testing

Every new feature must include tests.

Run the relevant tests before finishing.

## Security

Never commit secrets.

Never expose credentials.

Do not disable security controls
to make tests pass.

## Git

Do not create commits unless explicitly requested.

Por qué funciona

Estas instrucciones eliminan decisiones repetitivas. En lugar de decir:

"No hagas commits."

en cada conversación, la regla vive en el repositorio.

6. AGENTS.md

AGENTS.md se ha convertido en una convención muy útil para proporcionar instrucciones a agentes que trabajan sobre un repositorio.

Ejemplo completo

# AGENTS.md

## Project Overview

This project is a web application for
managing employee availability.

## Architecture

The project uses:

- frontend application;
- backend API;
- PostgreSQL database.

See:

docs/architecture.md

## Before Making Changes

Always:

1. Read the relevant documentation.
2. Inspect related code.
3. Search for existing functionality.
4. Check tests.
5. Propose a plan for complex changes.

## Development Rules

Do not:

- rewrite existing components without reason;
- introduce unnecessary dependencies;
- duplicate existing services;
- modify unrelated files.

## Database

Database changes must include:

- migration;
- updated documentation;
- tests where appropriate.

## API

API changes must update:

docs/api.md

## Testing

Before finishing:

- run unit tests;
- run integration tests when relevant;
- verify no existing functionality is broken.

## Security

Never:

- commit secrets;
- expose environment variables;
- disable authentication;
- bypass authorization.

## Communication

If a requirement is ambiguous:

STOP.

Ask for clarification.

Do not silently invent business rules.

7. Reglas específicas

No todas las reglas tienen que aplicarse a todo el repositorio. Podemos tener reglas específicas para determinadas áreas.

Ejemplo conceptual

rules/
│
├── general.md
├── frontend.md
├── backend.md
├── database.md
└── testing.md

Reglas frontend

# Frontend Rules

- Reuse existing UI components.
- Do not introduce a new design system.
- Keep accessibility in mind.
- Forms must expose validation errors.
- Do not duplicate API clients.

Reglas backend

# Backend Rules

- Validate input at the API boundary.
- Never trust client input.
- Return consistent error structures.
- Business logic belongs in services.
- Database access must remain isolated.

Reglas database

# Database Rules

- All schema changes require migrations.
- Never manually modify production schema.
- Foreign keys must be explicit.
- Avoid destructive migrations without a migration plan.

general.md

"Always use service classes."


frontend.md

"Never use service classes."

8. Contexto de arquitectura

Una IA puede leer el código, pero eso no significa que entienda automáticamente por qué está construido así.

Architecture.md

# Architecture

## Overview

The application follows a layered architecture.

Frontend
    ↓
API
    ↓
Application Services
    ↓
Repositories
    ↓
PostgreSQL


## Frontend

Responsible for:

- presentation;
- user interaction;
- client-side validation.

## API

Responsible for:

- authentication;
- authorization;
- request validation;
- HTTP responses.

## Services

Responsible for:

- business rules;
- workflows;
- orchestration.

## Repositories

Responsible for:

- persistence;
- database queries.

## Important Rule

Business rules must not be implemented
directly inside controllers.

¿Qué conseguimos?

Si el agente tiene que implementar:

"Crear una nueva solicitud"

9. Memoria del proyecto

No toda la información debe vivir en el mismo sitio. Podemos distinguir:

ADRs

Un ADR (Architecture Decision Record) documenta decisiones arquitectónicas importantes.

# ADR-001

## Title

Use PostgreSQL as primary database.

## Status

Accepted.

## Context

The application requires relational
data and transactional consistency.

## Decision

PostgreSQL will be the primary database.

## Alternatives

- MySQL
- MongoDB

## Consequences

We benefit from:

- relational integrity;
- transactions;
- mature tooling.

We accept:

- relational schema management;
- migrations.

"¿Por qué usamos PostgreSQL?"

10. MCP — Model Context Protocol

MCP es un protocolo abierto que permite conectar aplicaciones de IA con herramientas y fuentes externas de información de una forma estandarizada.

La idea

                  ┌──────────────┐
                  │     AGENT    │
                  └──────┬───────┘
                         │
                         │ MCP
          ┌──────────────┼───────────────┐
          │              │               │
          ▼              ▼               ▼
       Database        Files          APIs
          │              │               │
          ▼              ▼               ▼
      PostgreSQL      GitHub         External Tool

Conceptos que debes conocer

• MCP Client
• MCP Server
• Tools
• Resources
• Prompts

Ejemplo conceptual

En lugar de copiar manualmente información desde una herramienta a un chat:

IA
 ↓
MCP Server
 ↓
Sistema externo
 ↓
Resultado
 ↓
IA

11. Workflow profesional AI-Native

12. Anti-patterns

"La IA puede leer el código."

13. El principio de Single Source of Truth

Cada tipo de información debería tener un lugar claramente definido.

14. Proyecto práctico de la semana

Proyecto

Construye una pequeña aplicación de gestión de empleados y disponibilidad. No importa demasiado el lenguaje. La arquitectura y el contexto sí importan.

Fase 1 — Crear estructura

employee-management/
│
├── README.md
├── AGENTS.md
├── CONTRIBUTING.md
├── .env.example
│
├── docs/
│   ├── product.md
│   ├── architecture.md
│   ├── database.md
│   ├── api.md
│   ├── security.md
│   ├── testing.md
│   │
│   ├── requirements/
│   │   ├── US-001.md
│   │   └── US-002.md
│   │
│   └── decisions/
│       └── ADR-001.md
│
├── src/
├── tests/
└── scripts/

Fase 2 — README

• Qué hace el proyecto.
• Cómo instalarlo.
• Cómo ejecutarlo.
• Cómo ejecutar tests.
• Estructura principal.
• Documentación.

Fase 3 — AGENTS.md

• Descripción.
• Arquitectura.
• Reglas.
• Testing.
• Seguridad.
• Git.
• Cómo actuar ante ambigüedad.

Fase 4 — Architecture

Frontend
   ↓
API
   ↓
Services
   ↓
Repositories
   ↓
Database

Fase 5 — Requirements

US-001 — Crear empleado

US-002 — Consultar empleado

US-003 — Marcar disponibilidad

US-004 — Cambiar disponibilidad

Fase 6 — Security

• Autenticación.
• Autorización.
• Gestión de secretos.
• Validación de inputs.
• Protección de datos.

Fase 7 — Pedir a la IA una auditoría

Actúa como AI Architecture Auditor.

Analiza este repositorio.

Quiero que compruebes:

1. Si la documentación es suficiente.
2. Si existen contradicciones.
3. Si falta información importante.
4. Si las instrucciones para agentes son claras.
5. Si la arquitectura está documentada.
6. Si los requisitos son trazables.
7. Si existen riesgos de seguridad.
8. Si la estructura facilita trabajar con agentes.

No modifiques ningún archivo.

Devuelve:

- problemas críticos;
- problemas importantes;
- mejoras;
- recomendaciones.

Para cada problema indica
qué archivo deberíamos modificar.

15. Ejercicios prácticos

README.md

src/

tests/

AGENTS.md

"Always create a new component
when implementing a feature."

docs/frontend.md

"Always reuse existing components
when possible."

50.000 líneas de código

+

todos los logs

+

toda la documentación

+

todos los commits

Do not introduce a new dependency
unless:

1. Existing functionality cannot satisfy
the requirement.

2. The dependency provides significant value.

3. The reason is documented.

4. Security and maintenance implications
have been considered.

PostgreSQL
MongoDB

Actúa como Documentation Auditor.

Compara:

- documentación;
- arquitectura;
- código;
- tests.

Busca contradicciones.

No modifiques archivos.

Devuelve:

Archivo
Problema
Evidencia
Severidad
Recomendación

16. Reto avanzado

Test de incorporación

Una vez creado el repositorio, abre una nueva sesión con tu agente y dile solamente:

Familiarízate con este proyecto.

No modifiques ningún archivo.

Explícame:

1. Qué hace.
2. Cómo está estructurado.
3. Qué arquitectura utiliza.
4. Qué reglas debes seguir.
5. Cómo ejecutar tests.
6. Qué decisiones importantes existen.
7. Qué información falta.

Después compara la respuesta con lo que realmente sabes del proyecto.

17. Test de evaluación

18. Recursos externos

19. Checklist de la semana

20. Métrica de aprendizaje

21. Conclusión

ANTES

Usuario
   ↓
Prompt
   ↓
IA
   ↓
Código


AHORA

Usuario
   ↓
Specification
   ↓
Context
   ↓
Rules
   ↓
Architecture
   ↓
Repository
   ↓
Agent
   ↓
Plan
   ↓
Implementation
   ↓
Tests
   ↓
Validation