A few well-placed lines in a CLAUDE.md or AGENTS.md file are enough to transform the quality of the code produced by an AI agent. Method, pitfalls to avoid and example.
By default, code brokers produce generic code that is poorly adapted to the context of an existing project. To guide the AI precisely, the CLAUDE.md file, or AGENTS.md for other code agents on the market, plays a key role. Loaded before each new conversation, it allows you to configure the coding standards, the expected quality level, the orders specific to your project or even the security rules to respect. How to structure it? What should you put there? Answer.
A file written in natural language, short and understandable
As a reminder, CLAUDE.md can only be used with Anthropic’s code agent, Claude Code. The AGENTS.md file, launched by OpenAI, has become an almost universal standard, adopted by most code agents on the market (Codex, Cursor, Aider, Jules, Factory, etc.). The advice given in this article, although it applies primarily to CLAUDE.md, remains valid for AGENTS.md.
In its documentation, Anthropic specifies that the CLAUDE.md file must be written entirely in natural language. It must remain short, to avoid drowning the agent in unnecessary complexities, and structured in sections. Only the general instructions applicable to all of the code in your project should appear there. For rules specific to a sub-project, prefer skills or CLAUDE.md files nested at the level of the sub-folder concerned. Anthropic also recommends avoiding overly general instructions, which do not provide anything that Claude could not have deduced for himself by reading your code.
If certain instructions in your CLAUDE.md, for example prohibitions, are not respected by Claude, this is generally due to two causes. The first: the file is much too long. Cut it down to keep only the essentials. The second: the instructions are formulated imprecisely or ambiguously. Rewrite them. Anthropic also recommends adding emphasis markers to prioritize instructions and emphasize the most critical ones. Examples: “VERY IMPORTANT” before a crucial rule, or “YOU MUST DO X OR Y”. Claude’s editor finally recommends treating CLAUDE.md like code: modify, test in Claude, iterate. It is at this price that you will obtain the best result.
Instructions to avoid and those to specify
Instructions to ban
As we have just seen, imprecise and overly general instructions must absolutely be banned. No instructions that Claude can understand natively by analyzing your system or code base. No standard coding convention that it is likely to know by default. Another example: don’t detail how a well-documented API or service works. No information likely to change during the project either, otherwise these instructions will become obsolete; you will forget them in your CLAUDE.md, but not Claude, who will continue to apply them. No tutorial or long code explanation. Finally, and this is notable, because it has been widely disseminated advice until now, including by some publishers themselves: avoid purely rhetorical prescriptive formulations as much as possible. No more “Write clean code”, “don’t make any mistakes”, “don’t forget to comment on the code”…
Instructions to add
The list of instructions to avoid is certainly long. But what should you put in CLAUDE.md? Add anything Claude can’t guess about himself. Bash commands specific to your project? Add them. Coding conventions specific to your company? Write them down. Also specify all naming conventions, your graphic charter, your code review rules and your internal security requirements. The development environment (specific versions of packages, hardware or network constraints, etc.), if complex or atypical, can also be documented. Also mention the architectural choices of your project if they deviate significantly from current practices. Finally, if you notice recurring errors from Claude on the same point, add an instruction in CLAUDE.md to indicate the expected behavior.
The CLAUDE.md file also allows you to include references to local files or online resources. You can therefore point, for example, to the internal documentation of your project so that Claude consults it before each conversation. Example: “look in /var/www/html/monprojet/documentation.md to understand the whole project”.
JDN advice for your CLAUDE.md
Once the generic but very useful advice has been given, here are some recommendations gleaned after almost a year of practicing Claude Code. We advise you to at least add to your CLAUDE.md:
- the desired or already applied graphic charter (without explicit instructions, Claude generates generic designs);
- the desired documentation choices (so that Claude completes your documentation with each addition or modification of functionality);
- the development of systematic unit tests for each modification or addition of structural code;
- the development of UX tests with Playwright on critical processes (authentication, payment, forms);
- the audit by sub-agents of the structural code produced, broken down into three stages: functional, quality and security;
- for personal projects only: the systematic atomic commit after code review, and the manual push at the end of a coherent unit of work on the GitHub repository.
Based on these tips, here is a CLAUDE.md good quality according to our feedback:
## Contexte projet [Une à trois phrases : nature du projet, stack, environnement de déploiement.] ## Environnement - Versions imposées : [Node X, Python X, etc.] - Contraintes spécifiques : [VPS, RAM, réseau…] ## Charte graphique - Palette : principale `[#XXXXXX]`, secondaire `[#XXXXXX]`, accent `[#XXXXXX]` - Typographies : titres `[police]`, corps `[police]` TRÈS IMPORTANT : ne jamais générer de design générique. Respecter strictement la charte. ## Documentation interne A chaque ajout ou modification fonctionnelle, mettre à jour la documentation correspondante dans `/docs`. Format : Markdown. ## Tests unitaires VOUS DEVEZ écrire un test unitaire pour chaque ajout ou modification de code structurel. Framework imposé : [Jest / Vitest / Pytest]. ## Tests d'UX VOUS DEVEZ tester l’UX avec Playwright sur l’ensemble des modifications susceptibles d’impacter l’UI. ## Audit par sous-agents Pour tout code structurel produit, déclencher trois passes : 1. Audit fonctionnel : le code fait-il ce qu'il doit ? 2. Audit qualité : lisibilité, duplications, conventions. 3. Revue sécuritaire : vulnérabilités, validation, gestion d'erreurs. ## Git (projets personnels uniquement) Après revue du code, push systématique des modifications sur le dépôt GitHub. ## Problèmes récurrents [A enrichir au fil du projet. Exemples : ne met JAMAIS de tokens d’API en dur dans le code, toujours en env]
This model will not necessarily correspond to your project: it is up to you to adapt it to your needs. As with prompt engineering, handling CLAUDE.md or AGENTS.md is a process of continuous iteration. Also pay attention to model version changes, whether at Anthropic or elsewhere: it is often useful to take back your CLAUDE.md on this occasion. Weight changes between two versions significantly vary the way the model adheres to your instructions (called prompt adhesion). Finally, final advice: Claude is only an executor, you must remain in the position of the order giver. The AI only applies your instructions; context engineering and prompt engineering are what differentiate a good developer with Claude Code from a beginner.
