AI Coding Agents

Exemples de CLAUDE.md tirés de 28 apps Next.js et NestJS en production (2026)

Quatre exemples de CLAUDE.md à copier, tirés de 28 apps Next.js et NestJS : racine, Next.js, NestJS et AGENTS.md, et un skill gratuit qui vérifie le vôtre.

Par Aniq-UI16 novembre 202629 min de lecture
Partager:
Exemples de CLAUDE.md tirés de 28 apps Next.js et NestJS en production (2026)
#Claude Code#CLAUDE.md#AGENTS.md#Next.js#NestJS#AI coding agents#Claude Code skills#next-intl

Les exemples de CLAUDE.md qui valent la peine d'être copiés sont courts et précis : les commandes, les ports et les conventions exacts d'un vrai projet, bien en dessous de 200 lignes, sans rien que Claude pourrait apprendre en ouvrant les dossiers. Les arborescences et les listes de dépendances coûtent du contexte à chaque session et n'apprennent rien à Claude.

Cette page donne quatre exemples de CLAUDE.md écrits à partir du code des 28 apps Next.js et NestJS que nous livrons : un fichier racine, une app Next.js, une API NestJS et un AGENTS.md pour Codex et Cursor. Chaque ligne est expliquée, et un skill gratuit, à la fin, rédige ces fichiers depuis votre code puis les vérifie.

Ce qui a sa place dans un CLAUDE.md

Anthropic présente CLAUDE.md comme l'endroit où écrire ce que vous réexpliqueriez à chaque session. Claude le lit au début de chaque session comme du contexte, pas comme une configuration imposée. Une ligne vérifiable vaut donc mieux qu'une ligne vague : « lancez yarn typecheck » vaut mieux que « testez vos changements ».

La page des bonnes pratiques précise encore. Gardez les commandes qui confirment le travail, les endroits où le code induit en erreur, les décisions qui ne figurent nulle part dans le dépôt et tout ce que vous avez déjà dû corriger deux fois. Retirez la visite de l'architecture et l'arborescence, car, selon la doc, Claude lit le dépôt lui-même.

Beaucoup d'exemples de la première page de résultats sont écrits pour un projet imaginaire plutôt que tirés d'un vrai. Chaque ligne des nôtres nomme un vrai script, un vrai fichier à copier ou un vrai piège, et chaque fichier passe un vérificateur lancé sur le code qu'il décrit.

Vous pouvez partir de /init, qui écrit un premier CLAUDE.md depuis votre code, ou propose des améliorations s'il en existe déjà un. Avec CLAUDE_CODE_NEW_INIT=1, il demande quels fichiers préparer (CLAUDE.md, skills, hooks) et montre une proposition avant d'écrire. Ensuite, dit la doc, le travail consiste surtout à retirer des lignes.

Où vivent les fichiers CLAUDE.md et quand ils se chargent

  • Politique gérée : /Library/Application Support/ClaudeCode/CLAUDE.md sur macOS, /etc/claude-code/CLAUDE.md sur Linux. Définie par une organisation.
  • Utilisateur : CLAUDE.md dans le dossier .claude de votre répertoire personnel. Vos préférences, dans tous les projets.
  • Projet : ./CLAUDE.md ou ./.claude/CLAUDE.md. Versionné et partagé.
  • Local : ./CLAUDE.local.md. Vos notes pour un projet, hors de git.

Les fichiers du dossier où vous lancez Claude, et de chaque dossier au-dessus, se chargent au démarrage. Ils s'additionnent sans s'écraser, et le fichier le plus proche de vous est lu en dernier. Si deux fichiers se contredisent, Claude peut suivre l'un ou l'autre : une règle doit donc vivre à un seul endroit.

Un CLAUDE.md placé dans un sous-dossier ne se charge que lorsque Claude lit, écrit ou modifie un fichier de ce dossier. C'est pourquoi nos exemples sont découpés par app : le fichier racine reste court, les règles du dashboard arrivent quand Claude ouvre un fichier du dashboard, et une session sur l'API ne les porte jamais.

