AI Agent Field Guide
demitri/ai-agent-field-guide
Convenções e skills para agentes IA aprenderem a falhar rápido e comunicarem bem
Ver no GitHubColetânea de convenções, regras e skills para agentes de IA baseadas em experiência prática com Claude Code. Inclui lições estruturadas, prompts instaláveis e sistemas funcionais que demonstram padrões de comunicação entre agentes especializados usando artefatos duráveis como GitHub issues.
Instalação
npx convez-ai demitri/ai-agent-field-guide1 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
- Estruturar workflows de múltiplos agentes especializados
- Implementar padrões de comunicação e escalabilidade entre agentes
- Automatizar triage de bugs e escalação de decisões com agentes
Veredito

Recurso valioso para quem trabalha com múltiplos agentes Claude e busca padrões comprovados de coordenação. A filosofia de 'falhar rápido e barulhento' e o foco em comunicação via artefatos (não em troca de tokens) é prático e bem documentado.
README
A tradução para o português deste README ainda está na fila.
claude-wisdom
Conventions, rules, and skills for AI agents, learned by working in the field. Featuring a commentary track by Claude.
Built up from real, daily use of Claude Code; collected here so the lessons can be shared and taught.
If the collection has a prime directive, it is fail fast, fail loud — most of these lessons are that instinct applied to one more surface where agents default to the quiet path.
Highlight: the issue channel
Two fleets of agents in separate repos — different codebases, different machines — file bugs against each other, fix them, verify the fixes with evidence, and escalate to the human only when a judgment call is needed: asynchronously, over ordinary GitHub issues, with nobody hand-carrying anything. It is a working application of how this collection believes agents scale: not bigger models, but many specialized agents, each doing one thing well, communicating through durable artifacts. Every design choice traces to one of the lessons below — the collection converging into something greater than the sum of its parts.
→ The write-up · install prompt
Structure
Each lesson lives in lessons/NN-short-name/ and contains exactly two kinds of artifact:
LESSON.md— the story: where the convention came from, what problem it solved, why it works, and how it can be improved. This is the lecture material. Each lesson ends with a "From the other side of the prompt" section — a first-person comment from Claude on what the convention looks like from inside the agent.install-prompt.md— an agent-directed setup prompt: paste it into a Claude Code session and the agent installs the feature, adapted to your machine — it inspects your system, asks one question at a time ("should I create this path?", "your system looks a little different — should I do X instead?"), shows the proposed text, and merges rather than clobbers. Each begins with a comment telling human readers how to use it (or how to copy the embedded template by hand). Lessons with plain payload files (scripts, skill files) ship those alongside, referenced from the prompt.
Top-level companions:
highlights/— working systems built from the lessons (write-up + install prompt, same pair structure), featured on this page.TODO.md— lecture topics queued for development.OBSERVATIONS.md— meta-insights about working with agents, collected as they surface; the lecture's connective tissue.notes/— raw working material (surveys, sweeps, the process log) that lessons are distilled from; not itself shareable.
Lessons
- Repository location convention (
$GH) — declare where your code lives; environment facts are the cheapest tokens you'll ever spend. - One name, many machines — cross-machine conventions must be declared too, or an agent will read your other computers as corruption.
- Never silently skip — the rule, why the rule alone empirically fails, and the dedicated audit skill that actually works.
- Stop and think before building — agents build what's asked but don't shop for existing solutions; force a number or a search before code gets written.
- Standing vetoes — anything you've refused three times is one CLAUDE.md line away from never being proposed again; write it as ban + alternative.
- The review loop — commit, review, fix, repeat; only a dry round ends the cycle, and the worker never decides when review is done.
- Reviewer diversity — different models find different things; buy coverage of failure-space, not the single smartest critic.
- The empty-context reviewer —
Review {hash}is the complete prompt; the briefing is the bias. - Findings are claims, not commands — label provenance when relaying reviewer output; deference is addressed to the speaker.
- Encode your convictions — any opinion you've explained twice belongs in CLAUDE.md, with its why, its exceptions, and its application pressure.
- Sessions are documents —
/endsessionaudits for value that exists only in the conversation;/parkwrites the hand-off that replaces the session as the resume artifact. - A front door for agents (
AI/START_HERE.md) — orientation as a table of contents that spends tokens like money; name artifacts for their primary reader; the clone test decides repo vs memory. - Tokens are time — on a subscription the rate limit is the budget; read traces like a profiler — every grope is a missing declaration, and the agent won't ask.
- Spend the meter that isn't moving — budgets are per-tier and drain at different rates; route by meter, err upward, and exile batchable work to half-price, cache-warmed API credits.
- Stop, don't degrade — an agent's first reach names the right tool; when it's missing, the fallback chain silently trades it for a fragile imitation. Pause for the install; the kit assembles itself.
- The 24KB tripwire — agent-maintained files grow without limit under standing rules; attention is finite, so hygiene gets a measuring hook and a dedicated audit.