Pieza: código limpio

Un detector de código duplicado que avisa sin bloquear, siete reglas cortas para el AGENTS.md y una skill de revisión. Separa lo que se puede automatizar del código limpio de lo que sigue necesitando criterio.

Antes de empezar

  • Pieza: calidadArnés

    Dos hooks y unas reglas de ESLint que mantienen el formato, el lint, los tipos y las pruebas en verde sin pedírselo al agente. Sale del arnés por capas y sirve para cualquier arnés de la serie.

    Publicado

La idea clave: una parte del código limpio se puede automatizar y otra no. Una herramienta, jscpd, encuentra código copiado, y un hook se lo enseña al agente como un aviso, no como un bloqueo. Lo que ninguna herramienta mide bien, como los nombres o qué hace cada función, va en siete reglas cortas del AGENTS.md y en una skill de revisión que el agente sigue antes de entregar.

Qué problema evita

Un agente escribe código deprisa, y con la prisa aparecen tres costumbres:

  • Reescribir lo que ya existe. El agente no ha leído todo el proyecto, así que escribe una segunda versión de una función que ya estaba en otro archivo. Funciona, pero ahora la misma regla vive en dos sitios, y un cambio futuro puede llegar solo a uno.
  • Copiar y pegar. Para una funcionalidad parecida a otra, copia el bloque entero y cambia un par de cosas.
  • Unir lo que solo se parece. Es el error contrario. El agente ve dos bloques parecidos y los junta en una función con un parámetro para distinguir los casos. Esa función acaba siendo más difícil de entender que las dos copias.

El principio DRY («no te repitas») se suele leer como «no repitas texto», pero habla de conocimiento. En una entrevista con Artima, Dave Thomas, uno de los autores de The Pragmatic Programmer, explica que cada regla del sistema debería tener un único sitio donde vive. Dos bloques iguales que representan reglas distintas no rompen DRY. Y Sandi Metz, en «The Wrong Abstraction», defiende que duplicar sale mucho más barato que una abstracción equivocada.

Piensa en un detector de metales en la playa. Pita con cualquier objeto de metal, sea un anillo o una chapa. Decidir si vale la pena cavar es cosa tuya. jscpd es ese detector: encuentra las copias, pero no sabe cuáles importan. Por eso esta pieza avisa y no bloquea, y deja el resto a unas reglas cortas y a una revisión.

Qué archivos añade

Parte Archivos Qué hace
Detector de duplicados .jscpd.json y el script check:duplicates Ejecuta jscpd sobre las carpetas que nombra el script. Informa de las copias de al menos 5 líneas y 50 tokens, y nunca falla.
Aviso al terminar .agents/hooks/report-duplicates-before-stop.mjs Cuando el agente intenta terminar, ejecuta jscpd sobre las carpetas del script check:duplicates y avisa de cada duplicado nuevo una sola vez, con código 2. Si el agente vuelve a intentarlo, le deja.
Revisión antes de entregar .agents/skills/clean-code-review/SKILL.md Los pasos que sigue el agente antes de decir que ha terminado: duplicados, nombres, responsabilidades y alcance del cambio.
Instrucciones La sección Clean code de AGENTS.md Siete reglas, a propósito pocas.
Pruebas test/ Ejecutan el hook como lo hace un agente, sobre proyectos falsos pequeños, y comprueban qué avisa y con qué código termina.

Un hook es un comando que la herramienta del agente ejecuta sola en un momento concreto; lo explica el tema sobre Hooks. Una skill es un procedimiento que el agente carga solo cuando lo necesita; lo explica el tema sobre Skills.

Por qué es un aviso y no un bloqueo

jscpd cuenta tokens (las palabras, símbolos y números del código) y busca secuencias repetidas. No sabe si dos copias representan la misma regla. Si el hook bloqueara, el agente solo podría terminar uniendo las copias, también cuando unirlas es peor.

El problema es que un hook de parada solo sabe dos cosas: dejar terminar al agente o devolverlo al trabajo. Busqué en la documentación de Claude Code, Codex y Cursor una forma de dejar un mensaje al agente sin devolverlo al trabajo, y no encontré ninguna. En Claude Code, el campo additionalContext del hook de parada da información sin marcarla como error, pero la conversación también continúa. Codex y Cursor solo describen bloquear o enviar un mensaje de seguimiento.

Así que el hook devuelve al agente una vez por duplicado:

  • La primera vez que encuentra un duplicado, escribe la lista en stderr y termina con código 2. El agente sigue trabajando y decide qué hacer con cada copia.
  • Si el agente decide dejar la copia e intenta terminar otra vez, el hook le deja: ese duplicado ya se avisó.
  • Recuerda los duplicados avisados en node_modules/.cache/report-duplicates/reported.json, la carpeta de caché habitual de las herramientas de Node, que git ya ignora. Los identifica por sus dos archivos y su código, no por los números de línea, así que una línea añadida encima no lo convierte en nuevo.
  • Solo recuerda los duplicados que siguen existiendo. Si uno desaparece y vuelve, avisa otra vez. Para ver todos los avisos de nuevo, borra esa carpeta.
  • Si jscpd no se puede ejecutar, por ejemplo porque falta instalarlo o porque el script check:duplicates no empieza por jscpd, el hook también termina con código 2: una comprobación que no se ejecuta no debe pasar en silencio.

jscpd tiene opciones para fallar, threshold (un porcentaje máximo de código duplicado) y exitCode. Sirven en integración continua, pero la pieza no las usa.