Une ligne comme @AGENTS.md importe un autre fichier, jusqu'à quatre niveaux, mais n'économise aucun contexte, car le fichier importé se charge avec celui qui le cite. Les fichiers de règles du dossier rules dans .claude peuvent porter une liste paths et ne se charger que lorsque Claude touche un fichier correspondant. Celui-ci protège les fichiers de messages des deux 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.

Pour voir ce qui est chargé, lancez /context all et regardez sous Memory files. Les commentaires HTML d'un CLAUDE.md sont retirés avant que Claude ne le lise : c'est un endroit gratuit pour des notes destinées aux mainteneurs.

Comment nous avons écrit ces exemples de CLAUDE.md : un script sur 28 apps

Nous avons écrit un petit script Node en lecture seule, facts.mjs, qui lit le package.json de chaque app, les noms de son .env.example, ses dossiers, ses fichiers de messages et sa configuration. Nous l'avons lancé sur les 12 dépôts que nous vendons : 28 apps, 19 sur Next.js 16 et 9 sur NestJS 10 à 12.

Une règle n'entrait dans les exemples que si le code la confirmait. Le 14 novembre 2026, le script a trouvé :

  • 0 package.json sur 28 contient une plage de versions. Chaque dépendance, résolution et override est exacte.
  • Les 28 apps utilisent Yarn 4, et chacune a un .env.example (376 noms de variables au total).
  • Les 19 apps Next.js utilisent next-intl avec messages/<namespace>/<locale>.json en anglais et en arabe, un segment [locale] et src/proxy.ts : 640 fichiers de messages dans 158 namespaces.
  • 16 sur 19 gardent leurs endpoints dans src/lib/api et les lisent via des hooks TanStack Query dans src/services. Les 19 construisent leurs formulaires avec react-hook-form et zod.
  • Sur 6 969 fichiers de composants : 3 467 classes de côté logiques (ms-, start-, text-start) et 189 physiques (ml-, left-). Beaucoup des 189 sont du positionnement comme left-1/2, qui se lit pareil dans les deux sens.
  • Les 9 API NestJS répondent sous /api avec une ValidationPipe globale en whitelist, et synchronisent le schéma en développement seulement. 8 sur 9 n'ont pas de dossier de migrations.
  • 0 app sur 28 a un script test. 17 des 19 apps Next.js appellent leur vérification de types typecheck, une l'appelle type-check, une n'en a pas.

Ce dernier point compte. Un CLAUDE.md qui dit « lancez les tests » dans un projet sans script de test envoie Claude vers une commande qui échoue à chaque session. Les nôtres disent qu'il n'y a pas de suite de tests et nomment les vérifications qui existent. Voici la sortie réelle sur le code source 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...)

Exemple de CLAUDE.md n° 1 : la racine d'un produit Next.js et NestJS

Le fichier racine se charge dans chaque session lancée n'importe où dans le dépôt. Il contient ce que les trois apps partagent : où elles sont, comment les lancer et les vérifier, comment elles se relient, et les règles qu'aucune ne doit enfreindre. 41 lignes, 2 075 caractères.

# 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.

