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.mdy 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:duplicatesno empieza porjscpd, 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 auditmuestra 5 avisos de gravedad alta después de instalar jscpd 4. Todos vienen de un mismo fallo debraces, una dependencia que llega a través defast-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 tupackage.jsony 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 connode, 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.mdcorto 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.
.agents/hooks/report-duplicates-before-stop.mjs
// 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');
}.agents/skills/clean-code-review/SKILL.md
---
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.test/report-duplicates-before-stop.test.ts
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');
});
});.gitignore
node_modules/.jscpd.json
{
"format": ["typescript", "javascript"],
"minTokens": 50,
"minLines": 5,
"noTips": true
}AGENTS.md
# 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`.package.json
{
"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"
}
}README.md
# 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.tsconfig.json
{
"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.
StackBlitz es un servicio externo y se abre en una pestaña nueva. Funciona mejor en Chrome y Edge; en Firefox y Safari está en beta. La primera ejecución tarda un poco, porque instala las dependencias.
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
- Copia
.agents/hooks/report-duplicates-before-stop.mjs,.agents/skills/clean-code-review/SKILL.md,.jscpd.jsonytest/report-duplicates-before-stop.test.tsen el arnés. - Instala jscpd con
npm install --save-dev --save-exact jscpd@4.3.0. Las pruebas necesitan además TypeScript y Vitest. - Añade a
package.jsonel script"check:duplicates": "jscpd src", con las carpetas donde está el código de la app. Tiene que empezar porjscpd, porque el hook lee de ahí las carpetas. No lo sumes averify: nunca falla, así que ahí no comprueba nada. - Pega la sección
Clean codedelAGENTS.mdde la pieza en elAGENTS.mddel arnés. - Conecta el hook a tu agente, y también la skill si tu agente no lee
.agents/skills/. Lo explica el apartado siguiente. - Ejecuta
npm run verifyynpm 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 verifypasó: tipos y 5 de 5 pruebas. - En el arnés por capas, con la pieza añadida,
npm run verifypasó: 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.tscopiando deLoanService.lendlas 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.tsla funciónreadTextdehttp.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, enbooks-controller.tsy enloans-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.mdse 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:
- jscpd, repositorio oficial. La rama master-v4 tiene el código y la documentación de la versión 4.
- Clone types, documentación de jscpd. Explica qué copias detecta y cuáles no.
- GHSA-vfj7-8cjw-p6xm, aviso de seguridad de
braces. - Troubleshooting, documentación de WebContainers, el entorno de StackBlitz.
- Hooks reference, documentación de Claude Code.
- How Claude remembers your project y Best practices, documentación de Claude Code.
- Skills, documentación de Claude Code.
- Claude prompting best practices, guía de Anthropic.
- Hooks, Custom instructions with AGENTS.md y Best practices, documentación de Codex.
- Hooks, Rules y Skills, documentación de Cursor.
- Specification, formato abierto Agent Skills.
- How Many Instructions Can LLMs Follow at Once?, Jaroslawicz y otros, 2025.
- Orthogonality and the DRY Principle, entrevista de Bill Venners a Dave Thomas, 2003.
- The Wrong Abstraction, Sandi Metz, 2016.
Contenido relacionado
- Diseño del contexto para agentesTécnica
Qué información recibe el agente en cada momento, por qué más no siempre es mejor y cómo darle lo justo: lo esencial desde el principio y el resto cuando lo necesite.
Publicado - Skills: procedimientos reutilizables para agentesTécnica
Una carpeta con instrucciones, y opcionalmente scripts y referencias, que enseña al agente un tipo de tarea concreto. Solo se carga cuando hace falta.
Publicado