AI Coding Agents

Ejemplos de CLAUDE.md de 28 apps Next.js y NestJS en producción (2026)

Cuatro ejemplos de CLAUDE.md para copiar, sacados de 28 apps Next.js y NestJS: raíz, Next.js, NestJS y AGENTS.md, y una skill gratis que revisa el tuyo.

Por Aniq-UI16 de noviembre de 202629 min de lectura
Compartir:
Ejemplos de CLAUDE.md de 28 apps Next.js y NestJS en producción (2026)
#Claude Code#CLAUDE.md#AGENTS.md#Next.js#NestJS#AI coding agents#Claude Code skills#next-intl

Los ejemplos de CLAUDE.md que vale la pena copiar son cortos y concretos: los comandos, puertos y convenciones exactos de un proyecto real, muy por debajo de 200 líneas, sin nada que Claude pueda aprender abriendo las carpetas. Los árboles de archivos y las listas de dependencias gastan contexto en cada sesión y no le enseñan nada nuevo a Claude.

Esta página reúne cuatro ejemplos de CLAUDE.md escritos a partir del código de las 28 apps Next.js y NestJS que publicamos: un archivo raíz, una app Next.js, una API NestJS y un AGENTS.md para Codex y Cursor. Cada línea lleva su motivo, y al final una skill gratuita redacta estos archivos desde tu código y los revisa.

Qué va en un CLAUDE.md

Anthropic describe CLAUDE.md como el sitio para lo que de otro modo explicarías en cada sesión. Claude lo lee al empezar cada sesión como contexto, no como configuración obligatoria, así que una línea comprobable funciona mejor que una vaga: «ejecuta yarn typecheck» es mejor que «prueba tus cambios».

La página de buenas prácticas lo concreta más. Conserva los comandos que confirman el trabajo, los puntos donde el código engaña, las decisiones que no están en ningún lugar del repositorio y todo lo que hayas tenido que corregir dos veces. Quita el recorrido por la arquitectura y la estructura de carpetas porque, según la documentación, Claude lee el repositorio por sí mismo.

Muchos ejemplos de la primera página de resultados están escritos para un proyecto imaginario en lugar de sacarse de uno real. Cada línea de los nuestros nombra un script real, un archivo real que copiar o una trampa real, y cada archivo pasa un verificador ejecutado sobre el código que describe.

Puedes empezar con /init, que escribe un primer CLAUDE.md a partir de tu código, o sugiere mejoras si ya existe uno. Con CLAUDE_CODE_NEW_INIT=1 pregunta qué archivos preparar (CLAUDE.md, skills, hooks) y muestra una propuesta antes de escribir. Después, dice la documentación, el trabajo consiste sobre todo en quitar líneas.

Dónde viven los archivos CLAUDE.md y cuándo se cargan

  • Política gestionada: /Library/Application Support/ClaudeCode/CLAUDE.md en macOS, /etc/claude-code/CLAUDE.md en Linux. La define una organización.
  • Usuario: CLAUDE.md en la carpeta .claude de tu directorio personal. Tus preferencias, en todos los proyectos.
  • Proyecto: ./CLAUDE.md o ./.claude/CLAUDE.md. Versionado y compartido.
  • Local: ./CLAUDE.local.md. Tus notas para un proyecto, fuera de git.

Los archivos de la carpeta donde arrancas Claude, y de cada carpeta superior, se cargan al inicio. Se suman sin sobrescribirse, y el más cercano a ti se lee el último. Si dos archivos se contradicen, Claude puede seguir cualquiera, así que una regla debe vivir en un solo sitio.

Un CLAUDE.md dentro de una subcarpeta solo se carga cuando Claude lee, escribe o edita un archivo de esa carpeta. Por eso nuestros ejemplos se dividen por app: el archivo raíz es corto, las reglas del panel llegan cuando Claude abre un archivo del panel, y una sesión en la API nunca las arrastra.

Una línea como @AGENTS.md importa otro archivo, hasta cuatro niveles, pero no ahorra contexto, porque el archivo importado se carga junto con el que lo nombra. Los archivos de reglas de la carpeta rules dentro de .claude pueden llevar una lista paths y entonces solo se cargan cuando Claude toca un archivo que coincide. Este protege los archivos de mensajes de los dos frontends de Northstack:

---
paths:
  - "**/messages/**/*.json"
---
- Every key exists in both `en.json` and `ar.json` of the same namespace.
- A new namespace file is listed in `website/src/i18n/request.ts` (website)
  or `dashboard/src/config/dashboardNamespaces.ts` (dashboard), or it never loads.

Para ver qué se cargó, ejecuta /context all y mira en Memory files. Los comentarios HTML de un CLAUDE.md se eliminan antes de que Claude lo lea, así que son un sitio gratuito para notas a quien mantiene el archivo.

Cómo escribimos estos ejemplos de CLAUDE.md: un script sobre 28 apps