Pourquoi chaque ligne est là

  • Apps et ports : tirés de chaque package.json (next dev -p 3030, un script qui lit PORT dans le dashboard) et de PORT=8000 dans le .env.example de l'API. Le port par défaut de Next.js, 3000, n'est utilisé par aucune.
  • Pas npm : chaque app déclare yarn@4.8.1 et versionne un yarn.lock. Un autre outil écrirait un second fichier de verrouillage.
  • L'API d'abord : l'ordre du README. Le dashboard lit chaque écran depuis l'API, et /api/health indique qu'elle est prête.
  • Pas de typecheck dans l'API, pas de tests : d'après les listes de scripts. yarn build lance nest build, qui échoue sur une erreur de type.
  • CORS_ORIGIN : src/main.ts la passe à app.enableCors. Un frontend dont l'adresse manque ne peut pas appeler l'API depuis un navigateur.
  • Valeurs NEXT_PUBLIC_ : le .env.example du dashboard précise qu'elles sont intégrées au build et ne doivent jamais contenir de secret.
  • Mode données d'exemple : un NEXT_PUBLIC_API_BASE_URL vide fait passer un frontend sur son mock dans le navigateur. Aucun nom de dossier ne le dit.
  • Versions exactes : 0 plage dans 28 apps. Une ligne empêche yarn add d'écrire le premier caret.
  • Arabe et classes logiques : le dashboard Northstack compte 303 classes de côté logiques pour 1 physique.
  • Marqueurs de région : yarn remove:demo et yarn remove:mock suppriment les blocs marqués. Un marqueur perdu d'un côté casse la suppression.
Page d'accueil du site Northstack en thème sombre, l'app Next.js sur le port 3030 que décrit l'exemple de CLAUDE.md racine
Le site Northstack, l'app que le fichier racine place sur le port 3030.

Exemple n° 2 : un CLAUDE.md pour un projet Next.js (App Router et next-intl)

Ce fichier se trouve dans dashboard/ et ne se charge que lorsque Claude travaille sur un fichier du dashboard. Un projet Next.js App Router porte plus de conventions discrètes qu'une API : c'est le plus utile des quatre. 43 lignes.

# 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.

Pourquoi chaque ligne est là

  • La page compose, la feature porte la logique : src/app/[locale]/dashboard/billing/page.tsx importe ses composants et useBillingPage depuis la feature billing. Un dossier à copier est plus clair qu'un modèle décrit.
  • src/components/ui/ contient 44 composants et dossiers partagés. La ligne y envoie Claude avant qu'il n'écrive une modale de plus.
  • L'alias @/ : eslint.config.mjs active no-relative-import-paths avec allowedDepth: 2.
  • La chaîne de données : billingApi.ts, puis useBilling.ts, useBillingActions.ts et billingKeys.ts. 16 de nos 19 apps Next.js la suivent.
  • Le handler du mock : pour une route inconnue, le mock écrit « No mock handler » et répond 404. Un nouvel endpoint sans handler marche avec l'API et échoue en mode données d'exemple.
  • La liste des namespaces : le layout du dashboard ne charge que les namespaces de DASHBOARD_NAMESPACES. Un dossier absent de la liste n'arrive jamais à la page, qui affiche alors des clés au lieu du texte.
  • Validation traduite : billingEmailSchema(t) construit son schéma zod à partir des messages de billing, donc les erreurs s'affichent aussi en arabe.
  • Direction : src/app/layout.tsx pose dir sur <html> selon la locale, et useDirection() sert le code qui doit s'inverser, comme un graphique.
  • agentRules : depuis Next.js 16.3, next dev écrit un bloc géré dans AGENTS.md quand il détecte un agent de code, qui pointe vers la doc fournie dans node_modules/next/dist/docs/. Nos 19 apps Next.js mettent agentRules: false. Si vous le gardez, versionnez le bloc.
Page de facturation du dashboard Northstack en thème sombre, avec l'offre, les jauges d'usage et l'historique des factures, construite depuis le dossier de feature billing que le CLAUDE.md Next.js demande de copier
La page de facturation : le dossier de feature que le fichier Next.js désigne comme modèle.
Vue d'ensemble de l'espace de travail Northstack en arabe, de droite à gauche, en thème sombre, avec la barre latérale à droite et les graphiques inversés
Le même dashboard en arabe : les classes logiques placent la barre latérale à droite sans seconde feuille de style.

Exemple n° 3 : un CLAUDE.md pour une API NestJS

Le fichier de l'API fait 37 lignes. Il énonce les règles qui vivent dans main.ts, app.module.ts et les scripts de base de données, que Claude ne voit que s'il ouvre ces fichiers en premier.

