Punto de partida: la mini app sin arnés

La app que comparten todos los arneses de la serie, tal cual: funciona y tiene pruebas, pero no tiene arnés ni una arquitectura definida.

La idea clave: antes de construir arneses, conviene ver la app sin ninguno. Es la referencia con la que se compara todo lo que viene después, igual que el Setup base en la ruta de temas.

Qué es la mini app

Piensa en el mostrador de una biblioteca de barrio: das de alta libros y socios, y apuntas quién se lleva qué libro y cuándo lo devuelve. La mini app hace eso mismo, pero como una API REST pequeña.

Está escrita en TypeScript con Node 22 o superior, Express y Vitest. Los datos viven en memoria: no hay base de datos, así que cada vez que arranca empieza vacía.

Petición Qué hace
GET /books Lista los libros
POST /books Da de alta un libro
GET /members Lista los socios
POST /members Da de alta un socio
POST /loans Presta un libro a un socio
POST /loans/:id/return Registra una devolución

Las reglas de negocio

  1. Un libro prestado no se puede volver a prestar hasta que se devuelve.
  2. Un socio tiene como máximo tres préstamos activos.

Si una petición rompe una regla, la app responde con un error y un código claro, como BOOK_ALREADY_LOANED o LOAN_LIMIT_REACHED.

Qué le falta a propósito

Todo el código está en un solo archivo, src/app.ts: las rutas, las reglas y los datos juntos. La app funciona y las pruebas pasan. Lo que falta es lo que ayuda a un agente a trabajar en ella sin romper nada:

  • No hay AGENTS.md. El agente no sabe dónde va cada cosa ni qué comandos debe ejecutar.
  • No hay hooks. Nada le obliga a pasar las pruebas antes de dar una tarea por terminada.
  • No hay permisos. Nada le impide leer un archivo sensible o instalar dependencias sin preguntar.
  • No hay reglas de arquitectura. El código puede crecer de cualquier forma, y nadie lo comprueba.

Cada arnés de la serie añade estas piezas, cada uno con su arquitectura.

El código

Este es el código completo de la app. Elige un archivo para ver su contenido. Los archivos están en inglés, como el código.

import express, { type Express, type Request, type Response, type NextFunction } from 'express';

interface Book {
  id: string;
  title: string;
  author: string;
  available: boolean;
}

interface Member {
  id: string;
  name: string;
}

interface Loan {
  id: string;
  bookId: string;
  memberId: string;
  loanedAt: string;
  returnedAt: string | null;
}

const MAX_ACTIVE_LOANS = 3;

export function createApp(): Express {
  const app = express();
  const books: Book[] = [];
  const members: Member[] = [];
  const loans: Loan[] = [];
  let lastBookId = 0;
  let lastMemberId = 0;
  let lastLoanId = 0;

  app.use(express.json());

  app.get('/books', (_req, res) => {
    res.json(books);
  });

  app.post('/books', (req, res) => {
    const input = readInput(req);
    const title = readText(input.title);
    const author = readText(input.author);
    if (title === null || author === null) {
      return sendError(res, 400, 'INVALID_INPUT', 'Title and author are required.');
    }
    const book: Book = { id: String(++lastBookId), title, author, available: true };
    books.push(book);
    res.status(201).json(book);
  });

  app.get('/books/:id', (req, res) => {
    const book = findById(books, req.params.id);
    if (!book) {
      return sendError(res, 404, 'BOOK_NOT_FOUND', `Book ${req.params.id} does not exist.`);
    }
    res.json(book);
  });

  app.get('/members', (_req, res) => {
    res.json(members);
  });

  app.post('/members', (req, res) => {
    const name = readText(readInput(req).name);
    if (name === null) {
      return sendError(res, 400, 'INVALID_INPUT', 'Name is required.');
    }
    const member: Member = { id: String(++lastMemberId), name };
    members.push(member);
    res.status(201).json(member);
  });

  app.get('/loans', (_req, res) => {
    res.json(loans);
  });

  app.post('/loans', (req, res) => {
    const input = readInput(req);
    const bookId = readText(input.bookId);
    const memberId = readText(input.memberId);
    if (bookId === null || memberId === null) {
      return sendError(res, 400, 'INVALID_INPUT', 'bookId and memberId are required.');
    }

    // The order of these checks is part of the contract: the first failing check wins.
    const book = findById(books, bookId);
    if (!book) {
      return sendError(res, 404, 'BOOK_NOT_FOUND', `Book ${bookId} does not exist.`);
    }
    const member = findById(members, memberId);
    if (!member) {
      return sendError(res, 404, 'MEMBER_NOT_FOUND', `Member ${memberId} does not exist.`);
    }
    if (!book.available) {
      return sendError(res, 409, 'BOOK_ALREADY_LOANED', `Book ${bookId} is already loaned.`);
    }
    const activeLoans = loans.filter(
      (loan) => loan.memberId === member.id && loan.returnedAt === null,
    ).length;
    if (activeLoans >= MAX_ACTIVE_LOANS) {
      return sendError(
        res,
        409,
        'LOAN_LIMIT_REACHED',
        `Member ${memberId} has ${MAX_ACTIVE_LOANS} active loans.`,
      );
    }

    const loan: Loan = {
      id: String(++lastLoanId),
      bookId: book.id,
      memberId: member.id,
      loanedAt: new Date().toISOString(),
      returnedAt: null,
    };
    loans.push(loan);
    book.available = false;
    res.status(201).json(loan);
  });

  app.post('/loans/:id/return', (req, res) => {
    const loan = findById(loans, req.params.id);
    if (!loan) {
      return sendError(res, 404, 'LOAN_NOT_FOUND', `Loan ${req.params.id} does not exist.`);
    }
    if (loan.returnedAt !== null) {
      return sendError(res, 409, 'LOAN_ALREADY_RETURNED', `Loan ${loan.id} was already returned.`);
    }
    loan.returnedAt = new Date().toISOString();
    const book = findById(books, loan.bookId);
    if (book) {
      book.available = true;
    }
    res.json(loan);
  });

  app.use((_req, res) => {
    sendError(res, 404, 'NOT_FOUND', 'Route not found.');
  });

  app.use((err: unknown, _req: Request, res: Response, next: NextFunction) => {
    if (res.headersSent) {
      next(err);
      return;
    }
    if (isMalformedJson(err)) {
      return sendError(res, 400, 'INVALID_INPUT', 'Request body must be valid JSON.');
    }
    console.error(err);
    sendError(res, 500, 'INTERNAL_ERROR', 'Unexpected server error.');
  });

  return app;
}

