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 GitHubTemplate 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-medium1 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
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.
| Tier | Scope | Status |
|---|---|---|
| Small | Single-file scripts, quick edits, lowest cost | planned |
| Medium (this repo) | Multi-file projects, small full-stack apps | ✅ available |
| Large | Large codebases, parallel sub-agents, review gates | planned |
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, andbashare confined to the--sandboxdirectory; 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
| Flag | Default | Description |
|---|---|---|
--task | (required) | Path to the task spec (markdown/text). |
--sandbox | (required) | Project directory the agent may read/write. |
--planner-model | claude-opus-4-8 | Model for the planning phase. |
--executor-model | claude-sonnet-4-6 | Model for the build phase. |
--test-cmd | python3 -m pytest -q | Command used as the completion gate. |
--skip-plan | off | Skip planning; run the executor directly. |
--max-iterations | 50 | Hard cap on executor turns. |
--max-plan-turns | 12 | Hard 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
bashis 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-iterationsand 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.