Escribimos un pequeño script de Node de solo lectura, facts.mjs, que lee el package.json de cada app, los nombres de su .env.example, sus carpetas, sus archivos de mensajes y su configuración. Lo ejecutamos sobre los 12 repositorios que vendemos: 28 apps, 19 con Next.js 16 y 9 con NestJS 10 a 12.

Una regla entraba en los ejemplos solo si el código la respaldaba. El 14 de noviembre de 2026 el script encontró:

  • 0 de 28 package.json contiene un rango de versiones. Cada dependencia, resolución y override es exacta.
  • Las 28 apps usan Yarn 4, y cada una tiene un .env.example (376 nombres de variables en total).
  • Las 19 apps Next.js usan next-intl con messages/<namespace>/<locale>.json en inglés y árabe, un segmento [locale] y src/proxy.ts: 640 archivos de mensajes en 158 namespaces.
  • 16 de 19 guardan sus endpoints en src/lib/api y los leen con hooks de TanStack Query en src/services. Las 19 crean sus formularios con react-hook-form y zod.
  • En 6.969 archivos de componentes: 3.467 clases de lado lógicas (ms-, start-, text-start) y 189 físicas (ml-, left-). Muchas de las 189 son posicionamiento como left-1/2, que se lee igual en los dos sentidos.
  • Las 9 API NestJS responden bajo /api con una ValidationPipe global en whitelist y sincronizan el esquema solo en desarrollo. 8 de 9 no tienen carpeta de migraciones.
  • 0 de 28 apps tiene un script test. 17 de las 19 apps Next.js llaman typecheck a su comprobación de tipos, una la llama type-check y otra no tiene.

Ese último punto importa. Un CLAUDE.md que dice «ejecuta los tests» en un proyecto sin script de test manda a Claude a un comando que falla en cada sesión. Los nuestros dicen que no hay suite de tests y nombran las comprobaciones que sí existen. Esta es la salida real sobre el código fuente de Northstack:

$ node facts.mjs .
Project: northstack
Apps: 3 (2 Next.js, 1 NestJS)
Instruction files at the root: none

## back-end (nest, northstack-backend)
versions: @nestjs/core 12.3.3, typescript 5.9.3
package manager: yarn@4.8.1, node ^22.13.0 || >=24.11.0
scripts: build, format, start, dev, start:debug, start:prod, lint, typeorm, seed, seed:prod, schema, schema:prod, admin:create, admin:create:prod, reset, drop, remove:demo, export:mock
port: 8000
env example: .env.example, 54 names
versions not pinned exactly: none
agent files in this app: none
global prefix: api; ValidationPipe: global, whitelist; ORM: typeorm
synchronize: configService.get('NODE_ENV') === 'development'; migrations folder: none; modules: 22

## dashboard (next, northstack-dashboard)
versions: next 16.4.5, react 19.3.1, typescript 5.9.3, tailwindcss 4.3.4, next-intl 4.14.9
package manager: yarn@4.8.1, node >=22.9.0
scripts: dev, build, start, remove:mock, lint, typecheck, remove:demo
port: 3031
env example: .env.example, 6 names, 5 NEXT_PUBLIC_
versions not pinned exactly: none
agent files in this app: none
app router: src/app, [locale] segment; proxy/middleware: src/proxy.ts
next config: next.config.js, agentRules false
src folders: app, components, config, features, fonts, hooks, layouts, lib, providers, services, store, styles, types
i18n: next-intl, messages/<namespace>/<locale>.json, locales ar/en (RTL locale present), 8 namespaces
data layer: src/lib/api (31 entries); TanStack Query yes; services with hooks/: 26
forms: react-hook-form + zod + @hookform/resolvers
side classes in 419 files: 303 logical (ms-, ps-, start-, text-start...), 1 physical (ml-, pl-, left-, text-left...)

## website (next, northstack-website)
versions: next 16.4.5, react 19.3.1, typescript 6.0.3, tailwindcss 4.3.4, next-intl 4.14.9
package manager: yarn@4.8.1, node >=22.9.0
scripts: dev, build, start, lint, typecheck, remove:demo, remove:mock
port: 3030
env example: .env.example, 9 names, 7 NEXT_PUBLIC_
versions not pinned exactly: none
agent files in this app: none
app router: src/app, [locale] segment; proxy/middleware: src/proxy.ts
next config: next.config.ts, agentRules false
src folders: app, components, config, content, features, fonts, hooks, i18n, lib, services, styles
i18n: next-intl, messages/<namespace>/<locale>.json, locales ar/en (RTL locale present), 10 namespaces
data layer: src/lib/api (5 entries); TanStack Query yes; services with hooks/: 2
forms: react-hook-form + zod + @hookform/resolvers
side classes in 168 files: 147 logical (ms-, ps-, start-, text-start...), 0 physical (ml-, pl-, left-, text-left...)

Ejemplo de CLAUDE.md n.º 1: la raíz de un producto Next.js y NestJS

El archivo raíz se carga en cada sesión iniciada en cualquier punto del repositorio. Contiene lo que comparten las tres apps: dónde están, cómo arrancarlas y comprobarlas, cómo se conectan y las reglas que ninguna puede romper. 41 líneas, 2.075 caracteres.