function sendError(res: Response, status: number, code: string, message: string): void {
  res.status(status).json({ error: { code, message } });
}

function findById<T extends { id: string }>(items: T[], id: string): T | undefined {
  return items.find((item) => item.id === id);
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

function readInput(req: Request): Record<string, unknown> {
  const body: unknown = req.body;
  return isRecord(body) ? body : {};
}

// Returns the trimmed text, or null when the value is not a string or is blank.
function readText(value: unknown): string | null {
  if (typeof value !== 'string') {
    return null;
  }
  const text = value.trim();
  return text === '' ? null : text;
}

function isMalformedJson(err: unknown): boolean {
  return err instanceof Error && 'type' in err && err.type === 'entity.parse.failed';
}
import { createApp } from './app';

const port = Number(process.env.PORT ?? 3000);

createApp().listen(port, () => {
  console.log(`Library API listening on http://localhost:${port}`);
});
import type { Express } from 'express';
import request from 'supertest';
import { describe, expect, it } from 'vitest';
import { createApp } from '../src/app';

async function createBook(app: Express, title = 'Dune'): Promise<string> {
  const res = await request(app).post('/books').send({ title, author: 'Frank Herbert' });
  return (res.body as { id: string }).id;
}

async function createMember(app: Express, name = 'Ana'): Promise<string> {
  const res = await request(app).post('/members').send({ name });
  return (res.body as { id: string }).id;
}

describe('library API', () => {
  it('creates a book and lists it as available', async () => {
    const app = createApp();

    const created = await request(app)
      .post('/books')
      .send({ title: 'Dune', author: 'Frank Herbert' });
    expect(created.status).toBe(201);
    expect(created.body).toMatchObject({ title: 'Dune', author: 'Frank Herbert', available: true });

    const list = await request(app).get('/books');
    expect(list.status).toBe(200);
    expect(list.body).toContainEqual(
      expect.objectContaining({ id: created.body.id, available: true }),
    );
  });

  it('returns 404 BOOK_NOT_FOUND for an unknown book', async () => {
    const app = createApp();

    const res = await request(app).get('/books/does-not-exist');
    expect(res.status).toBe(404);
    expect(res.body.error.code).toBe('BOOK_NOT_FOUND');
  });

  it('rejects a book without a title with 400 INVALID_INPUT', async () => {
    const app = createApp();

    const res = await request(app).post('/books').send({ author: 'Frank Herbert' });
    expect(res.status).toBe(400);
    expect(res.body.error.code).toBe('INVALID_INPUT');
  });

  it('creates a member and lists it', async () => {
    const app = createApp();

    const created = await request(app).post('/members').send({ name: 'Ana' });
    expect(created.status).toBe(201);
    expect(created.body).toMatchObject({ name: 'Ana' });

    const list = await request(app).get('/members');
    expect(list.status).toBe(200);
    expect(list.body).toContainEqual(expect.objectContaining({ id: created.body.id, name: 'Ana' }));
  });

  it('lends an available book, and the book stops being available', async () => {
    const app = createApp();
    const bookId = await createBook(app);
    const memberId = await createMember(app);

    const loan = await request(app).post('/loans').send({ bookId, memberId });
    expect(loan.status).toBe(201);
    expect(loan.body).toMatchObject({ bookId, memberId, returnedAt: null });

    const book = await request(app).get(`/books/${bookId}`);
    expect(book.status).toBe(200);
    expect(book.body.available).toBe(false);
  });

  it('rejects lending a book that is already loaned with 409 BOOK_ALREADY_LOANED', async () => {
    const app = createApp();
    const bookId = await createBook(app);
    const firstMemberId = await createMember(app, 'Ana');
    const secondMemberId = await createMember(app, 'Luis');

    const first = await request(app).post('/loans').send({ bookId, memberId: firstMemberId });
    expect(first.status).toBe(201);

    const second = await request(app).post('/loans').send({ bookId, memberId: secondMemberId });
    expect(second.status).toBe(409);
    expect(second.body.error.code).toBe('BOOK_ALREADY_LOANED');
  });

  it('rejects a fourth active loan for the same member with 409 LOAN_LIMIT_REACHED', async () => {
    const app = createApp();
    const memberId = await createMember(app);

    for (const title of ['Dune', 'Emma', 'Ulysses']) {
      const bookId = await createBook(app, title);
      const loanRes = await request(app).post('/loans').send({ bookId, memberId });
      expect(loanRes.status).toBe(201);
    }

    const bookId = await createBook(app, 'Beloved');
    const res = await request(app).post('/loans').send({ bookId, memberId });
    expect(res.status).toBe(409);
    expect(res.body.error.code).toBe('LOAN_LIMIT_REACHED');

    const book = await request(app).get(`/books/${bookId}`);
    expect(book.body.available).toBe(true);
  });

  it('returning a loan makes the book available again', async () => {
    const app = createApp();
    const bookId = await createBook(app);
    const memberId = await createMember(app);
    const loanRes = await request(app).post('/loans').send({ bookId, memberId });

    const res = await request(app).post(`/loans/${loanRes.body.id}/return`);
    expect(res.status).toBe(200);
    expect(res.body).toMatchObject({ id: loanRes.body.id, bookId, memberId });
    expect(res.body.returnedAt).toEqual(expect.any(String));

    const book = await request(app).get(`/books/${bookId}`);
    expect(book.body.available).toBe(true);
  });

  it('rejects returning the same loan twice with 409 LOAN_ALREADY_RETURNED', async () => {
    const app = createApp();
    const bookId = await createBook(app);
    const memberId = await createMember(app);
    const loanRes = await request(app).post('/loans').send({ bookId, memberId });
    const loanPath = `/loans/${loanRes.body.id}/return`;

    const first = await request(app).post(loanPath);
    expect(first.status).toBe(200);

    const second = await request(app).post(loanPath);
    expect(second.status).toBe(409);
    expect(second.body.error.code).toBe('LOAN_ALREADY_RETURNED');
  });

  it('rejects a loan for an unknown member with 404 MEMBER_NOT_FOUND', async () => {
    const app = createApp();
    const bookId = await createBook(app);

    const res = await request(app).post('/loans').send({ bookId, memberId: 'does-not-exist' });
    expect(res.status).toBe(404);
    expect(res.body.error.code).toBe('MEMBER_NOT_FOUND');
  });

  it('rejects malformed JSON with 400 INVALID_INPUT', async () => {
    const app = createApp();

    const res = await request(app)
      .post('/books')
      .set('Content-Type', 'application/json')
      .send('{"title": "Dune"');
    expect(res.status).toBe(400);
    expect(res.body.error.code).toBe('INVALID_INPUT');
  });
});
node_modules/
{
  "name": "library-starting-point",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=22"
  },
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "start": "tsx src/server.ts",
    "test": "vitest run",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "express": "5.3.0"
  },
  "devDependencies": {
    "@types/express": "5.0.6",
    "@types/node": "22.20.5",
    "@types/supertest": "7.2.1",
    "supertest": "7.3.1",
    "tsx": "4.23.15",
    "typescript": "5.9.3",
    "vitest": "5.0.4"
  }
}
# Library starting point