Cómo trabaja jscpd

  • Parte el código en tokens y busca secuencias repetidas de al menos 50 tokens y 5 líneas, sus valores por defecto. En su modo normal ignora los espacios y los saltos de línea, así que una copia reformateada también cuenta.
  • Compara tokens, así que no ve la misma lógica escrita con otros nombres. La regla 1 y la skill piden al agente buscarla.
  • La pieza usa jscpd 4.3.0. Desde la versión 5, jscpd tiene un motor en Rust y ejecuta un binario nativo para cada sistema, que no puede ejecutarse en StackBlitz, donde la serie pasa las pruebas en el navegador. Lo comprobé en el código de su lanzador: no tiene alternativa en JavaScript. Es la misma razón por la que el día 3 elegí secretlint en lugar de gitleaks.
  • npm audit muestra 5 avisos de gravedad alta después de instalar jscpd 4. Todos vienen de un mismo fallo de braces, una dependencia que llega a través de fast-glob, publicado el 18 de septiembre de 2026 y sin versión corregida. Un patrón de llaves muy anidado puede tumbar el proceso. Aquí los patrones salen de tu package.json y de tu .jscpd.json, no de nadie de fuera.
  • Las carpetas que revisa van en el script (jscpd src), no en .jscpd.json. En Windows, con la carpeta escrita en el archivo de configuración, jscpd 4.3.0 no encontró ningún archivo: convierte la ruta en absoluta y luego no la reconoce. Con la carpeta en el comando funciona. El hook lee las carpetas de ese mismo script y arranca jscpd con node, sin pasar por npm, que sumaba unos 0,7 segundos a cada ejecución.

En el arnés por capas, el script revisa solo src/. Pasé jscpd por el arnés completo para ver qué pasaba: encontró 7 duplicados, 4 entre los scripts de los hooks y 3 en las pruebas. Los de los hooks son a propósito: cada pieza trae su propia copia del código que ejecuta npm y recoge los errores, para que funcione sola. Son un buen ejemplo de duplicado que conviene dejar.

Las siete reglas del AGENTS.md

¿Cuántas reglas caben en un AGENTS.md sin saturarlo? Ninguna documentación da un número de reglas, pero todas apuntan en la misma dirección:

  • La documentación de Claude Code recomienda archivos de menos de 200 líneas. Dice que un archivo demasiado largo hace que el agente ignore parte de las instrucciones, y que no merece la pena escribir prácticas obvias como «escribe código limpio».
  • La de Codex dice que un AGENTS.md corto y preciso sirve más que uno largo lleno de reglas vagas, y que, por defecto, Codex deja de leer las instrucciones cuando juntas pasan de 32 KiB.
  • La de Cursor recomienda reglas de menos de 500 líneas y empezar con pocas.
  • Un estudio de 2025, «How Many Instructions Can LLMs Follow at Once?», midió que los modelos cumplen menos instrucciones a medida que reciben más, y que cumplen mejor las primeras. Su tarea era sintética (escribir informes con palabras obligatorias), así que solo es una pista.

Por eso la sección tiene siete reglas, cada una concreta y comprobable al leer el código:

Regla Por qué está
1. Busca una función que ya haga el trabajo antes de escribir una nueva Es la forma de duplicar que jscpd no ve: la misma lógica escrita otra vez con otros nombres.
2. Usa las palabras del dominio y evita nombres vagos Ninguna herramienta sabe si data o handle dicen algo. Unos ejemplos concretos (book, member, loan) se entienden mejor que «usa buenos nombres».
3. Una función hace una cosa La prueba del «y»: si necesitas «y» para describirla, se parte. El tamaño ya lo mide ESLint en la pieza de calidad; esto mide otra cosa.
4. No unas lo que solo se parece Contrapeso a DRY: extrae una función común cuando las copias tienen la misma regla y cambiarían juntas. Si esa función necesitaría un parámetro para saber quién la llama, deja las copias.
5. Escribe solo lo que pide la tarea La guía de prompts de Anthropic avisa de que algunos de sus modelos tienden a sobrediseñar: archivos de más, abstracciones innecesarias o flexibilidad que nadie pidió.
6. El aviso de duplicados Explica qué hace el hook, que es un aviso y qué no puede tocar el agente para esconder un duplicado.
7. Sigue la skill antes de entregar Lleva al agente a la revisión sin copiar sus pasos en AGENTS.md.

Dejé fuera lo que ya hace otra pieza (el formato y el tamaño de las funciones), lo obvio («escribe código limpio») y lo que solo importa a veces, que va en la skill. Cómo elegir qué entra en el contexto del agente lo explica Diseño del contexto.

La skill de revisión

La skill clean-code-review tiene seis pasos: duplicados (ejecutar npm run check:duplicates y buscar la misma lógica con otros nombres), nombres, responsabilidades, alcance, volver a verificar e informar al usuario de qué duplicados dejó y por qué.

Es una skill y no una regla porque solo se necesita al final. Al empezar, el agente solo carga su nombre y su descripción; el resto lo lee cuando la usa. Así la revisión no ocupa sitio en el AGENTS.md.

El plan también pensaba en un subagente revisor. Un subagente revisaría con un contexto limpio, sin lo que el agente ya cree de su propio código, y eso es una ventaja. Pero cada agente define los subagentes en un formato distinto, y la serie los trata el día 7. La documentación de Claude Code avisa además de un riesgo: un revisor al que pides buscar problemas casi siempre encuentra alguno, y perseguirlos todos lleva a sobrediseñar. Por eso la skill empieza diciendo que solo se cambia lo que claramente mejora.

El explorador

