Organisation d'un projet agentique

1. Introduction

#

L’organisation d’un projet agentique consiste à structurer les instructions, les compétences réutilisables, la documentation et les configurations nécessaires au fonctionnement des agents IA.

L’objectif est de permettre à un agent de :

• comprendre rapidement le projet ;
• respecter les conventions existantes ;
• identifier les procédures disponibles ;
• accéder au contexte pertinent ;
• exécuter et vérifier ses modifications.

Trois éléments jouent un rôle central :

Principe : les instructions générales doivent rester courtes ; les procédures détaillées doivent être séparées et chargées uniquement lorsque nécessaire.

2. Le fichier AGENTS.md

#

Le fichier AGENTS.md fournit des instructions persistantes aux agents intervenant sur un projet.

Il est notamment utilisé par OpenAI Codex. Sa prise en charge varie selon les autres outils.

Contenu recommandé

#

Exemple : AGENTS.md

#

# Project

Pipeline Data Engineering en Python.

## Stack

- Python 3.12
- uv
- DuckDB
- dbt
- pytest
- ruff

## Architecture

- src/ : code applicatif
- tests/ : tests automatisés
- data/raw/ : données sources
- docs/ : documentation

## Instructions

- Respecter l'architecture existante.
- Privilégier les modifications minimales.
- Ne pas ajouter de dépendances sans justification.
- Ne jamais modifier les données RAW.

## Validation

- Exécuter `uv run pytest`.
- Exécuter `uv run ruff check .`.
- Signaler les tests non exécutés ou échoués.

## Output

- Résumer les modifications.
- Indiquer les fichiers concernés.
- Présenter les résultats des vérifications.

Portée des instructions

#

Avec Codex, les instructions peuvent être définies à plusieurs niveaux :

Les fichiers locaux permettent d’ajouter des règles propres à certaines parties du projet.

Bonnes pratiques :

• Conserver un AGENTS.md racine concis.
• Éviter de recopier la documentation existante.
• Référencer les documents détaillés lorsque nécessaire.
• Ne créer des instructions locales qu’en présence de contraintes particulières.
• Ne pas considérer ce fichier comme une barrière de sécurité technique.

3. Les Skills (SKILL.md)

#

Un skill est un ensemble d’instructions réutilisables décrivant comment réaliser une tâche particulière.

Contrairement à AGENTS.md, qui définit des règles générales, un skill encapsule une procédure spécialisée.

Structure d’un skill

#

Un skill peut contenir :

Exemple : skill de validation Data

#

Emplacement Codex : .agents/skills/data-validation/SKILL.md

---
name: data-validation
description: >
  Valider un pipeline de données après modification.
  Utiliser pour contrôler les schémas, volumes
  et résultats des tests.
---

# Data Validation

1. Identifier les tables modifiées.
2. Vérifier les schémas et les contraintes.
3. Comparer les volumes avant/après.
4. Exécuter les tests disponibles.
5. Signaler les anomalies.
6. Produire un rapport synthétique.

Chargement progressif

#

Les skills peuvent utiliser le principe de Progressive Disclosure :

1. L’agent découvre les skills disponibles via leurs métadonnées.
2. Il sélectionne un skill pertinent.
3. Il charge les instructions du SKILL.md.
4. Il consulte les références ou scripts complémentaires si nécessaire.

Cette approche limite la quantité d’instructions présentes simultanément dans le contexte.

Où placer les skills ?

#

Certains outils reconnaissent plusieurs emplacements. La découverte et les règles de priorité dépendent du harness.

Un skill ne correspond pas à un agent supplémentaire. Il fournit des compétences ou procédures à un agent existant.

4. Fichiers de configuration

#

Les fichiers de configuration définissent certains paramètres techniques du harness.

Ils ne remplissent pas le même rôle que les instructions.

Exemple : configuration Codex

#

Configuration personnelle, généralement dans ~/.codex/config.toml :

model = "<model-id-supported>"

sandbox_mode = "workspace-write"
approval_policy = "on-request"

Ces paramètres illustrent :

• model : modèle utilisé par l’agent ;
• sandbox_mode : périmètre d’exécution autorisé ;
• approval_policy : politique de demande d’approbation.

Les valeurs et leur prise en charge peuvent évoluer selon la version du harness.

Les configurations techniques doivent être appliquées par l’environnement d’exécution et non uniquement décrites dans les instructions.

Gestion des secrets

#

• Ne jamais stocker de clés API dans AGENTS.md ou SKILL.md.
• Utiliser des variables d’environnement ou un gestionnaire de secrets.
• Exclure les fichiers sensibles du versionnement.
• Limiter les accès aux ressources externes.

5. Arborescence recommandée

#

Pour un projet Python utilisant Codex, une organisation simple peut suffire.

my-project/
├── AGENTS.md
├── README.md
├── pyproject.toml
├── uv.lock
│
├── .agents/
│   └── skills/
│       ├── data-validation/
│       │   └── SKILL.md
│       └── model-evaluation/
│           └── SKILL.md
│
├── src/
├── tests/
├── docs/
└── data/

Responsabilités

#

Cette organisation est une proposition et non une structure obligatoire.

Le projet peut fonctionner avec un simple AGENTS.md, sans aucun skill.

6. Organisation des tâches complexes

#

Les instructions permanentes ne doivent pas contenir l’intégralité des tâches en cours.

Pour les travaux complexes, il peut être pertinent de séparer :

• les règles permanentes ;
• les objectifs du projet ;
• le plan de réalisation ;
• les résultats et décisions précédentes.

Documents complémentaires

#

Ces fichiers ne sont pas automatiquement interprétés par tous les agents. Leur utilisation doit être prévue par les instructions ou le workflow.

Exemple : développement d’une fonctionnalité

#

1. L’agent consulte AGENTS.md.
2. Il examine le code et la documentation pertinente.
3. Il établit un plan si la tâche est complexe.
4. Il applique les modifications autorisées.
5. Il utilise les skills pertinents.
6. Il exécute les vérifications.
7. Il documente les résultats et les éventuels travaux restants.

L’objectif est de conserver un contexte exploitable, notamment lorsque le travail s’étend sur plusieurs sessions.

7. Bonnes pratiques

#

Recommandations

#

1. Commencer avec un seul AGENTS.md.
2. Ajouter des skills lorsqu’une procédure devient répétitive.
3. Séparer la documentation technique des instructions agentiques.
4. Définir les restrictions dans le harness lorsque cela est possible.
5. Versionner les instructions et skills propres au projet.
6. Vérifier que le harness reconnaît les fichiers et emplacements choisis.
7. Éviter de créer plusieurs agents sans besoin démontré.

L’organisation doit rester proportionnée à la complexité du projet.

8. Synthèse

#

L’organisation d’un projet agentique repose sur une séparation claire des responsabilités.

• AGENTS.md : règles générales et permanentes du projet.
• SKILL.md : procédures spécialisées et réutilisables.
• Configuration : paramètres techniques du harness.
• Documentation : architecture, objectifs et décisions.
• Arborescence : organisation des ressources et du code.

La structure minimale recommandée est un AGENTS.md concis, complété progressivement par des skills et des documents lorsque leur utilité apparaît.

Une organisation efficace permet aux agents de travailler avec un contexte pertinent, sans multiplier les instructions ni complexifier inutilement l’environnement.

Références

#

• OpenAI — Codex Customization
• OpenAI — Building Skills
• OpenAI — Codex Development Workflows
• VS Code — Agent Skills
• Hugging Face — Using Skills with Code Agents