# 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.

Pourquoi chaque ligne est là

  • Pas de script typecheck ni test : la liste de scripts plus haut. yarn build est la seule vérification de types.
  • SQLite ou MySQL : app.module.ts choisit le pilote selon DB_TYPE.
  • Pas de migrations : synchronize vaut true en développement seulement, et le README dit de sauvegarder puis lancer yarn schema:prod après une mise à jour qui change les tables. « Ajoute une colonne » a deux réponses plausibles avec TypeORM ; le fichier dit laquelle s'applique.
  • reset et drop : ils vident ou suppriment toutes les tables. Une ligne de CLAUDE.md reste un conseil ; le vrai verrou est une règle deny, plus bas.
  • Dossiers de modules : src/modules/ en contient 22. Billing sépare controllers/, services/, providers/, entities/ et dto/.
  • /api et la ValidationPipe : src/main.ts pose le préfixe et une pipe globale avec forbidNonWhitelisted : un champ de DTO sans décorateur reçoit un 400.
  • La forme des réponses : response.interceptor.ts enveloppe tout résultat qui n'est pas { success, data, message }, et les deux frontends lisent cette forme.
  • Guards : projects.controller.ts utilise WorkspaceGuard et @WorkspacePermissions('projects.read') sur chaque handler.
  • Les textes de l'API : 9 namespaces en en et ar dans src/i18n/translations/.
  • Contrôle d'env et export du mock : env-check.ts refuse un démarrage en production avec le secret d'exemple ; export-mock.mjs écrit les données d'exemple des deux frontends depuis l'API en marche.
Page projet de Northstack en thème sombre avec un tableau de tâches en quatre colonnes, servi par les modules projects et tasks de l'API NestJS
Un projet et son tableau de tâches, servis par les modules projects et tasks de l'API.
Matrice des rôles et permissions de Northstack en thème sombre, avec les colonnes owner, admin, member et billing liées aux clés de permission que vérifie l'API
La matrice des rôles : chaque case est une clé de permission que l'API vérifie sur ses routes.

Exemple n° 4 : AGENTS.md pour Codex, Cursor et Claude Code

AGENTS.md est le fichier markdown simple que lisent Codex, Cursor et GitHub Copilot. Codex descend de la racine du projet jusqu'au dossier courant, un fichier par dossier, et cesse d'en ajouter à 32 Kio par défaut. Cursor le lit à la racine et dans les sous-dossiers, le fichier le plus précis l'emportant.

Claude Code le lit aussi. Depuis la v2.1.277, Claude lit AGENTS.md quand aucun CLAUDE.md ni CLAUDE.local.md n'existe dans le dossier de travail ou au-dessus. Quand les deux existent, il ne lit que CLAUDE.md, sauf si Project instructions vaut claude-md-and-agents-md dans /config.

Une équipe sur plusieurs outils garde donc une seule source : le texte commun dans AGENTS.md, et à côté un CLAUDE.md qui l'importe et ajoute les lignes propres à Claude. Selon la doc, l'import ne fait jamais lire le fichier deux fois, et il marche aussi dans les sessions qui ne lisent pas AGENTS.md directement.

# 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.

Le CLAUDE.md à côté, six lignes :

@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.

Pourquoi chaque ligne est là

  • Un fichier pour trois apps : Codex et Cursor ne voient jamais les fichiers de sous-dossier de Claude, donc ce fichier condense les trois exemples en 34 lignes. Les deux outils lisent aussi des AGENTS.md imbriqués.
  • La ligne sur la doc Next.js : Next.js 16.2 et suivants fournissent une doc qui correspond à la version installée. Nos apps désactivent le bloc géré, donc le lien est écrit à la main.
  • Never : deux règles sans exception. Dans Claude Code, une règle qui doit tenir à chaque fois va dans les réglages, comme plus bas.
  • L'import : la doc montre exactement ce modèle. Un lien symbolique (ln -s AGENTS.md CLAUDE.md) marche aussi, sauf sur les clones Windows où Git le récupère comme un fichier texte d'une ligne.