Al cargarse, el explorador abre AGENTS.md. La pieza no tiene la mini app: solo su configuración, su hook, su skill y las pruebas del hook. Las dependencias y package-lock.json no aparecen.

// Stop hook: connect it to your agent's stop event, the moment the agent is about to finish.
// It runs jscpd on the folders named in the `check:duplicates` script and reports the duplicated
// blocks it has not reported before. Duplicated code is sometimes the right choice, so this is a
// warning, not a gate: each duplicate is reported once. The first time, the hook prints the list to
// stderr and exits with code 2, which agents that follow this convention read as "not done yet". If
// the agent decides to keep a duplicate and tries to finish again, the hook lets it. Exit code 0
// with no output means there is nothing new to report.
//
// The script is not tied to one agent: it reads no agent-specific input or environment variable.
// stdin (the hook's JSON input) is not read: the check does not depend on it.
import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

// The project root is two folders up from .agents/hooks/. Agents start hooks from different
// folders, so the script does not rely on the current directory.
const scriptDir = path.dirname(fileURLToPath(import.meta.url));
const projectDir = path.resolve(scriptDir, '..', '..');

// node_modules/.cache/ is where Node tools usually keep their caches, and git already ignores it.
// The JSON report and the list of reported duplicates live there, out of the agent's way.
const CACHE_DIR = 'node_modules/.cache/report-duplicates';
const REPORT_FILE = path.join(projectDir, CACHE_DIR, 'jscpd-report.json');
const REPORTED_FILE = path.join(projectDir, CACHE_DIR, 'reported.json');
const JSCPD = path.join(projectDir, 'node_modules', 'jscpd', 'bin', 'jscpd');
const CHECK_TIMEOUT_MS = 60_000;
const MAX_LISTED = 10;

const problem = runJscpd();
if (problem !== null) {
  // A check that cannot run must not pass in silence. The usual cause is a missing install or a
  // folder in check:duplicates that does not exist.
  process.stderr.write(
    `Could not run the duplicate check (\`npm run check:duplicates\`).\n${problem}\n` +
      'Fix the setup, or tell the user if you cannot.\n',
  );
  process.exitCode = 2;
} else {
  const duplicates = readDuplicates();
  const reported = readReported();
  const fresh = duplicates.filter((duplicate) => !reported.has(duplicate.id));
  // Only the duplicates that still exist are remembered. If one is removed and comes back later, it
  // is reported again.
  writeReported(duplicates.map((duplicate) => duplicate.id));
  if (fresh.length > 0) {
    process.stderr.write(warning(fresh));
    process.exitCode = 2;
  }
}

// The folders come from the check:duplicates script in package.json (for example `jscpd src`), so
// the hook and the command a person runs always scan the same code. The hook starts jscpd with node
// instead of npm, which added about 0.7 seconds to every run. Returns null when the report is ready,
// or the reason it is not.
function runJscpd() {
  const [command, ...args] = readCheckDuplicatesScript();
  if (command !== 'jscpd') {
    return 'The check:duplicates script in package.json must run jscpd, for example `jscpd src`.';
  }
  rmSync(REPORT_FILE, { force: true });
  const reportArgs = ['--silent', '--reporters', 'json', '--output', CACHE_DIR];
  const result = spawnSync(process.execPath, [JSCPD, ...args, ...reportArgs], {
    cwd: projectDir,
    encoding: 'utf8',
    timeout: CHECK_TIMEOUT_MS,
  });
  if (result.status === 0 && existsSync(REPORT_FILE)) {
    return null;
  }
  return [result.stdout, result.stderr, result.error?.message].filter(Boolean).join('\n').trim();
}

function readCheckDuplicatesScript() {
  try {
    const packageJson = JSON.parse(readFileSync(path.join(projectDir, 'package.json'), 'utf8'));
    return String(packageJson.scripts?.['check:duplicates'] ?? '')
      .trim()
      .split(/\s+/);
  } catch {
    return [];
  }
}

// Each duplicate gets an id from its two files and its code, not its line numbers, so an edit
// above it does not make it new.
function readDuplicates() {
  const report = JSON.parse(readFileSync(REPORT_FILE, 'utf8'));
  return report.duplicates.map((duplicate) => {
    const first = location(duplicate.firstFile);
    const second = location(duplicate.secondFile);
    const files = [first.file, second.file].sort().join('\n');
    const id = createHash('sha256').update(`${files}\n${duplicate.fragment}`).digest('hex');
    return { id, first, second, lines: duplicate.lines };
  });
}

// jscpd writes paths with the separator of the operating system. The agent gets forward slashes.
function location(file) {
  return { file: file.name.replaceAll('\\', '/'), start: file.start, end: file.end };
}

function readReported() {
  try {
    return new Set(JSON.parse(readFileSync(REPORTED_FILE, 'utf8')));
  } catch {
    return new Set();
  }
}

function writeReported(ids) {
  mkdirSync(path.dirname(REPORTED_FILE), { recursive: true });
  writeFileSync(REPORTED_FILE, `${JSON.stringify(ids, null, 2)}\n`);
}

