0Pricing
AI Agents · Aula

Um agente que explica código

Construa um agente que leia arquivos de código-fonte, peça ao LLM uma explicação e retorne documentação em Markdown.

Um agente que explica código é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.

Partes desta aula ainda não foram traduzidas e aparecem em inglês.

Objetivo do projeto

Crie um agente que receba um arquivo-fonte (Python, JS ou qualquer outro) e retorne uma documentação em Markdown: finalidade, funções principais e exemplo de uso.

Por que isso é útil?

Gerar documentação a partir de código é um dos casos de uso mais confiáveis de LLM — o código é estruturado, a tarefa é limitada e a saída é lida por pessoas (portanto, pequenos erros são toleráveis).

Arquitetura

  1. Leia o arquivo-fonte
  2. Opcionalmente, divida por classe ou função
  3. Para cada parte, peça ao LLM uma explicação
  4. Combine tudo em um documento 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)

Lidar com arquivos longos

Se o arquivo for longo demais, divida-o por função e explique cada uma separadamente:

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)

Etapa 3: Combinar as saídas

Para execuções com várias partes, una as explicações de cada função em um único documento:

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)

Adicionar um resumo no nível do projeto

Depois das explicações de cada função, peça ao LLM uma visão geral de alto nível:

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

Várias linguagens

A mesma instrução funciona para JS, Go, Rust etc. Para obter resultados melhores, adicione a linguagem à instrução:

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

Documentação baseada em diferenças

Para atualizações incrementais, execute novamente apenas nos arquivos alterados:

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)

Use uma ferramenta para executar o exemplo

Verifique se o exemplo de uso do LLM realmente é executado — forneça ao agente uma ferramenta REPL de 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)

Quando o agente alucina

Às vezes, o modelo inventa funções ou argumentos. Medidas de contenção:

  • Forneça ONLY o conteúdo do arquivo (sem a memória do modelo)
  • Temperatura 0
  • Inclua uma etapa de verificação (execute o exemplo e analise o trecho)

Transforme-o em um produto

Envolva isso em uma CLI:

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

Da ferramenta à integração contínua

Conecte-a à integração contínua: em cada PR, regenere a documentação dos arquivos alterados e faça o commit de volta. Agora, seu repositório está sempre documentado.

Por que ler o arquivo inteiro?

Por que passar o arquivo-fonte FULL ao LLM em vez de apenas as assinaturas das funções?

Recapitulação

Um agente de 30 linhas que transforma código em documentação. Fácil de ampliar com ferramentas e verificação. Um ótimo segundo projeto depois de RAG.

Perguntas Frequentes

A aula “Um agente que explica código” é grátis?

Sim — o texto completo de “Um agente que explica código” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.

O que vou aprender em “Um agente que explica código”?

Construa um agente que leia arquivos de código-fonte, peça ao LLM uma explicação e retorne documentação em Markdown. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Agents?

Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Um agente que explica código”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Agents?

Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Um robô de perguntas e respostas sobre seus documentos
  2. Um agente que explica código
  3. Um agente de pesquisa que navega na Web
  4. Um assistente SQL para seu DB
← Voltar para AI Agents