# Northstack

Three apps in one repository. Each has its own package.json, yarn.lock and
.env.example, so run every command inside the app's folder.

- `website/`: Next.js 16 public site, port 3030
- `dashboard/`: Next.js 16 workspace dashboard and platform admin, port 3031
- `back-end/`: NestJS 12 API, port 8000, every route under `/api`

## Run
- Yarn 4 through Corepack (`corepack enable` once). Not npm, not pnpm.
- All three at once: `docker compose up --build` in this folder.
- Without Docker, the API first: `cd back-end && yarn seed && yarn dev`,
  ready when http://localhost:8000/api/health answers.
- Then `cd dashboard && yarn dev` and `cd website && yarn dev`.

## Check your work
- Frontends: `cd dashboard && yarn typecheck && yarn lint`, the same in `website/`.
- API: `cd back-end && yarn build && yarn lint`. It has no typecheck script.
- There is no test suite: typecheck, lint and build are the checks.

## How the apps connect
- The frontends call the API at `NEXT_PUBLIC_API_BASE_URL`, which ends in `/api`.
- A frontend on a new address goes in `CORS_ORIGIN` in `back-end/.env.example`,
  or every browser call to the API fails.
- `NEXT_PUBLIC_*` values are compiled into the bundle: restart `yarn dev` after
  changing one, and never put a secret in one. Provider keys live in the API only.
- With `NEXT_PUBLIC_API_BASE_URL` empty, a frontend runs on its own sample data
  in `src/lib/mock/`. Keep that mode working.

## Rules for all three apps
- Exact versions in every package.json: `"next": "16.4.5"`, never `"^16.4.5"`.
  Add a package as `yarn add name@1.2.3`.
- Every string a user sees exists in English and Arabic. Arabic runs right to
  left: use logical classes (`ms-4`, `pe-2`, `start-0`, `text-start`), never
  `ml-4`, `pr-2`, `left-0` or `text-left`.
- In each app, `yarn remove:demo` and `yarn remove:mock` delete the code
  between `#region demo-mode` and `#region mock-api` markers. Keep each pair
  intact, and keep code that must survive outside them.

Each app folder has its own CLAUDE.md, loaded when you work in that folder.

Por qué está cada línea

  • Apps y puertos: salen de cada package.json (next dev -p 3030, un script que lee PORT en el panel) y de PORT=8000 en el .env.example de la API. El puerto por defecto de Next.js, 3000, no lo usa ninguna.
  • No npm: cada app declara yarn@4.8.1 y versiona un yarn.lock. Otra herramienta escribiría un segundo archivo de bloqueo.
  • Primero la API: el orden del README. El panel lee cada pantalla de la API, y /api/health indica que está lista.
  • Sin typecheck en la API, sin tests: según las listas de scripts. yarn build ejecuta nest build, que falla ante un error de tipos.
  • CORS_ORIGIN: src/main.ts la pasa a app.enableCors. Un frontend cuya dirección falte no puede llamar a la API desde el navegador.
  • Valores NEXT_PUBLIC_: el .env.example del panel dice que se incrustan al compilar y que nunca pueden contener un secreto.
  • Modo de datos de ejemplo: un NEXT_PUBLIC_API_BASE_URL vacío pasa el frontend a su mock en el navegador. Ningún nombre de carpeta lo dice.
  • Versiones exactas: 0 rangos en 28 apps. Una línea evita que yarn add escriba el primer caret.
  • Árabe y clases lógicas: el panel de Northstack tiene 303 clases de lado lógicas frente a 1 física.
  • Marcadores de región: yarn remove:demo y yarn remove:mock borran los bloques marcados. Un marcador perdido en un lado rompe el borrado.
Página de inicio del sitio Northstack en tema oscuro, la app Next.js en el puerto 3030 que describe el ejemplo de CLAUDE.md raíz
El sitio de Northstack, la app que el archivo raíz pone en el puerto 3030.

Ejemplo n.º 2: un CLAUDE.md para un proyecto Next.js (App Router y next-intl)

Este archivo está en dashboard/ y solo se carga cuando Claude trabaja en un archivo del panel. Un proyecto Next.js App Router tiene más convenciones discretas que una API, así que es el más útil de los cuatro. 43 líneas.

# Dashboard (Next.js 16, App Router, next-intl)

Run in this folder: `yarn dev` (port from `PORT` in .env, 3031 when unset),
`yarn typecheck`, `yarn lint`, `yarn build`.

## Where code goes
- Routes are `src/app/[locale]/**/page.tsx`. A page composes one feature and
  wires its hook; it holds no logic of its own.
- A feature is `src/features/<area>/` with `components/`, `hooks/`,
  `constants/`, `types/` and `utils/`, one job per file. Copy the shape of
  `src/features/dashboard/billing/`.
- Look in `src/components/ui/` before writing a modal, tab strip, notice or
  skeleton, and reuse what is there.