function warning(fresh) {
  const lines = [
    'Duplicated code: a warning, not a failure. jscpd found the same code in more than one place:',
    '',
  ];
  for (const { first, second, lines: count } of fresh.slice(0, MAX_LISTED)) {
    lines.push(
      `- ${first.file}:${first.start}-${first.end} and ${second.file}:${second.start}-${second.end} (${count} lines)`,
    );
  }
  if (fresh.length > MAX_LISTED) {
    lines.push(`- and ${fresh.length - MAX_LISTED} more. Run \`npm run check:duplicates\`.`);
  }
  lines.push(
    '',
    'Look at each one before you finish:',
    '- If both copies hold the same rule and would change together, move it into one function and call it from both places.',
    '- If they only look alike, or a shared function would need a flag or extra parameters to tell its callers apart, keep the copies.',
    'Tell the user which duplicates you kept and why. Each duplicate is reported once: when you try to finish again, this hook lets you.',
    '',
  );
  return lines.join('\n');
}
---
name: clean-code-review
description: Review your own changes for duplicated code, names and responsibilities before you say a task is done. Use at the end of any task that added or changed code, or when the user asks for a clean-code review.
---

# Clean-code review

Review only the code this task changed. List it with `git status` and `git diff`. Change only what is clearly better: a review that adds layers, helpers or defensive code that nobody asked for makes the code worse.

1. **Duplicates.** Run `npm run check:duplicates`. jscpd only finds copies with the same tokens, so it misses the same logic written with other names. For each function you added, search the code for its main domain word (for example, `grep -rn "loan" src`) and read what is already there. For each duplicate, extract a shared function only if both copies hold the same rule and would change together. If they only look alike, or a shared function would need a flag or extra parameters to tell its callers apart, keep the copies.
2. **Names.** Each new file, function and variable says what it is or does, with the words of the domain (book, member, loan). Rename vague names such as `data`, `info`, `item`, `handle`, `process`, `utils` or `temp`. A boolean reads as a question: `isAvailable`, `hasActiveLoans`.
3. **Responsibilities.** Each new function does one thing. If you need "and" to describe it, split it. Keep each part in the folder where the project's `AGENTS.md` says it goes.
4. **Scope.** Remove what the task did not ask for: unused parameters and options, abstractions written for a future need, commented-out code, and changes to files the task did not need.
5. **Verify.** If you changed anything, run `npm run verify` again.
6. **Report.** Tell the user in a few lines what this review changed, and which duplicates you kept and why.
import { spawn } from 'node:child_process';
import { copyFileSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { afterAll, describe, it } from 'vitest';

// These tests run the stop hook the way an agent does, then read its exit code and stderr. Each
// test copies the hook and .jscpd.json into a small fake project in the system's temporary folder
// and writes some source files. The hook runs the real jscpd installed in this project. The folders
// are deleted at the end.

const hook = fileURLToPath(
  new URL('../.agents/hooks/report-duplicates-before-stop.mjs', import.meta.url),
);
const jscpdConfig = fileURLToPath(new URL('../.jscpd.json', import.meta.url));
const jscpdBin = fileURLToPath(new URL('../node_modules/jscpd/bin/jscpd', import.meta.url));
const projectDirs: string[] = [];

// A function that validates a text field, and the same function copied under another name. jscpd
// sees the copy: only the function name changed.
const READ_TITLE = `export function readTitle(input: unknown): string {
  if (typeof input !== 'string') {
    throw new Error('The value must be text');
  }
  const text = input.trim();
  if (text.length === 0 || text.length > 200) {
    throw new Error('The value must have between 1 and 200 characters');
  }
  return text;
}
`;
const READ_NAME_COPY = READ_TITLE.replace('readTitle', 'readName');
// The same logic with every name and message changed. jscpd compares tokens, so it does not see it.
const READ_NAME_RENAMED = `export function readName(value: unknown): string {
  if (typeof value !== 'string') {
    throw new Error('A name is text');
  }
  const name = value.trim();
  if (name.length === 0 || name.length > 200) {
    throw new Error('A name has between 1 and 200 characters');
  }
  return name;
}
`;
const COUNT_LOANS = `export function countActiveLoans(loans: { returnedAt: string | null }[]): number {
  return loans.filter((loan) => loan.returnedAt === null).length;
}
`;

function createProject(checkDuplicates = 'jscpd src'): string {
  const projectDir = mkdtempSync(path.join(tmpdir(), 'duplicates-hook-'));
  projectDirs.push(projectDir);
  mkdirSync(path.join(projectDir, '.agents', 'hooks'), { recursive: true });
  copyFileSync(
    hook,
    path.join(projectDir, '.agents', 'hooks', 'report-duplicates-before-stop.mjs'),
  );
  copyFileSync(jscpdConfig, path.join(projectDir, '.jscpd.json'));
  const scripts = { 'check:duplicates': checkDuplicates };
  writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify({ private: true, scripts }));
  // The hook runs node_modules/jscpd/bin/jscpd of its own project. In the fake project, that file
  // loads the jscpd installed in this one.
  const binDir = path.join(projectDir, 'node_modules', 'jscpd', 'bin');
  mkdirSync(binDir, { recursive: true });
  writeFileSync(path.join(binDir, 'jscpd'), `require(${JSON.stringify(jscpdBin)});\n`);
  mkdirSync(path.join(projectDir, 'src'));
  return projectDir;
}

function writeSource(projectDir: string, name: string, content: string): void {
  writeFileSync(path.join(projectDir, 'src', name), content);
}

// The hook runs from this project's folder, not the fake project's, as when an agent starts it
// from another folder. spawn is asynchronous, so the tests can run at the same time.
function runHook(projectDir: string): Promise<{ code: number | null; stderr: string }> {
  return new Promise((resolve, reject) => {
    const child = spawn(process.execPath, [
      path.join(projectDir, '.agents', 'hooks', 'report-duplicates-before-stop.mjs'),
    ]);
    let stderr = '';
    child.stderr.setEncoding('utf8').on('data', (chunk: string) => {
      stderr += chunk;
    });
    child.on('error', reject);
    child.on('close', (code) => resolve({ code, stderr }));
    child.stdin.end('{}');
  });
}

