Développer avec des agents IA

Chaque page est aussi servie en Markdown. Les fichiers ci-dessous donnent à un agent de code les mêmes faits que ces pages vous donnent.

Ce qui est là pour les machines

Ressource	URL	Usage
Index	https://dzbuild.dev/llms.txt	La liste des pages, une ligne chacune. Collez-la dans un chat ou pointez un agent dessus.
Site entier	https://dzbuild.dev/llms-full.txt	Toutes les pages dans un seul fichier Markdown.
Une page en Markdown	l'URL de la page suivie de .md, par exemple https://dzbuild.dev/fr/oauth.md	Une page sans navigation. Les pages arabes et anglaises fonctionnent de la même façon sous /ar/ et à la racine.
Compétence agent	https://dzbuild.dev/skills/dzbuild-apps/SKILL.md	Les faits et les règles dont un agent a besoin pour construire une application DZBuild.
Modèle AGENTS.md	https://dzbuild.dev/agents/AGENTS.md	Un fichier de départ pour le dépôt de votre application.
Description OpenAPI	https://dzbuild.dev/openapi/dzbuild-apps-v1.json	Chaque opération qu'un jeton d'installation peut appeler, avec ses paramètres, ses scopes et la forme de ses réponses.
Application exemple	dzbuild-app-starter	Trois presets Cloudflare Worker et un exemple Node.js, chacun avec ses tests.

Chaque page HTML porte aussi <link rel="alternate" type="text/markdown"> vers son jumeau Markdown, pour qu'un outil qui lit la page trouve seul la version brute.

Donnez la compétence à votre agent

Le fichier de compétence suit le format Agent Skills : une courte description qui dit à l'agent quand l'utiliser, puis les instructions. Claude Code lit les compétences dans .claude/skills/ de votre projet ou dans ~/.claude/skills/ sur votre machine :

mkdir -p .claude/skills/dzbuild-apps
curl -sSf https://dzbuild.dev/skills/dzbuild-apps/SKILL.md -o .claude/skills/dzbuild-apps/SKILL.md

Pour les agents qui lisent un AGENTS.md à la racine du dépôt (Codex, Cursor et d'autres), partez du modèle et gardez vos propres règles de projet en dessous :

curl -sSf https://dzbuild.dev/agents/AGENTS.md -o AGENTS.md

Les deux fichiers reprennent les règles de ce site, pour que votre agent travaille à partir des mêmes faits que vous.

Donnez la documentation à votre agent comme serveur MCP

@dzbuild/docs-mcp donne à tout client MCP ces pages et la référence de l'API, lues depuis dzbuild.dev, sans aucun identifiant. La page /agents/connect donne la commande ou la configuration pour Claude Code, Codex, Cursor et Claude Desktop.

Poser une question sur une page

Sous chaque page, une barre propose Voir en Markdown, Copier le Markdown, Ouvrir dans ChatGPT et Ouvrir dans Claude. Les deux derniers ouvrent un nouveau chat qui commence par lire cette page. Le message envoyé est :

Read https://dzbuild.dev/fr/oauth.md so I can ask questions about it.

Pour une tâche plutôt qu'une question, donnez à l'agent l'index et la compétence ensemble, puis décrivez ce que l'application fait pour le marchand :

Read https://dzbuild.dev/llms.txt and https://dzbuild.dev/skills/dzbuild-apps/SKILL.md.
Build a DZBuild app in Node.js that installs on a store through the OAuth flow,
stores one token per store, verifies webhooks, and posts a message to our Slack
channel when an order is confirmed. Secrets come from environment variables.

Générer un client depuis la description OpenAPI

La description est au format OpenAPI 3.1. Importez-la dans Postman ou Insomnia, ou générez des types et un client :

curl -sO https://dzbuild.dev/openapi/dzbuild-apps-v1.json
npx openapi-typescript dzbuild-apps-v1.json -o dzbuild-apps-v1.d.ts

Le schéma de sécurité dzOAuth du fichier liste chaque scope avec sa description. Le fichier déclare https://api.dzbuild.app comme serveur, l'hôte que votre application appelle.

Gardez les secrets hors du chat

Un agent a seulement besoin de savoir qu'un secret existe, jamais sa valeur.

• Le secret client, le secret de signature et chaque jeton d'installation vivent dans des variables d'environnement ou un coffre de secrets sur votre serveur. Ne les collez pas dans un message, un dépôt ou une ligne de journal.
• Si un secret atteint un chat ou un commit, régénérez-le dans la console développeur. L'ancien secret client s'arrête aussitôt ; les jetons déjà émis continuent de fonctionner, et renouveler le secret de signature le change pour toutes les installations à la fois : déployez la nouvelle valeur tout de suite.
• Un agent ne doit pas se connecter au tableau de bord DZBuild à la place du marchand, le scripter, ni aspirer les pages des boutiques. Les données de boutique passent uniquement par l'API REST et les webhooks, comme le disent les règles de sécurité.
• Les adresses de redirection sont comparées caractère par caractère. Enregistrez dans la console l'adresse exacte que votre code envoie, en https, avec la même barre oblique finale.

Ce que les assistants se trompent sans la documentation

Ces erreurs reviennent souvent quand une application est écrite à partir de connaissances générales sur OAuth ou les webhooks. Les pages liées tranchent chacune.

• Attendre expires_in et un jeton de rafraîchissement. Les jetons d'installation n'ont ni l'un ni l'autre ; ils fonctionnent jusqu'à ce que le marchand désinstalle ou réinstalle. Voir Concepts clés.
• Envoyer une écriture sans Idempotency-Key. POST, PATCH et DELETE répondent 400 sans elle. Voir Limites de requêtes.
• Analyser le corps du webhook avant de vérifier la signature. Le HMAC couvre les octets bruts, un corps re-sérialisé ne correspond donc jamais. Voir Webhooks.
• Enregistrer le webhook via POST /v1/webhooks. Les applications y reçoivent 403 ; l'URL de webhook se règle une fois sur l'application dans la console. Voir Référence de l'API.
• Demander tous les scopes. Le marchand voit une ligne par ressource sur l'écran de consentement, et la vérification compare les scopes avec ce que la fiche dit de l'application. Voir Scopes.
• Construire un sélecteur de boutique dans un seul jeton. Un jeton n'atteint que sa boutique ; utilisez le jeton de chaque boutique depuis la liste stores de la réponse du jeton. Voir OAuth.