- Import through the `@/` alias (`@/lib/api/billing`). ESLint warns on
  relative imports deeper than two levels.

## Data
- Endpoints live in `src/lib/api/<domain>/` and return the API's
  `{ success, data, message }` shape.
- Screens never import `src/lib/api` or axios. They use the TanStack Query
  hooks in `src/services/<domain>/`: queries in `hooks/`, mutations in
  `hooks/mutations/`, query keys in `keys/`.
- A new endpoint also needs a handler in `src/lib/mock/handlers/`, or its
  screen gets a 404 when `NEXT_PUBLIC_API_BASE_URL` is empty. List a literal
  route before a pattern that would catch it (`/projects/archived` before
  `/projects/:projectId`).

## Text and direction
- Messages are `messages/<namespace>/<locale>.json`, an `en.json` and an
  `ar.json` in every namespace, read with `useTranslations("dashboard/billing")`.
- A new namespace goes in `src/config/dashboardNamespaces.ts`. A file that is
  not listed there is never loaded, and the page shows raw keys.
- Forms are react-hook-form with a zod schema built from translated messages,
  like `src/features/dashboard/billing/utils/billingEmailSchema.ts`.
- Logical Tailwind classes only (`ms-*`, `pe-*`, `start-*`, `text-start`).
  `<html dir>` follows the locale; code that must flip reads `useDirection()`
  from `src/hooks/locale/`.

## Gotchas
- `agentRules: false` in `next.config.js` stops `next dev` from writing an
  AGENTS.md block here. This file is the instruction file.
- `NEXT_PUBLIC_*` values are inlined at build: restart `yarn dev` after editing
  .env. None of them may hold a secret.

Por qué está cada línea

  • La página compone, la feature lleva la lógica: src/app/[locale]/dashboard/billing/page.tsx importa sus componentes y useBillingPage desde la feature de billing. Una carpeta que copiar es más clara que un patrón descrito.
  • src/components/ui/ contiene 44 componentes y carpetas compartidos. La línea manda a Claude allí antes de que escriba otro modal.
  • El alias @/: eslint.config.mjs activa no-relative-import-paths con allowedDepth: 2.
  • La cadena de datos: billingApi.ts, luego useBilling.ts, useBillingActions.ts y billingKeys.ts. 16 de nuestras 19 apps Next.js la siguen.
  • El handler del mock: ante una ruta que no conoce, el mock escribe «No mock handler» y responde 404. Un endpoint nuevo sin handler funciona con la API y falla en el modo de datos de ejemplo.
  • La lista de namespaces: el layout del panel solo carga los namespaces de DASHBOARD_NAMESPACES. Una carpeta que no esté en la lista nunca llega a la página, que entonces muestra claves en lugar de texto.
  • Validación traducida: billingEmailSchema(t) construye su esquema zod con los mensajes de billing, así que los errores también salen en árabe.
  • Dirección: src/app/layout.tsx pone dir en <html> según la locale, y useDirection() sirve al código que debe invertirse, como un gráfico.
  • agentRules: desde Next.js 16.3, next dev escribe un bloque gestionado en AGENTS.md cuando detecta un agente de código, apuntando a la documentación incluida en node_modules/next/dist/docs/. Nuestras 19 apps Next.js ponen agentRules: false. Si lo mantienes, versiona el bloque.
Página de facturación del panel de Northstack en tema oscuro, con el plan, las barras de uso y el historial de facturas, construida desde la carpeta de la feature billing que el CLAUDE.md de Next.js pide copiar
La página de facturación: la carpeta de feature que el archivo de Next.js señala como modelo.
Vista general del espacio de trabajo de Northstack en árabe, de derecha a izquierda, en tema oscuro, con la barra lateral a la derecha y los gráficos invertidos
El mismo panel en árabe: las clases lógicas llevan la barra lateral a la derecha sin una segunda hoja de estilos.

Ejemplo n.º 3: un CLAUDE.md para una API NestJS

El archivo de la API tiene 37 líneas. Recoge las reglas que viven en main.ts, app.module.ts y los scripts de base de datos, que Claude solo ve si abre esos archivos primero.

# API (NestJS 12, TypeORM)

Run in this folder: `yarn dev` (port 8000, from `PORT` in .env), `yarn build`,
`yarn lint`, `yarn format`. There is no typecheck or test script, so
`yarn build` is the type check.

## Database
- SQLite by default (`DB_TYPE=sqlite`, one file), MySQL with `DB_TYPE=mysql`.
  A query has to work on both.
- There are no migrations. With `NODE_ENV=development` the tables follow the
  entities on start. On a server: back up the database, then `yarn schema:prod`.
- `yarn seed` loads the sample data. `yarn reset` empties every table and
  `yarn drop` deletes them: run either only when asked.

## Where code goes
- One folder per feature in `src/modules/<name>/`: `<name>.module.ts`, `dto/`,
  `entities/`, and `controllers/` and `services/` once there are several.
  Copy `src/modules/billing/`.
