0Pricing
AI Agents · Leçon

Un agent explicateur de code

Construisez un agent qui lit des fichiers source, demande au LLM une explication et renvoie une documentation en Markdown.

Un agent explicateur de code est une leçon AI Agents gratuite sur CoddyKit. Ceci est la leçon 2 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage AI Agents, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours AI Agents comprend 4 leçons au total.

Certaines parties de cette leçon n'ont pas encore été traduites et s'affichent en anglais.

Objectif du projet

Créez un agent qui prend un fichier source (Python, JS ou autre) et renvoie une documentation Markdown : objectif, fonctions principales et exemple d’utilisation.

Pourquoi est-ce utile ?

Générer de la documentation à partir de code est l’un des cas d’utilisation les plus fiables des LLM : le code est structuré, la tâche est délimitée et la sortie est lue par des humains, de sorte que les erreurs mineures sont tolérables.

Architecture

  1. Lire le fichier source
  2. Le découper éventuellement par classe ou fonction
  3. Pour chaque segment, demander au LLM de fournir une explication
  4. Combiner le tout dans un document Markdown

Step 1: Read the File

import sys

with open('example.py', 'w') as f:
    f.write('print("hello")\n')

path = sys.argv[1] if len(sys.argv) > 1 else 'example.py'
with open(path) as f:
    code = f.read()
print(f'Read {len(code)} characters from {path}')

Step 2: Prompt for Documentation

from openai import OpenAI
oai = OpenAI()

prompt = f'''
You are a senior engineer writing developer-friendly docs.

Given this source file, produce a Markdown document with:
# {path}

## Purpose
(One paragraph)

## Public API
(Each function/class with one-line description)

## Usage Example
(One short, runnable snippet)

Source:
```
{code}
```
'''

response = oai.chat.completions.create(
    model='gpt-4o-mini',
    messages=[{'role': 'user', 'content': prompt}],
    temperature=0.2,
)
print(response.choices[0].message.content)

Gérer les fichiers longs

Si le fichier est trop long, découpez-le par fonction et expliquez chaque fonction séparément :

import ast

tree = ast.parse(code)
functions = [node for node in ast.walk(tree) if isinstance(node, ast.FunctionDef)]

for func in functions:
    snippet = ast.unparse(func)
    explain(snippet)

Étape 3 : Combiner les sorties

Pour les exécutions sur plusieurs segments, assemblez les explications de chaque fonction dans un seul document :

docs = []
for func_name, snippet in functions:
    explanation = explain(snippet)
    docs.append(f'### {func_name}\n\n{explanation}\n')

full_doc = '\n'.join(docs)
open('docs.md', 'w').write(full_doc)

Ajouter un résumé au niveau du projet

Après les explications de chaque fonction, demandez au LLM une vue d’ensemble :

summary_prompt = 'Summarise the purpose of this package in 3 sentences, given these function docs:\n\n' + full_doc
summary = ask(summary_prompt)

Multilingue

Le même prompt fonctionne pour JS, Go, Rust, etc. Pour obtenir de meilleurs résultats, ajoutez le langage au prompt :

prompt = f'You are documenting {language} code. ...'

Documentation basée sur les différences

Pour les mises à jour incrémentielles, relancez le traitement uniquement sur les fichiers modifiés :

import subprocess
changed = subprocess.check_output(['git', 'diff', '--name-only', 'HEAD~1']).decode().splitlines()
for path in changed:
    if path.endswith('.py'):
        regenerate_doc(path)

Utiliser un outil pour exécuter l’exemple

Vérifiez que l’exemple d’utilisation du LLM s’exécute réellement — donnez à l’agent un outil REPL Python :

def run_python(code):
    try:
        exec(code, {})
        return {'stdout': 'ok', 'stderr': ''}
    except Exception as e:
        return {'stdout': '', 'stderr': str(e)}

tools = [{'name': 'run_python', 'description': 'Execute a Python snippet and return stdout/stderr', 'parameters': {'code': 'str'}}]

broken_example = 'print(1/0)'
result = run_python(broken_example)
if result['stderr']:
    print('Example failed:', result['stderr'])
    fixed_example = 'print(1)'
    result = run_python(fixed_example)
    print('Self-corrected result:', result)
else:
    print('Example ran fine:', result)

Lorsque l’agent hallucine

Le modèle invente parfois des fonctions ou des arguments. Voici quelques mesures pour limiter ce problème :

  • Fournissez UNIQUEMENT le contenu du fichier (sans utiliser la mémoire du modèle)
  • Température à 0
  • Ajoutez une étape de vérification (exécutez l’exemple, analysez l’extrait de code)

En faire un produit

Transformez ceci en CLI :

# pip install -e .
# docgen src/myproject/agent.py
# Outputs docs.md

De l’outil à l’intégration continue

Branchez-le sur l’intégration continue : à chaque PR, régénérez la documentation des fichiers modifiés et réintégrez-la. Votre dépôt est ainsi toujours documenté.

Pourquoi lire le fichier entier ?

Pourquoi transmettre au LLM l’intégralité du fichier source plutôt que les seules signatures de fonctions ?

Récapitulatif

Un agent de 30 lignes qui transforme du code en documentation. Il est facile de l’étendre avec des outils et une vérification. Un excellent deuxième projet après RAG.

Questions Fréquemment Posées

La leçon « Un agent explicateur de code » est-elle gratuite ?

Oui — le texte complet de « Un agent explicateur de code » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours AI Agents, passe à CoddyKit PRO. Le cours AI Agents comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Un agent explicateur de code » ?

Construisez un agent qui lit des fichiers source, demande au LLM une explication et renvoie une documentation en Markdown. Tu pratiques AI Agents avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer AI Agents ?

Aucune expérience préalable n'est requise. AI Agents sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 2 sur 4.

Combien de temps prend la leçon « Un agent explicateur de code » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon AI Agents ?

Oui. Chaque leçon AI Agents inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

  1. Un robot de questions-réponses sur vos documents
  2. Un agent explicateur de code
  3. Un agent de recherche sur le Web
  4. Un assistant SQL pour votre DB
← Retour à AI Agents