afterAll(() => {
  for (const projectDir of projectDirs) {
    rmSync(projectDir, { recursive: true, force: true });
  }
});

// Each run starts jscpd, which takes about a second on a computer and much longer in StackBlitz,
// so the timeout is longer than usual. The hook starts jscpd without npm, which keeps each run light
// enough to run the tests at the same time there too.
describe.concurrent('report-duplicates-before-stop hook', { timeout: 120_000 }, () => {
  it('passes in silence when there is no duplicated code', async ({ expect }) => {
    const projectDir = createProject();
    writeSource(projectDir, 'books.ts', READ_TITLE);
    writeSource(projectDir, 'loans.ts', COUNT_LOANS);

    const result = await runHook(projectDir);

    expect(result.stderr).toBe('');
    expect(result.code).toBe(0);
  });

  it('reports a copied function once, with code 2 and both locations', async ({ expect }) => {
    const projectDir = createProject();
    writeSource(projectDir, 'books.ts', READ_TITLE);
    writeSource(projectDir, 'members.ts', READ_NAME_COPY);

    const first = await runHook(projectDir);
    // The agent keeps the copy and tries to finish again: the hook lets it.
    const second = await runHook(projectDir);

    expect(first.code).toBe(2);
    expect(first.stderr).toContain('Duplicated code: a warning, not a failure.');
    expect(first.stderr).toMatch(/src\/books\.ts:\d+-\d+/);
    expect(first.stderr).toMatch(/src\/members\.ts:\d+-\d+/);
    expect(first.stderr).toContain('Each duplicate is reported once');
    expect(second.stderr).toBe('');
    expect(second.code).toBe(0);
  });

  it('reports a new duplicate, and a duplicate that was removed and comes back', async ({
    expect,
  }) => {
    const projectDir = createProject();
    writeSource(projectDir, 'books.ts', READ_TITLE);
    writeSource(projectDir, 'members.ts', READ_NAME_COPY);
    await runHook(projectDir);

    // The copy in members.ts goes away and a new one appears in authors.ts.
    writeSource(projectDir, 'members.ts', COUNT_LOANS);
    writeSource(projectDir, 'authors.ts', READ_TITLE.replace('readTitle', 'readAuthor'));
    const fresh = await runHook(projectDir);
    // The copy in members.ts comes back.
    writeSource(projectDir, 'members.ts', READ_NAME_COPY);
    const back = await runHook(projectDir);

    expect(fresh.code).toBe(2);
    expect(fresh.stderr).toMatch(/src\/authors\.ts:\d+-\d+/);
    expect(fresh.stderr).not.toContain('src/members.ts');
    expect(back.code).toBe(2);
    expect(back.stderr).toMatch(/src\/members\.ts:\d+-\d+/);
  });

  // A limit of jscpd, not of the hook: the clean-code-review skill asks the agent to look for this.
  it('does not see the same logic written with other names', async ({ expect }) => {
    const projectDir = createProject();
    writeSource(projectDir, 'books.ts', READ_TITLE);
    writeSource(projectDir, 'members.ts', READ_NAME_RENAMED);

    const result = await runHook(projectDir);

    expect(result.stderr).toBe('');
    expect(result.code).toBe(0);
  });

  it('fails with code 2 when the duplicate check cannot run', async ({ expect }) => {
    const projectDir = createProject('jscpd missing-folder');
    writeSource(projectDir, 'books.ts', READ_TITLE);

    const result = await runHook(projectDir);

    expect(result.code).toBe(2);
    expect(result.stderr).toContain('Could not run the duplicate check');
    expect(result.stderr).toContain('missing-folder');
  });
});
node_modules/
{
  "format": ["typescript", "javascript"],
  "minTokens": 50,
  "minLines": 5,
  "noTips": true
}
# AGENTS.md

## Project

This folder is the **clean-code piece** of the Agent Atlas harness series. It is not an app: it holds the settings of the duplicate detector (jscpd), a stop hook, a review skill and the tests of the hook, ready to add to a harness. The layered harness (`../layered/`) already includes it.

Use npm in this folder, not pnpm. Run `npm run verify` before you say a task is done.

The `Clean code` section below is the one to paste into the `AGENTS.md` of a harness. It has seven rules on purpose: each rule added to this file makes the others easier to miss.

## Clean code

- Before you write a new function, search the code for one that already does the job, and reuse it.
- Name files, functions and variables with the words of the domain (book, member, loan). Do not use vague names such as `data`, `info`, `handle` or `utils`.
- A function does one thing. If you need "and" to describe what it does, split it.
- Do not merge code only because it looks alike. Extract a shared function when the copies hold the same rule and would change together. If the shared function would need a flag or extra parameters to tell its callers apart, keep the copies.
- Write only what the task needs: no options, parameters or abstractions for later, and no changes to code the task does not touch.
- When you try to finish, the hook `.agents/hooks/report-duplicates-before-stop.mjs` runs jscpd on the folders of the `check:duplicates` script and lists the duplicated blocks it has not reported before. It is a warning: decide on each one with the rule above and tell the user which ones you kept. Never edit `.jscpd.json`, the `check:duplicates` script or the hook to hide a duplicate.
- Before you say a task is done, follow the skill `clean-code-review` (`.agents/skills/clean-code-review/SKILL.md`).

## Files