- Every route is under `/api` (`setGlobalPrefix` in `src/main.ts`).
- Bodies and queries are DTO classes with class-validator decorators. The
  global ValidationPipe sets `whitelist` and `forbidNonWhitelisted`, so a field
  with no decorator is refused with a 400.
- Handlers return `{ success, data, message }`;
  `src/common/interceptors/response.interceptor.ts` wraps anything else.
- Workspace routes take `@UseGuards(AuthGuard('bearer'), WorkspaceGuard)` and
  one `@WorkspacePermissions(...)` per handler. Permission keys are listed in
  `src/modules/workspaces/constants/workspace-permissions.ts`.
- Text a person reads (errors, emails) comes from
  `src/i18n/translations/<locale>/<namespace>.json`, in `en` and `ar`.

## Config
- A new setting goes in `.env.example` with a comment and is read through
  `ConfigService`.
- `src/config/env-check.ts` stops a production start on the example
  `JWT_SECRET` or an empty `CORS_ORIGIN`. Keep those checks.
- After changing what a route returns, run `yarn export:mock` (API seeded and
  running) so both frontends' sample data matches it.

Por qué está cada línea

  • Sin script de typecheck ni de test: la lista de scripts de arriba. yarn build es la única comprobación de tipos.
  • SQLite o MySQL: app.module.ts elige el driver según DB_TYPE.
  • Sin migraciones: synchronize es true solo en desarrollo, y el README dice que hagas una copia y ejecutes yarn schema:prod tras una actualización que cambie tablas. «Añade una columna» tiene dos respuestas plausibles en TypeORM; el archivo dice cuál aplica.
  • reset y drop: vacían o borran todas las tablas. Una línea de CLAUDE.md es una guía; el freno real es una regla deny, más abajo.
  • Carpetas de módulos: src/modules/ tiene 22. Billing separa controllers/, services/, providers/, entities/ y dto/.
  • /api y la ValidationPipe: src/main.ts fija el prefijo y una pipe global con forbidNonWhitelisted, así que un campo de DTO sin decorador recibe un 400.
  • La forma de las respuestas: response.interceptor.ts envuelve cualquier resultado que no sea { success, data, message }, y los dos frontends leen esa forma.
  • Guards: projects.controller.ts usa WorkspaceGuard y @WorkspacePermissions('projects.read') en cada handler.
  • Los textos propios de la API: 9 namespaces en en y ar dentro de src/i18n/translations/.
  • Control del env y exportación del mock: env-check.ts impide arrancar en producción con el secreto de ejemplo; export-mock.mjs escribe los datos de ejemplo de los dos frontends desde la API en marcha.
Página de proyecto de Northstack en tema oscuro con un tablero de tareas de cuatro columnas, servido por los módulos projects y tasks de la API NestJS
Un proyecto y su tablero de tareas, servidos por los módulos projects y tasks de la API.
Matriz de roles y permisos de Northstack en tema oscuro, con columnas owner, admin, member y billing ligadas a las claves de permiso que comprueba la API
La matriz de roles: cada casilla es una clave de permiso que la API comprueba en sus rutas.

Ejemplo n.º 4: AGENTS.md para Codex, Cursor y Claude Code

AGENTS.md es el archivo markdown sencillo que leen Codex, Cursor y GitHub Copilot. Codex recorre desde la raíz del proyecto hasta la carpeta actual, un archivo por carpeta, y deja de añadir al llegar a 32 KiB por defecto. Cursor lo lee en la raíz y en subcarpetas, y prevalece el archivo más específico.

Claude Code también lo lee. Desde la v2.1.277, Claude lee AGENTS.md cuando no existe CLAUDE.md ni CLAUDE.local.md en la carpeta de trabajo o por encima. Si existen los dos, solo lee CLAUDE.md, salvo que Project instructions valga claude-md-and-agents-md en /config.

Así que un equipo con varias herramientas mantiene una sola fuente: el texto común en AGENTS.md y, a su lado, un CLAUDE.md que lo importa y añade líneas solo para Claude. Según la documentación, la importación nunca hace que se lea dos veces, y funciona también en sesiones que no leen AGENTS.md directamente.

# AGENTS.md

Northstack: `website/` (Next.js 16, port 3030), `dashboard/` (Next.js 16,
port 3031) and `back-end/` (NestJS 12, port 8000, routes under `/api`). Each
app has its own package.json and yarn.lock: run commands inside its folder.

## Setup and checks
- Yarn 4 through Corepack. Start the API first:
  `cd back-end && yarn seed && yarn dev`, then `yarn dev` in each frontend.
- Or all three: `docker compose up --build`.
- Frontends: `cd website && yarn typecheck && yarn lint`, same in `dashboard/`.
- API: `cd back-end && yarn build && yarn lint`. No test suite exists.

## Conventions
- Exact versions only in package.json. No `^`, no `~`.
- Text: next-intl, `messages/<namespace>/<locale>.json` with `en` and `ar`.
  The API's own messages: `back-end/src/i18n/translations/<locale>/`.
