0Pricing
AI Agents · Урок

Агент для объяснения кода

Создайте агента, который читает исходные файлы, просит LLM дать объяснение и возвращает документацию в Markdown.

«Агент для объяснения кода» — бесплатный урок AI Agents на CoddyKit. Это урок 2 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения AI Agents, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс AI Agents содержит 4 уроков всего.

Части этого урока еще не переведены и отображаются на английском.

Цель проекта

Создайте агента, который принимает исходный файл (Python, JS и любой другой) и возвращает документацию в Markdown: назначение, ключевые функции и пример использования.

Чем это полезно?

Генерация документации по коду — один из самых надёжных вариантов применения LLM: код структурирован, задача ограничена, а результат читают люди, поэтому небольшие ошибки допустимы.

Архитектура

  1. Прочитать исходный файл
  2. При необходимости разделить по классам и функциям
  3. Для каждого фрагмента попросить LLM дать объяснение
  4. Объединить результат в документ 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)

Обработка длинных файлов

Если файл слишком длинный, разделите его по функциям и объясните каждую отдельно:

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)

Шаг 3: объединение результатов

При работе с несколькими фрагментами объедините объяснения отдельных функций в один документ:

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)

Добавьте сводку на уровне проекта

После объяснений отдельных функций попросите LLM дать обзор высокого уровня:

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

Несколько языков

Один и тот же промпт работает для JS, Go, Rust и других языков. Для лучших результатов добавьте язык в промпт:

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

Документация на основе различий

Для инкрементальных обновлений запускайте обработку повторно только для изменённых файлов:

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)

Используйте инструмент для запуска примера

Проверьте, что пример использования от LLM действительно запускается: предоставьте агенту инструмент Python REPL:

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)

Когда агент выдумывает

Модель иногда выдумывает функции или аргументы. Возможные меры:

  • Предоставляйте ONLY содержимое файла, без памяти модели
  • Установите температуру 0
  • Добавьте этап проверки: запустите пример и выполните статическую проверку фрагмента

Превратите это в продукт

Оберните это в CLI:

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

От инструмента к CI

Подключите инструмент к CI: при каждом PR заново создавайте документацию для изменённых файлов и фиксируйте изменения в репозитории. Теперь ваш репозиторий всегда документирован.

Зачем читать весь файл?

Зачем передавать LLM полный исходный файл, а не только сигнатуры функций?

Повторим

Агент из 30 строк, превращающий код в документацию. Его легко расширить инструментами и проверками. Отличный второй проект после RAG.

Часто задаваемые вопросы

Урок «Агент для объяснения кода» бесплатный?

Да — полный текст урока «Агент для объяснения кода» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс AI Agents, подпишись на CoddyKit PRO. Курс AI Agents содержит 4 уроков всего.

Чему я научусь в уроке «Агент для объяснения кода»?

Создайте агента, который читает исходные файлы, просит LLM дать объяснение и возвращает документацию в Markdown. Ты практикуешь AI Agents с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать AI Agents?

Предыдущий опыт не требуется. AI Agents на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 2 из 4.

Сколько времени занимает урок «Агент для объяснения кода»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке AI Agents?

Да. Каждый урок AI Agents включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

  1. Бот вопросов и ответов по вашим документам
  2. Агент для объяснения кода
  3. Агент-исследователь для веб-поиска
  4. SQL-ассистент для вашей DB
← Назад к AI Agents