| File                                              | What it does                                                                                                      |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `.agents/hooks/report-duplicates-before-stop.mjs` | Runs when the agent tries to finish and reports each new duplicated block once (exit code 2), then lets it finish |
| `.agents/skills/clean-code-review/SKILL.md`       | The review steps before a task is done: duplicates, names, responsibilities and scope                             |
| `.jscpd.json`                                     | The jscpd settings: which languages it reads and how long a copy must be to count                                 |
| `test/`                                           | Runs the hook the way an agent does, against small fake projects, and checks what it reports and its exit codes   |

## Verification

Run these from this folder:

- `npm run typecheck`: TypeScript, for the tests.
- `npm test`: the tests of the hook.
- `npm run verify`: both, in that order.
- `npm run check:duplicates`: jscpd on this folder's code. It reports duplicates but never fails, so it is not part of `verify`.
{
  "name": "harness-piece-clean-code",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=22"
  },
  "scripts": {
    "test": "vitest run",
    "typecheck": "tsc --noEmit",
    "check:duplicates": "jscpd .agents test",
    "verify": "npm run typecheck && npm test"
  },
  "devDependencies": {
    "@types/node": "22.20.5",
    "jscpd": "4.3.0",
    "typescript": "5.9.3",
    "vitest": "5.0.4"
  }
}
# Clean-code piece

A reusable part of the Agent Atlas harness series. It separates the part of clean code that a tool can check from the part that still needs judgment. A tool, jscpd, finds copied code and a stop hook shows it to the agent as a warning. Short rules in `AGENTS.md` and a review skill cover names, responsibilities and scope, which no tool checks well.

It is not an app. It holds the settings, a hook, a skill and the tests of the hook, so you can check the hook before you copy it into a harness. The [layered harness](../layered/) already includes it.

## Run it

```bash
npm install
npm run verify
```

## What it adds to a harness

| Part                     | Files                                             | What it does                                                                                                                                                                                    |
| ------------------------ | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Duplicate check          | `.jscpd.json`, the `check:duplicates` script      | Runs jscpd on the folders named in the script. It reports copies of at least 5 lines and 50 tokens, and never fails.                                                                            |
| Duplicate warning        | `.agents/hooks/report-duplicates-before-stop.mjs` | When the agent tries to finish, runs jscpd on the folders of the `check:duplicates` script and reports each new duplicate once (exit code 2). When the agent tries to finish again, it lets it. |
| Review before delivering | `.agents/skills/clean-code-review/SKILL.md`       | The steps the agent follows before it says a task is done: duplicates, names, responsibilities and scope.                                                                                       |
| Instructions             | The `Clean code` section of `AGENTS.md`           | Seven rules, on purpose: each rule added to the file makes the others easier to miss.                                                                                                           |

The hook follows the same contract as the rest of the series: it finds the project root from its own location, reads no agent-specific environment variable, and reports with exit code 2 and the reason on stderr. Exit code 0 with no output means "go on".

The hook reads the folders to scan from the `check:duplicates` script, which must start with `jscpd`, so the hook and the command you run scan the same code. It starts jscpd with `node` instead of `npm run`, which added about 0.7 seconds to every run.

Duplicated code is sometimes the right choice, so the hook is a warning, not a gate. A stop hook can only let the agent finish or send it back, so the hook sends it back once per duplicate. It remembers the duplicates it reported in `node_modules/.cache/report-duplicates/reported.json`, by their files and their code, not their line numbers. A duplicate that is removed and comes back is reported again. Delete that folder to see every duplicate again.

## Add it to a harness

1. Copy `.agents/hooks/report-duplicates-before-stop.mjs`, `.agents/skills/clean-code-review/SKILL.md`, `.jscpd.json` and `test/report-duplicates-before-stop.test.ts` into the harness.
2. Install jscpd with `npm install --save-dev --save-exact jscpd@4.3.0`. The tests also need TypeScript and Vitest.
3. Add the script `"check:duplicates": "jscpd src"` to `package.json`, with the folders that hold the app's code. It has to start with `jscpd`, because the hook reads the folders from it. In this folder the script scans `.agents` and `test`, because the piece has no `src`. Do not add it to `verify`: it never fails.
4. Paste the `Clean code` section of `AGENTS.md` into the harness's `AGENTS.md`.
5. Connect the hook to your agent (next section). Connect the skill too if your agent does not read `.agents/skills/`.
6. Run `npm run verify` and `npm run check:duplicates`.

## Connect it to your agent

Agents do not share a settings format, so the hook in `.agents/` does nothing on its own. Register `node .agents/hooks/report-duplicates-before-stop.mjs` on the event that runs when the agent is about to finish.

Some agents read skills from `.agents/skills/`. Others read them from their own folder, so the skill has to be copied there.

The Agent Atlas page for this piece shows the settings for some agents and says what was tested: <https://agentatlas-dev.vercel.app/en/harnesses/clean-code/>.

## Why jscpd 4

jscpd 5 has a Rust engine and runs a native binary for each platform. That binary cannot run in StackBlitz, where the series runs its tests in the browser. jscpd 4.3.0 (npm tag `latest-4`) is plain JavaScript.

`npm audit` reports 5 high-severity findings after the install. They all come from one advisory in `braces` (GHSA-vfj7-8cjw-p6xm), which jscpd 4 loads through `fast-glob` and `micromatch`. A deeply nested brace pattern can crash the process. Here the patterns come from your own `package.json` and `.jscpd.json`, not from outside input. No fixed version of `braces` exists yet.

## Checks

