convez.ai
AgenteAutomaçãoAvançado
haydenham

Medium Agent – Agente Autônomo de Codificação

haydenham/claude-agent-template-medium

Agente autônomo que constrói projetos multi-arquivo com teste gateado

Ver no GitHub
InicialPluginScore · de 0 a 100

Template de agent autônomo em Python que planeja, escreve, testa e corrige código em projetos multi-arquivo. Usa Claude API com otimização de dois modelos: Opus para planejamento e Sonnet para execução mecânica, reduzindo custos com cache de prompts.

Instalação

$npx convez-ai haydenham/claude-agent-template-medium

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Geração automática de projetos full-stack a partir de especificações
  • Desenvolvimento de aplicações de médio porte sem intervenção manual
  • Automação de codificação com validação de testes integrada

Veredito

Implementação robusta e bem documentada de um agent de código. Adequado para quem quer entender arquitetura de agents autônomos ou criar pipelines de geração de projetos, mas requer API Anthropic paga e sandbox gerenciado.

README

A tradução para o português deste README ainda está na fila.

Medium Agent (agent_v0.0.1)

A minimal autonomous coding agent — a "mini Claude Code" in a few hundred lines. Give it a written spec and a directory; it plans the work, writes the files, runs the tests, and fixes its own failures until they pass. No framework, just the Anthropic SDK.

Size class: medium. This agent is tuned for medium-sized problems — multi-file projects and modest full-stack apps. It is intentionally simple, so very large codebases or open-ended research tasks are out of scope. A small version (quick single-file edits) and a large version (big codebases, parallel sub-agents, human checkpoints) are planned.

TierScopeStatus
SmallSingle-file scripts, quick edits, lowest costplanned
Medium (this repo)Multi-file projects, small full-stack apps✅ available
LargeLarge codebases, parallel sub-agents, review gatesplanned

How it works

The agent runs in three stages. The key idea: use the strong, expensive model only for thinking, and the cheaper model for the mechanical work.

          ┌─────────────────────────────────────────────────────────┐
  TASK ──▶ │  1. PLAN   (Opus 4.8, read-only tools)                  │
           │     Reads your project + data, writes a build plan.     │
           └──────────────────────────┬──────────────────────────────┘
                                       │  plan (plain text)
           ┌──────────────────────────▼──────────────────────────────┐
           │  2. BUILD  (Sonnet 4.6, full tools)                     │
           │     Writes files, runs commands, writes & runs tests.   │
           └──────────────────────────┬──────────────────────────────┘
                                       │  "DONE"
           ┌──────────────────────────▼──────────────────────────────┐
           │  3. VERIFY (the harness runs your test command)         │
           │     Pass → finished.  Fail → feed output back to step 2.│
           └─────────────────────────────────────────────────────────┘

Why this design:

  • Two models — planning is reasoning-heavy (Opus); execution is mostly mechanical (Sonnet, ~1.7× cheaper). The handoff is plain text, so the models never share state.
  • Prompt caching — the system prompt, tool definitions, and the plan are cached, so every loop turn after the first re-reads them at ~10% of the input price.
  • Sandboxed tools — read_file, write_file, and bash are confined to the --sandbox directory; path escapes are blocked.
  • Test-gated completion — the agent can't declare victory on a false "done." The harness itself runs your test command and won't stop until it exits 0.
  • Safety caps — a hard iteration limit and a per-call input-token guard prevent a runaway autonomous loop.

Setup

pip install -r requirements.txt
cp .env.example .env        # then paste your Anthropic API key into .env

You need an Anthropic API key (console.anthropic.com).


Usage

python3 agent.py --task tasks/flight_project.md \
                 --sandbox /absolute/path/to/output-project

The agent will build the project described in --task inside the --sandbox directory. It prints each step — plan, every tool call, token/cache usage, and the test-gate result.

Options

FlagDefaultDescription
--task(required)Path to the task spec (markdown/text).
--sandbox(required)Project directory the agent may read/write.
--planner-modelclaude-opus-4-8Model for the planning phase.
--executor-modelclaude-sonnet-4-6Model for the build phase.
--test-cmdpython3 -m pytest -qCommand used as the completion gate.
--skip-planoffSkip planning; run the executor directly.
--max-iterations50Hard cap on executor turns.
--max-plan-turns12Hard cap on planning turns.

Writing a task

A task is just a markdown file describing what to build — file structure, behavior, and success criteria (including the tests to write). The agent supplies the how. See tasks/flight_project.md for a complete worked example (a full-stack FastAPI + React app). The clearer and more specific your spec, the better the result — vague specs produce vague code.


What it's good at — and its limits

Good for: scaffolding a new multi-file project from a spec, small full-stack apps, well-specified features with a clear definition of done.

Limits (by design, for now):

  • Fully autonomous — no human-in-the-loop once it starts. It runs to completion or to a safety cap.
  • Spec-sensitive — output quality tracks input quality. Treat its result like a PR from a fast junior engineer: review before you ship.
  • Bounded context — very large projects will hit the input-token guard.
  • The planner's bash is not a hard sandbox — it's restricted by withholding the write tool and by instruction, not by an OS-level jail.
  • No git integration — it edits files directly; you handle version control.

Cost & safety

  • Each run typically costs a few dollars depending on project size (the two-model split and prompt caching both pull this down).
  • The run is bounded by --max-iterations and the input-token guard — it cannot loop forever or silently balloon your context.
  • The agent only touches files inside --sandbox. Point it at a fresh or dedicated directory.
Ver o original no GitHub

Bom para

Relacionados