A small library REST API: books, members and loans. This is the starting point of the Agent Atlas harness series: the app works, but it has no harness and no defined architecture.

## Run it

```bash
npm install
npm test
npm run dev
```

The server listens on port 3000. Set `PORT` to use another port.

## Endpoints

| Method | Path                | What it does                                          |
| ------ | ------------------- | ----------------------------------------------------- |
| GET    | `/books`            | List all books                                        |
| POST   | `/books`            | Add a book. Body: `{ title, author }`                 |
| GET    | `/books/:id`        | Get one book                                          |
| GET    | `/members`          | List all members                                      |
| POST   | `/members`          | Add a member. Body: `{ name }`                        |
| GET    | `/loans`            | List all loans                                        |
| POST   | `/loans`            | Lend a book to a member. Body: `{ bookId, memberId }` |
| POST   | `/loans/:id/return` | Return a loan                                         |

## Business rules

1. A book with an active loan cannot be loaned again until it is returned.
2. A member can have at most 3 active loans.

## What is missing on purpose

- No `AGENTS.md` or other agent instructions.
- No hooks.
- No permission rules.
- No architecture rules or linters.
- The only checks are the TypeScript compiler (`npm run typecheck`) and the test suite (`npm test`).

The full contract (entities, status codes, error codes and acceptance tests) is in [`../MINI_APP_SPEC.md`](../MINI_APP_SPEC.md).
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "noEmit": true,
    "types": ["node"],
    "skipLibCheck": true,
    "noUncheckedIndexedAccess": true,
    "verbatimModuleSyntax": true
  },
  "include": ["src", "test"]
}

Cómo usarlo

Puedes ejecutarla en el navegador o en tu equipo.

En el navegador, el botón Ejecutar en el navegador abre la app en StackBlitz, en una pestaña nueva, instala las dependencias y pasa las pruebas sin que copies ningún archivo. Necesita JavaScript.

En tu equipo, copia los archivos en una carpeta y ejecuta:

npm install
npm test
npm run dev

npm test pasa las pruebas y npm run dev arranca la API en http://localhost:3000.

Las pruebas, el contrato entre arneses

El archivo test/library.test.ts tiene once pruebas de aceptación. Hablan con la app solo por HTTP: crean libros y socios, prestan, devuelven y comprueban los errores. No miran cómo está organizado el código por dentro.

Por eso el mismo archivo sirve para cualquier arquitectura. Todos los arneses de la serie tienen que pasar estas pruebas sin cambiarlas. Si un arnés las pasa, la app hace lo mismo que aquí; lo que cambia es cómo está organizada y qué ayuda recibe el agente.

Qué se comprueba hoy

Aquí no hay ningún hook, así que nada se ejecuta solo. Las únicas comprobaciones son las que alguien lance a mano: las pruebas (npm test) y el chequeo de tipos (npm run typecheck).

El 12 de octubre de 2026 instalé las dependencias y pasé las dos comprobaciones con Node 24: las once pruebas pasaron y el chequeo de tipos no dio errores.

El 13 de octubre de 2026 probé también el botón Ejecutar en el navegador en Chromium: StackBlitz instaló 137 paquetes y las once pruebas pasaron unos 30 segundos después del clic. No lo probé en Firefox ni en Safari.

Limitaciones

  • Es una app pequeña a propósito. Sirve para comparar arneses, no para medir cómo trabaja un agente en un proyecto grande.
  • Los datos en memoria simplifican el ejemplo, pero dejan fuera problemas reales como las migraciones o la concurrencia.
  • Esta página no compara agentes ni modelos: solo presenta la base sobre la que se construyen los arneses.

Siguiente paso

El primer arnés, el Arnés por capas, organiza esta misma app por capas y añade instrucciones, hooks y permisos. Para elegir entre los cuatro arneses de la serie, la guía Cómo elegir un arnés los compara. Puedes ver el calendario completo en Arneses por arquitectura.

Fuentes

Consultadas el 12 de octubre de 2026:

  • AGENTS.md: instrucciones persistentes para un proyectoTécnica

    Un archivo Markdown en la raíz del repositorio que explica al agente cómo funciona tu proyecto: comandos, convenciones y cómo comprobar los cambios. Es una guía, no un mecanismo de control.

    Publicado
  • Verificación y evaluaciónTécnica

    Cómo comprobar que el agente hizo bien el trabajo sin fiarte de su palabra: darle formas de verificarse a sí mismo, revisar el resultado y el proceso, y comparar configuraciones con honestidad.

    Publicado
  • Hooks: comprobaciones que se ejecutan solasTécnica

    Comandos que se ejecutan automáticamente en momentos concretos del trabajo del agente, como antes de editar un archivo o al terminar, para que los pasos importantes no dependan de que el agente se acuerde.

    Publicado