| Command                    | What it checks                                         |
| -------------------------- | ------------------------------------------------------ |
| `npm run typecheck`        | TypeScript types of the tests                          |
| `npm test`                 | The hook, run the way an agent runs it                 |
| `npm run verify`           | Both, in order                                         |
| `npm run check:duplicates` | jscpd on this folder's code (a report, it never fails) |

## Limits

- jscpd compares tokens. It finds copied code even with other spacing or line breaks, but not the same logic written with other names. The review skill asks the agent to look for that.
- jscpd only sees the size of a copy. It cannot tell a duplicate that should be one function from two pieces of code that only look alike. That is the agent's call, or yours.
- Names, responsibilities and scope are not checked by any tool here. The rules and the skill are instructions, not barriers.
- Nothing technical stops the agent from editing `.jscpd.json`, the script or the hook to hide a duplicate. `AGENTS.md` forbids it.
- A duplicate reported once is not reported again, even in a later session, while it exists.
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "noEmit": true,
    "types": ["node"],
    "skipLibCheck": true,
    "noUncheckedIndexedAccess": true,
    "verbatimModuleSyntax": true
  },
  "include": ["test"]
}

Cómo usarla

Puedes ejecutar las pruebas de la pieza en el navegador o en tu equipo.

En el navegador, el botón Ejecutar en el navegador abre la pieza en StackBlitz, un servicio externo, en una pestaña nueva. StackBlitz instala las dependencias y ejecuta npm test: 5 pruebas que lanzan el hook sobre proyectos falsos con jscpd de verdad. El 18 de octubre de 2026 lo probé en Chromium 152 con el botón «Abrir StackBlitz en esta pestaña»: pasaron las 5 pruebas, y su terminal midió 28 s para instalar las dependencias y ejecutarlas. No lo probé en Firefox ni en Safari, ni con el botón de pestaña nueva.

En tu equipo necesitas Node 22 o superior. Copia los archivos de la pieza en una carpeta y ejecuta, con npm:

npm install
npm run verify
npm run check:duplicates

npm run verify comprueba los tipos de las pruebas y ejecuta las 5 pruebas. npm run check:duplicates pasa jscpd por el código de la pieza; como la pieza no tiene src/, aquí revisa .agents y test.

Añadirla a un arnés

  1. Copia .agents/hooks/report-duplicates-before-stop.mjs, .agents/skills/clean-code-review/SKILL.md, .jscpd.json y test/report-duplicates-before-stop.test.ts en el arnés.
  2. Instala jscpd con npm install --save-dev --save-exact jscpd@4.3.0. Las pruebas necesitan además TypeScript y Vitest.
  3. Añade a package.json el script "check:duplicates": "jscpd src", con las carpetas donde está el código de la app. Tiene que empezar por jscpd, porque el hook lee de ahí las carpetas. No lo sumes a verify: nunca falla, así que ahí no comprueba nada.
  4. Pega la sección Clean code del AGENTS.md de la pieza en el AGENTS.md del arnés.
  5. Conecta el hook a tu agente, y también la skill si tu agente no lee .agents/skills/. Lo explica el apartado siguiente.
  6. Ejecuta npm run verify y npm run check:duplicates.

Así la añadí al arnés por capas. jscpd no encontró duplicados en su src/, así que no hubo que cambiar código. Las pruebas pasaron de 65 a 70, y el arnés tiene ahora cuatro hooks de parada: arquitectura, secretos, calidad y duplicados.

El día 6 copié la pieza sin cambios en el arnés hexagonal: los mismos archivos y las mismas 5 pruebas. jscpd tampoco encontró duplicados en su src/.

El día 7 la copié también sin cambios en el arnés de monolito modular. jscpd no encontró duplicados en su src/, que allí incluye las pruebas del módulo de préstamos.

El día 8 la copié sin cambios en el arnés orientado a eventos, con su skill de revisión junto a la skill nueva, add-event. jscpd tampoco encontró duplicados en su src/.

Conectarla a tu agente

Cada agente lee los hooks y las skills desde su propia configuración. Esos archivos no vienen en la pieza: créalos tú en la carpeta del arnés. Si ya conectaste otras piezas, añade este hook a la misma configuración.

Claude Code. En .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.agents/hooks/report-duplicates-before-stop.mjs"],
            "timeout": 120
          }
        ]
      }
    ]
  }
}
  • Claude Code no lee .agents/skills/. Copia la carpeta .agents/skills/clean-code-review/ en .claude/skills/clean-code-review/.
  • Según su documentación, cuando un hook de parada termina con código 2, el agente recibe el texto de stderr y sigue trabajando. Corta tras 8 continuaciones seguidas, pero este hook no llega a eso: avisa una vez de cada duplicado.

Codex. Lee AGENTS.md y las skills de .agents/skills/ por su cuenta. Para el hook, en .codex/hooks.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node .agents/hooks/report-duplicates-before-stop.mjs",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Como en las otras piezas, ábrelo en la carpeta del arnés y marca el hook como de confianza con /hooks. Su documentación dice que, en la parada, espera un JSON en la salida estándar cuando el hook termina con código 0; el script no escribe nada en ese caso, y no pude comprobar si Codex lo acepta.

Cursor. Lee AGENTS.md y las skills de .agents/skills/. Su hook stop espera un JSON con followup_message en la salida estándar, así que este hook necesitaría un pequeño adaptador, que no escribí.

No probé ninguna de estas configuraciones en una sesión real. Salen de la documentación de cada agente, consultada el 18 de octubre de 2026.

Qué se puede automatizar y qué no