- RTL: logical Tailwind classes (`ms-*`, `pe-*`, `start-*`, `text-start`).
- Frontend data: endpoint in `src/lib/api/<domain>/`, TanStack Query hook in
  `src/services/<domain>/hooks/`, screen uses the hook.
- Forms: react-hook-form and zod.
- API: one module per folder in `back-end/src/modules/`, DTOs with
  class-validator, answers shaped `{ success, data, message }`.
- No migrations: tables follow the entities in development; on a server run
  `cd back-end && yarn schema:prod` after a backup.

## Next.js docs
Read the guide for the installed version in `node_modules/next/dist/docs/`
inside the app you are changing. `agentRules: false` keeps `next dev` from
writing its own block into this file.

## Never
- Commit `.env` files or put a secret in a `NEXT_PUBLIC_*` variable.
- Break a `#region demo-mode` or `#region mock-api` marker pair.

El CLAUDE.md de al lado, seis líneas:

@AGENTS.md

## Claude Code
- Each app folder has its own CLAUDE.md, loaded when you work there.
- A change across apps: build the API first (`cd back-end && yarn build`),
  then change the frontend.

Por qué está cada línea

  • Un archivo para tres apps: Codex y Cursor nunca ven los archivos de subcarpeta de Claude, así que este reúne los tres ejemplos en 34 líneas. Ambas herramientas leen también AGENTS.md anidados.
  • La línea de la documentación de Next.js: Next.js 16.2 y posteriores incluyen documentación de la versión instalada. Nuestras apps desactivan el bloque gestionado, así que el enlace se escribe a mano.
  • Never: dos reglas sin excepciones. En Claude Code, una regla que debe cumplirse siempre va en la configuración, como se ve más abajo.
  • La importación: la documentación muestra exactamente este patrón. Un enlace simbólico (ln -s AGENTS.md CLAUDE.md) también sirve, salvo en clones de Windows donde Git lo descarga como un archivo de texto de una línea.

¿Cuánto debe medir un CLAUDE.md?

La recomendación de Anthropic es menos de 200 líneas por archivo: uno más largo gasta más contexto y se sigue peor. Claude Code avisa al arrancar cuando un archivo supera esa longitud e ignora cualquier archivo de más de 4 MiB. Con una ventana de 200K, los archivos de subcarpeta y las reglas con rutas se cortan en 40.000 caracteres.

Los nuestros tienen 41, 43, 37 y 34 líneas, 7.828 caracteres entre los cuatro. Cuando un archivo crece, /doctor propone recortes y /doctor prompt-audit marca las líneas que apuntan a archivos inexistentes o se contradicen.

Qué no poner en CLAUDE.md

  • Secretos. El archivo se versiona y se lee en cada sesión. Nombra la variable (JWT_SECRET), nunca su valor.
  • Reglas que no admiten excepciones. Claude puede decidir que una línea de CLAUDE.md no aplica. «Nunca leas .env» va en los permisos, donde una regla deny se cumple en todos los modos.
  • Documentación larga. Importa el README o enlázalo. Un procedimiento de varios pasos, como una release, funciona mejor como skill, que se carga solo cuando hace falta.
  • Árboles de archivos y listas de dependencias. Claude lee las carpetas y el package.json por sí mismo.
  • Preferencias personales. Van en CLAUDE.local.md.
  • Énfasis. La documentación dice que acumular IMPORTANT hace que Claude aplique de más una regla. Una línea que se ignora a menudo indica que el archivo es demasiado largo, o que la regla debería ser un hook.

En Northstack, los archivos env y los dos scripts destructivos van en .claude/settings.json. Una regla deny de Read bloquea el archivo tanto por la herramienta Read como por una lectura en la shell. Las reglas de Bash comparan el texto del comando: frenan su forma habitual, no todas las posibles:

{
  "permissions": {
    "deny": [
      "Read(**/.env)",
      "Bash(yarn drop)",
      "Bash(yarn reset)"
    ]
  }
}

Una plantilla de CLAUDE.md para empezar

Si prefieres rellenar huecos, este es el esqueleto que comparten los cuatro ejemplos. Borra cualquier apartado para el que no tengas nada cierto que escribir.

# <Project name>

<One line per app: folder, framework, port.>

## Run
- <Package manager and version; how to install.>
- <Start command for each app, in the order they must start.>

## Check your work
- <Exact typecheck, lint, build and test commands. Say so if one is missing.>

## How the apps connect
- <Env names that link them; which are compiled in; which may never hold a secret.>

## Conventions
- <Rule>, copy `<path/to/a/good/example>`.

## Gotchas
- <What fails quietly: a list to register in, a generated file, a destructive script.>

La skill gratuita: nextjs-claude-md

La skill empaqueta el método: leer los hechos, elegir los archivos, escribir solo lo que el código no muestra y comprobar. Es pública en github.com/aniq-ui-pro/agent-skills. Instálala con el CLI de skills, o copia la carpeta en .claude/skills/:

npx skills add aniq-ui-pro/agent-skills --skill nextjs-claude-md

# or copy the folder from a clone of the repository
cp -r agent-skills/skills/nextjs-claude-md .claude/skills/nextjs-claude-md

Después pide a Claude que escriba un CLAUDE.md para el proyecto, o escribe /nextjs-claude-md. El SKILL.md completo:

---
name: nextjs-claude-md
description: Drafts and checks CLAUDE.md (and AGENTS.md) files for a Next.js App Router project, with or without a NestJS API beside it. Use when a repository has no CLAUDE.md yet, when /init produced a generic one, when asked to write, update, audit or shorten CLAUDE.md or AGENTS.md, or after scripts, ports, folders or the i18n setup changed.
---

# CLAUDE.md for a Next.js (+ NestJS) project

Write instruction files from what the code does, then prove that every command
and path in them exists. Two read-only Node scripts (Node 20+, no packages):
`scripts/facts.mjs` reads package.json files, folders, `.env.example` names,
i18n and config; `scripts/check.mjs` checks a finished file.

1. **Read the facts.** At the repository root run
   `node ${CLAUDE_SKILL_DIR}/scripts/facts.mjs .`
   Check: it lists every app you expect. "Apps: 0" means the wrong folder.

2. **Look before you write.** If it reports a CLAUDE.md, AGENTS.md or rule
   files under `.claude/` already, read them and plan edits. Never overwrite one.
   Check: you can name the file each new line will go in.

3. **Choose the files.** One app: one CLAUDE.md. Several apps: a short root
   CLAUDE.md (apps, ports, run and check commands, how the apps connect, rules
   shared by all) plus one CLAUDE.md in each app folder, which Claude Code
   loads only when it works there. If the team also uses Codex, Cursor or
   Copilot, put the shared text in AGENTS.md and make CLAUDE.md `@AGENTS.md`
   followed by Claude-only lines.
   Check: no line appears in two files.

4. **Write only what the code does not show at a glance**, in this order:
   - Commands: exact script names from package.json (`dev`, `build`, `lint`,
     `typecheck`), and say so when there is no test script.
   - Ports and links between apps: env names from `.env.example`, never their
     values; which ones are compiled in (`NEXT_PUBLIC_*`).
   - Conventions, each with a real file to copy: the message file layout and
     locales; logical classes (`ms-*`, `text-start`) when a locale is RTL; the
     data chain (API client folder, query hooks); forms; exact versions when
     facts.mjs reports no ranges.
   - Gotchas that fail quietly: a namespace list, a mock that must answer, a
     schema that syncs only in development, generated files.
   - Leave out file trees, dependency lists, secrets and long docs. A rule with
     no exceptions ("never read .env") belongs in `.claude/settings.json`
     permissions, not here.
   Check: every line names a command, a path, an env name or a rule that
   someone could verify in the code.

5. **Check every file.** `node ${CLAUDE_SKILL_DIR}/scripts/check.mjs CLAUDE.md`,
   then each app's file and AGENTS.md (`--root <dir>` when the file is not in
   the project it describes).
   Check: 0 errors. Fix the file, not the checker, and read each WARN.

6. **Keep it short.** The checker fails a file over 200 lines, the length the
   Claude Code docs recommend staying under.
   Check: the line count in the checker's last line.

7. **Confirm it loads.** Ask the user to run `/context all` in a new session:
   the root file is listed under Memory files. App files load on demand, when
   Claude reads a file in that folder.
   Check: the user confirms it, or your report says it is not confirmed yet.

Report the files written, their line counts, the checker's last line for each,
and any line you were unsure of.

Los dos scripts son de solo lectura, necesitan Node 20 o superior y ningún paquete.

check.mjs comprueba que cada script citado existe en el package.json donde se ejecuta (siguiendo cd), que cada ruta y cada importación @ existen, que el archivo no pasa de 200 líneas y que nada parece una clave. Con los cuatro ejemplos informa de 0 errores, cada uno en menos de una décima de segundo:

$ for f in CLAUDE.md dashboard/CLAUDE.md back-end/CLAUDE.md AGENTS.md; do node check.mjs "$f"; done
CLAUDE.md: 41 lines, 11 commands and 6 paths checked, 0 errors, 0 warnings
dashboard/CLAUDE.md: 43 lines, 5 commands and 24 paths checked, 0 errors, 0 warnings
back-end/CLAUDE.md: 37 lines, 10 commands and 13 paths checked, 0 errors, 0 warnings
AGENTS.md: 34 lines, 8 commands and 9 paths checked, 0 errors, 0 warnings

El mismo archivo raíz copiado sin cambios en Ticketory, nuestro paquete de venta de entradas, falla de inmediato, porque los frontends de Ticketory están en storefront/ y admin-dashboard/:

$ node check.mjs CLAUDE.md
ERROR line 6: path `website/` does not exist
ERROR line 15: `yarn dev` runs in dashboard, which has no package.json
ERROR line 15: `yarn dev` runs in website, which has no package.json
ERROR line 18: `yarn typecheck` runs in dashboard, which has no package.json
ERROR line 18: `yarn lint` runs in dashboard, which has no package.json
ERROR line 18: path `website/` does not exist
CLAUDE.md: 41 lines, 11 commands and 6 paths checked, 6 errors, 0 warnings

El archivo del panel copiado en nuestro Financial Dashboard detecta una diferencia de un carácter en su primer error: esa app llama type-check a su comprobación de tipos. Los otros 13 errores son rutas que esa app no tiene.

$ node check.mjs CLAUDE.md
ERROR line 4: `yarn typecheck`: no script "typecheck" in ./package.json (did you mean "type-check"?)
ERROR line 10: path `constants/` does not exist
ERROR line 11: path `src/features/dashboard/billing/` does not exist
# 11 more path errors
CLAUDE.md: 43 lines, 5 commands and 24 paths checked, 14 errors, 0 warnings

Un CLAUDE.md copiado de cualquier sitio, incluida esta página, está mal para tu proyecto hasta que cada comando y cada ruta se hayan comprobado contra tu código.

Preguntas frecuentes

¿Claude Code lee AGENTS.md?

Sí, desde la v2.1.277, cuando no hay CLAUDE.md ni CLAUDE.local.md en tu carpeta de trabajo ni por encima. Si existe un CLAUDE.md, Claude solo lee CLAUDE.md salvo que Project instructions en /config diga otra cosa. Un CLAUDE.md que empieza con @AGENTS.md funciona en todas las versiones.

¿Dónde va CLAUDE.md en un monorepo con varias apps?

Un archivo corto en la raíz para lo que comparten todas las apps, y uno en cada carpeta de app. Los archivos de app solo se cargan cuando Claude toca un archivo de esa carpeta. En un monorepo grande, el ajuste claudeMdExcludes omite los archivos de otros equipos.

¿Hay que subir CLAUDE.md a git?

El del proyecto, sí: contiene las instrucciones comunes del equipo. Las notas personales van en CLAUDE.local.md, añadido al .gitignore, o en el CLAUDE.md de usuario dentro de la carpeta .claude de tu directorio personal. Nunca pongas un secreto en ninguno.

¿Qué hace /init si ya existe un CLAUDE.md?

Sugiere mejoras en lugar de sobrescribir el archivo. En un proyecto sin CLAUDE.md escribe un primer archivo con los comandos de build, las instrucciones de test y las convenciones que encuentra, e incorpora las reglas de Cursor y las instrucciones de Copilot si existen.

¿Puede CLAUDE.md impedir que Claude lea los archivos .env?

No de forma fiable. CLAUDE.md es contexto que Claude suele seguir, no configuración obligatoria. Una regla deny como Read(**/.env) en .claude/settings.json la aplica el propio Claude Code en todos los modos de permisos.

¿Cómo compruebo que Claude cargó mi CLAUDE.md?

Ejecuta /context all y mira en Memory files. Un CLAUDE.md de subcarpeta no aparece ahí porque se carga bajo demanda; cuando se carga, aparece en la terminal una línea con su ruta. /memory lista todas las ubicaciones de memoria y las abre en tu editor.

Northstack y las demás plantillas full stack

  • Northstack Full Stack (sitio web, panel de espacio de trabajo y API NestJS): 149 $.
  • Solo el sitio de Northstack: 39 $. Solo el panel: 49 $. Solo la API backend: 99 $.
  • Pack de 10 plantillas premium: 499 $. Northstack no forma parte del pack.

Cada licencia permite proyectos comerciales ilimitados, trabajo para clientes incluido, y cada página de plantilla muestra la oferta vigente si la hay. Ver las plantillas.

Fuentes

Documentación de Claude Code: How Claude remembers your project (ubicaciones, carga, importaciones, AGENTS.md, límites de tamaño), Best practices (qué conservar y qué quitar, /init, /doctor), Skills y Permissions. Next.js: How Next.js supports AI coding agents y la referencia de agentRules. Codex: cómo descubre AGENTS.md. Cursor: Rules. Cada cifra de esta página sale de nuestros propios repositorios, leídos el 14 de noviembre de 2026.

¿Encontró útil este artículo?

Compartir:
Boletín

Recibe un aviso cuando salga una nueva plantilla

Sé el primero en saber cuándo se publica una nueva plantilla.

  • Nuevas plantillas publicadas
  • Mira lo que se está creando y vota
  • Lanzamientos gratuitos y premium
  • Cancela la suscripción con un clic
world map

Comunidad Global de Usuarios

Únete a miles de desarrolladores en todo el mundo que confían en Aniq-UI para sus proyectos. Nuestras plantillas se utilizan en todo el mundo para crear experiencias web impresionantes.

Aniq-uiAniq-ui

Preferencias de Cookies

Utilizamos cookies para mejorar tu experiencia de navegación, analizar el tráfico del sitio y personalizar el contenido. Al hacer clic en "Aceptar Todo", consientes nuestro uso de cookies para análisis y publicidad personalizada.