Quelle longueur pour un CLAUDE.md ?

Anthropic recommande moins de 200 lignes par fichier : un fichier plus long consomme plus de contexte et est moins bien suivi. Claude Code avertit au démarrage quand un fichier dépasse cette longueur et ignore tout fichier de plus de 4 Mio. Avec une fenêtre de 200K, les fichiers de sous-dossier et les règles à chemins sont coupés à 40 000 caractères.

Les nôtres font 41, 43, 37 et 34 lignes, 7 828 caractères pour les quatre. Quand un fichier grossit, /doctor propose des coupes, et /doctor prompt-audit signale les lignes qui visent des fichiers absents ou se contredisent.

Ce qu'il ne faut pas mettre dans CLAUDE.md

  • Des secrets. Le fichier est versionné et lu à chaque session. Nommez la variable (JWT_SECRET), jamais sa valeur.
  • Des règles qui ne plient pas. Claude peut juger qu'une ligne de CLAUDE.md ne s'applique pas. « Ne lis jamais .env » va dans les permissions, où une règle deny tient dans tous les modes.
  • De longues docs. Importez le README ou mettez un lien. Une procédure en plusieurs étapes, comme une release, marche mieux en skill, chargé seulement au besoin.
  • Des arborescences et des listes de dépendances. Claude lit lui-même les dossiers et le package.json.
  • Des préférences personnelles. Elles vont dans CLAUDE.local.md.
  • De l'emphase. La doc dit qu'empiler des IMPORTANT pousse Claude à surappliquer une règle. Une ligne souvent ignorée signifie que le fichier est trop long, ou que la règle devrait être un hook.

Pour Northstack, les fichiers env et les deux scripts destructeurs vont dans .claude/settings.json. Une règle deny sur Read bloque le fichier par l'outil Read comme par une lecture en shell. Les règles Bash comparent le texte de la commande : elles arrêtent sa forme habituelle, pas toutes les formes possibles :

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

Un template de CLAUDE.md pour démarrer

Si vous préférez remplir des blancs, voici le squelette commun aux quatre exemples. Supprimez toute rubrique pour laquelle vous n'avez rien de vrai à écrire.

# <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.>

Le skill gratuit : nextjs-claude-md

Le skill reprend la méthode : lire les faits, choisir les fichiers, n'écrire que ce que le code ne montre pas, puis vérifier. Il est public sur github.com/aniq-ui-pro/agent-skills. Installez-le avec le CLI skills, ou copiez le dossier dans .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

Demandez ensuite à Claude d'écrire un CLAUDE.md pour le projet, ou tapez /nextjs-claude-md. Le SKILL.md complet :

---
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.

Les deux scripts sont en lecture seule, demandent Node 20 ou plus et aucun paquet.

check.mjs vérifie que chaque script cité existe dans le package.json où il s'exécute (en suivant cd), que chaque chemin et chaque import @ existe, que le fichier reste sous 200 lignes et que rien ne ressemble à une clé. Sur les quatre exemples, il rapporte 0 erreur, en moins d'un dixième de seconde chacun :

$ 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

Le même fichier racine copié tel quel dans Ticketory, notre pack de billetterie, échoue aussitôt, car les frontends de Ticketory sont dans storefront/ et 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

Le fichier du dashboard copié dans notre Financial Dashboard repère une différence d'un caractère dès sa première erreur : cette app appelle sa vérification de types type-check. Les 13 autres erreurs sont des chemins que cette app n'a pas.

$ 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 copié d'ailleurs, y compris de cette page, est faux pour votre projet tant que chaque commande et chaque chemin n'ont pas été vérifiés contre votre code.

FAQ

Claude Code lit-il AGENTS.md ?

Oui, depuis la v2.1.277, quand aucun CLAUDE.md ni CLAUDE.local.md n'existe dans votre dossier de travail ou au-dessus. Quand un CLAUDE.md existe, Claude ne lit que CLAUDE.md, sauf réglage contraire de Project instructions dans /config. Un CLAUDE.md qui commence par @AGENTS.md fonctionne avec toutes les versions.

Où placer CLAUDE.md dans un monorepo à plusieurs apps ?

Un fichier court à la racine pour ce que toutes les apps partagent, et un dans chaque dossier d'app. Les fichiers d'app ne se chargent que lorsque Claude touche un fichier de ce dossier. Dans un grand monorepo, le réglage claudeMdExcludes ignore les fichiers des autres équipes.

Faut-il versionner CLAUDE.md dans git ?

Le fichier du projet, oui : il porte les instructions communes de l'équipe. Les notes personnelles vont dans CLAUDE.local.md, ajouté au .gitignore, ou dans le CLAUDE.md utilisateur du dossier .claude de votre répertoire personnel. N'y mettez jamais de secret.

Que fait /init si un CLAUDE.md existe déjà ?

Il propose des améliorations au lieu d'écraser le fichier. Sur un projet sans CLAUDE.md, il écrit un premier fichier avec les commandes de build, les instructions de test et les conventions qu'il trouve, en reprenant les règles Cursor et les instructions Copilot s'il y en a.

CLAUDE.md peut-il empêcher Claude de lire les fichiers .env ?

Pas de façon fiable. CLAUDE.md est un contexte que Claude suit en général, pas une configuration imposée. Une règle deny comme Read(**/.env) dans .claude/settings.json est appliquée par Claude Code lui-même dans tous les modes de permission.

Comment vérifier que Claude a chargé mon CLAUDE.md ?

Lancez /context all et regardez sous Memory files. Un CLAUDE.md de sous-dossier n'y figure pas, car il se charge à la demande ; quand il se charge, une ligne avec son chemin apparaît dans le terminal. /memory liste tous les emplacements de mémoire et les ouvre dans votre éditeur.

Northstack et les autres templates full stack

  • Northstack Full Stack (site web, dashboard d'espace de travail et API NestJS) : 149 $.
  • Site Northstack seul : 39 $. Dashboard seul : 49 $. API backend seule : 99 $.
  • Pack de 10 templates premium : 499 $. Northstack ne fait pas partie du pack.

Chaque licence couvre un nombre illimité de projets commerciaux, travail client compris, et chaque page de template affiche l'offre en cours s'il y en a une. Parcourir les templates.

Sources

Documentation de Claude Code : How Claude remembers your project (emplacements, chargement, imports, AGENTS.md, limites de taille), Best practices (quoi garder et couper, /init, /doctor), Skills et Permissions. Next.js : How Next.js supports AI coding agents et la référence agentRules. Codex : découverte des AGENTS.md. Cursor : Rules. Chaque chiffre de cette page vient de nos propres dépôts, lus le 14 novembre 2026.

Cet article vous a été utile?

Partager:
Newsletter

Soyez prévenu quand un nouveau template sort

Soyez le premier informé de la sortie d'un nouveau template.

  • Nouveaux templates publiés
  • Voyez ce qui se prépare et votez
  • Sorties gratuites et premium
  • Désinscription en un clic
world map

Communauté Mondiale d'Utilisateurs

Rejoignez des milliers de développeurs à travers le monde qui font confiance à Aniq-UI pour leurs projets. Nos modèles sont utilisés partout dans le monde pour créer des expériences web impressionnantes.

Aniq-uiAniq-ui

Préférences des Cookies

Nous utilisons des cookies pour améliorer votre expérience de navigation, analyser le trafic du site et personnaliser le contenu. En cliquant sur "Accepter Tout", vous consentez à notre utilisation des cookies pour l'analyse et la publicité personnalisée.