Qué Qué lo hace ¿Se automatiza?
Código copiado jscpd en el hook de parada Sí, como aviso
La misma lógica escrita con otros nombres La regla 1 y la skill No: jscpd no la ve
Si un duplicado debe ser una sola función El agente o tú, con la regla 4 No
Funciones largas o enredadas ESLint en la pieza de calidad Sí: complejidad, anidamiento, parámetros y líneas
Que una función haga una sola cosa La regla 3 y la skill En parte: ESLint mide el tamaño, no la responsabilidad
Nombres claros La regla 2 y la skill No
Que cada cosa esté en su capa dependency-cruiser en el arnés por capas Sí, para los imports; no para dónde vive la lógica
Código para el futuro que nadie pidió La regla 5 y la skill No

Qué se comprobó

Lo que probé el 18 de octubre de 2026, en Windows 11 con Node 24.19:

  • En la pieza, npm run verify pasó: tipos y 5 de 5 pruebas.
  • En el arnés por capas, con la pieza añadida, npm run verify pasó: tipos, lint, formato, no dependency violations found (15 modules, 39 dependencies cruised), secretlint y 70 de 70 pruebas.
  • Dupliqué código a propósito: creé src/services/reservation-service.ts copiando de LoanService.lend las comprobaciones de que el libro y el socio existen, como haría un agente con prisa. El hook salió con código 2 en unos 1,3 segundos y escribió src/services/loan-service.ts:21-30 and src/services/reservation-service.ts:11-20 (10 lines). Al lanzarlo otra vez salió con código 0 sin escribir nada. Añadí una línea encima de la copia y siguió en 0. Borré el archivo: salió con 0 y la lista de avisados quedó vacía.
  • Copié en members-controller.ts la función readText de http.ts, de 6 líneas, con otro nombre. El hook no avisó: con el mínimo de 50 tokens, jscpd no la ve. Con un mínimo de 30 sí la encontró, pero en el código original marcó también el final de dos rutas, en books-controller.ts y en loans-controller.ts, que se parecen pero no conviene unir. Dejé el mínimo en 50.
  • Una de las pruebas escribe la misma función con otros nombres y comprueba que jscpd no la ve. Es una limitación de jscpd, y la prueba la deja escrita.
  • Lancé el hook desde otra carpeta, como hace un agente que arranca en otro sitio, con un evento de parada simulado por la entrada.

Los tiempos varían porque la máquina tenía otras tareas en marcha. El hook de duplicados tardó alrededor de un segundo sin nada que avisar. Las 5 pruebas nuevas se suman al hook de calidad, que ejecuta todas las pruebas en cada parada: en el arnés por capas tardó unos 15 segundos con ellas y unos 14 sin ellas, medido el mismo día. Los cuatro hooks de parada lanzados a la vez, como hace Claude Code, tardaron unos 15 segundos.

En StackBlitz, con Chromium 152 y el botón de la misma pestaña, pasaron las 5 pruebas de la pieza (28 s en su terminal) y las 70 del arnés por capas (56 s). No salió a la primera:

  • La primera versión del hook ejecutaba npm run check:duplicates. En StackBlitz cada prueba tardó hasta 55 segundos, y en el arnés por capas fallaron por tiempo pruebas de otros hooks. Ahora el hook arranca jscpd sin npm: las pruebas de la pieza pasaron de 58 a 12 segundos en Vitest.
  • Aun así fallaban 5 o 6 pruebas de las piezas de seguridad y calidad, por superar el límite de 5 segundos de Vitest. Lancé el mismo botón en la web publicada, con el arnés del 16 de octubre, sin esta pieza: fallaron 5 de 65 pruebas y, en un segundo intento, 6, todas por tiempo en ese segundo intento. StackBlitz iba más lento que ese día. Subí el límite de esas pruebas a 30 segundos en sus tres copias, y después pasaron todas: 39 de 39 en la pieza de seguridad y 12 de 12 en la de calidad.

Lo que no pude probar: una sesión real de un agente. El CLI de Claude Code de la máquina (2.1.220) respondió OAuth session expired and could not be refreshed. Codex avisó el 15 de octubre de que la cuenta había llegado a su límite de uso hasta el 2 de noviembre, así que no lo intenté. Cursor no está instalado. Tampoco le pedí a un agente una tarea dentro del arnés.

Limitaciones

  • jscpd encuentra código copiado, no la misma lógica escrita con otros nombres. Con el mínimo de 50 tokens tampoco ve copias cortas, como una función de 6 líneas.
  • jscpd no sabe si dos copias son la misma regla o solo se parecen. Esa decisión es del agente o tuya.
  • Los nombres, las responsabilidades y el alcance del cambio no los comprueba ninguna herramienta. Las reglas y la skill son instrucciones, no barreras.
  • Nada técnico impide que el agente cambie .jscpd.json, el script o el hook para esconder un duplicado. AGENTS.md se lo prohíbe.
  • Un duplicado avisado no se vuelve a avisar mientras exista, aunque sea en otra sesión.
  • Las 5 pruebas del hook se suman a npm test, que el hook de calidad ejecuta en cada parada. En el arnés por capas añadieron alrededor de un segundo a cada parada.
  • Solo lo probé en Windows 11 con Node 24.19.

Siguiente paso

Con esta pieza, el arnés por capas ya tiene las tres piezas reutilizables: seguridad, calidad y código limpio. El arnés hexagonal, del día 6, reutiliza las tres tal cual; solo cambia la parte de arquitectura. El arnés de monolito modular, del día 7, y el arnés orientado a eventos, del día 8, también. La guía para elegir un arnés los compara.

Fuentes

Consultadas el 18 de octubre de 2026: