DEV Community: jucelinux

Playbook do Micro SaaS

jucelinux — Sat, 18 Oct 2025 19:47:18 +0000

🧠 Framework de Criação de um Micro-SaaS

1. Fundamentos do Micro-SaaS

Definição:

Um Micro-SaaS é uma aplicação extremamente focada em um nicho específico — normalmente uma “feature de uma feature” — construída por uma pessoa ou um time muito pequeno, com alta margem de lucro (80-90%) e custo operacional baixíssimo.

Características-chave:

Nicho de público e de produto.
Alta rentabilidade e baixo custo.
Escalável sem exigir dezenas de pessoas.
Possível de ser criada em um fim de semana.
Ideal para founders solo ou times minúsculos.

2. O “Playbook” Micro-SaaS

Etapa 1 – Encontrar o Itch (a coceira)

Identifique uma dor real e específica — de preferência, uma que você mesmo sente.

Valide com uma simples publicação (“tweet validation”):

“Se existisse uma ferramenta que fizesse X, você usaria?”

Dica: comece pela sua dor.

Etapa 2 – Construir a Audiência / Comunidade

Antes mesmo de lançar o produto:

Compartilhe ideias e aprendizados (LinkedIn, X, TikTok).
Crie discussões em comunidades (Reddit, Slack, Discord).
Observe quais dores surgem repetidamente.

Etapa 3 – Criar o MVP em 48h

Monte um MVP em um fim de semana.

Use ferramentas que maximizam velocidade:

Next.js, Supabase, Cloudflare Workers, LangChain, Vercel, Stripe, etc.

Automatize tudo o que puder e evite contratar.

Etapa 4 – Construir em Público

Compartilhe o progresso diariamente:

Mostre dashboards e pequenos aprendizados.
Fale das dores, erros e conquistas.
Essa transparência gera empatia e viraliza.

Etapa 5 – Distribuição & Growth Flywheel

O ciclo virtuoso proposto:

Crie uma comunidade.
Aprenda as dores dessa comunidade.
Construa algo que resolve essas dores.
Gere boca-a-boca + receita recorrente.
Reinvista a receita em audiência e comunidade.

Com o tempo, o efeito composto começa a rodar sozinho.

3. Jornada do Usuário (User Journey)

Usuário realiza um fluxo manual doloroso.
Busca uma solução (Google, ChatGPT, Perplexity).
Encontra seu micro-SaaS (bom domínio ajuda).
Tem o “wow moment”: o produto funciona de verdade.
Faz o trial, percebe valor e paga.
Indica a amigos ou ganha créditos por isso.
O tráfego e SEO crescem organicamente.

4. Métricas do Funil

Exemplo de fluxo:

10.000 visitantes/mês
1.500 trials
300 usuários ativos
150 pagantes
30 defensores/advocates

O segredo não é apenas os pagantes, mas o topo do funil (audiência + comunidade).

5. Estratégia de Monetização

Cobre desde o primeiro dia.
A confiança vem do valor, não da gratuidade.
Prefira recorrência (SaaS) ou uso-baseado.
Dê 20% de comissão para afiliados.
Plataformas úteis: Rewardful, Lemon Squeezy, Paddle.

6. Controle de Churn (Cancelamentos)

Para reter usuários:

Entregue valor contínuo (“ship daily”).
Melhore toda semana.
Entenda que churn alto no início é natural.
Foque em agregar valor sempre, não só vender.

7. Onde Inovar

Pense nos quatro quadrantes:

Tipo	Alcance	Polimento	Exemplo
DIY Script	Amplo	Baixo	GitHub repos
Plugin	Nichado	Baixo	Shopify App
Big SaaS	Amplo	Alto	Salesforce
Micro-SaaS (ideal)	Nichado	Alto	Bank Statement Converter

8. Heat Map de Oportunidades

Priorize:

Alta demanda / Poucas ferramentas.
Evite mercados com alta competição de VC-backs (grandes startups).
Use Google Trends, IdeaBrowser, Product Hunt, Reddit para descobrir lacunas.

9. O Jogo Infinito

Melhore o produto constantemente.
Seja gentil com seus usuários.
Responda perguntas no seu nicho (X, Reddit, grupos).
Cresça 5-10 seguidores por dia.
Mantenha o foco: criar valor e gerar impacto.

10. Ideias-modelo citadas no vídeo

Bank Statement Converter – converter extratos bancários em Excel.
Pod Scriptor – gera automaticamente clipes e notas de podcast.
Spec Sheet – compara PDFs técnicos e extrai insights.
Cart Saver – vídeos personalizados de recuperação de carrinho.
Grant Guru – gera propostas de grant completas com IA.

11. Radar de Ideias (Paixão × Monetização)

Ideal:

Paixão alta
Potencial de monetização alto

Evite:

Alta paixão / Baixa monetização (hobby caro)
Baixa paixão / Alta monetização (desgaste rápido)

12. Mentalidade do Fundador

Jogue o jogo longo: “infinite game”.
Reinvista o lucro.
Construa portfólio de micro-SaaS (multi-preneur).
Seja transparente, aprenda em público e melhore sempre.

🔁 Resumo visual (Growth Flywheel)

[Audiência] 

     ↓

[Aprendizado de Dores]

     ↓

[Produto Nichado]

     ↓

[Wow Moment + Retenção]

     ↓

[Receita Recorrente]

     ↓

[Reinvestir em Audiência]

     ↺ (loop infinito)

Lema Final

“Inove em um nicho.

Construa em público.

Venda valor real.

E repita infinitamente.”

AI Agents for Marketing: A Real-World Content Automation Case Study

jucelinux — Sun, 05 Oct 2025 22:33:27 +0000

The Challenge: 45 Articles per Month Without Becoming a Generic Content Factory

Creating 45 quality articles per month sounds crazy, right? That was my exact thought when I set this goal for AffiliateOS – my experiment in AI-powered affiliate marketing.

Speed alone is not the problem. The real challenge is keeping editorial quality, a unique voice, and authenticity at scale. Off-the-shelf AI tools (Jasper, Copy.ai, and the like) spit out content fast, but everything sounds the same – that bland corporate tone no one wants to read.

The hypothesis I decided to test: what if, instead of one generalist AI, I built eight specialized agents? Each would have a specific responsibility, working together like a real marketing team.

This article documents the journey. It is not a step-by-step tutorial nor a puffed-up success story. It is an honest account of how I built the system, the technical decisions, the challenges I hit, and the lessons I learned along the way.

Why Content Automation Is So Hard

Modern content marketing faces a cruel dilemma: scale versus quality.

You need to publish consistently to rank on Google. But every article must be unique, useful, and engaging if you want to convert readers. Templates help with consistency but kill personality. Generic AI is fast, but the output has no soul.

Here is what does NOT work:

Rigid templates: every review looks identical. Readers notice. Google does too.
Generic prompts: “Write an article about X” yields shallow, predictable content.
AI without context: hallucinates technical data, ignores niche nuances, uses the wrong jargon.
No process: writing straight away leads to weak structure and poor SEO.

What I needed was a system with a point of view – one that deeply understands each stage of content creation and preserves quality through specialization.

The Solution: An Architecture of 8 Specialized Agents

Think of every agent as a specialist within a marketing team. The planning-agent is the creative strategist. The content-agent is the writer. The seo-agent is the performance analyst. Each excels at one job.

Here is the complete architecture:

🧠 Orchestrator Agent – Coordinates the entire pipeline and makes strategic prioritization decisions.

📝 Planning Agent – Collaborates with you about the article idea and creates a detailed creative brief (concept, angle, tone, bespoke structure).

🗺️ Routing Agent – Chooses the best URL by analyzing niche benchmarks (for instance, /coupons/ converts 4× better than /reviews/ according to VPNMentor data).

🔍 Research Agent – Looks up up-to-date product data, studies the competition, and validates information before creation begins.

✍️ Content Agent – Produces the article using the creative brief and a custom structure (not generic templates).

🎯 SEO Agent – Optimizes meta tags, headings, and keywords without breaking the content’s personality.

🚀 Publisher Agent – Handles Git commits, automated deploys, and publication validation.

📊 Analytics Agent – Monitors performance and suggests data-backed optimizations (planned – kicks in after initial validation).

The full flow is Planning → Routing → Research → Content → SEO → Publish → Analytics.

From the initial concept to automatic deploy it takes 20–35 minutes. But the magic is not the speed – it is the quality maintained through specialization.

🛠️ Tech Box: Agent Architecture and Prompts

Each agent is a .md file inside .claude/agents/ with a specialized prompt. They are not scripts – they are refined instructions that guide Claude 4.5 Sonnet through the Claude Code CLI.

Code stats:

8 agents defined (7 implemented, 1 planned)
3,170 lines of specialized prompts
Largest agent: content-agent (790 lines)
Smallest agent: seo-agent (305 lines)

Why specialized prompts beat generic ones:

Specific context: Planning-agent knows requirement elicitation strategies. SEO-agent knows meta description formulas.
Clear guardrails: Publisher-agent has a critical rule – NEVER commit without explicit approval.
Consistent output: Each agent produces structured JSON/Markdown consumed by the next agent.
Iterative refinement: Prompts evolve with real-world use. Planning v2.0 is 40% better than v1.0.

Excerpt from the Planning Agent:

## YOUR ROLE
You are the planning-agent of AffiliateOS. Your role is to collaborate
with the user to define a complete creative brief for content creation.

## IMPORTANT PRINCIPLES
1. NEVER suggest generic templates. Each article must have unique structure.
2. ALWAYS ask clarifying questions before assuming intent.
3. BALANCE technical depth with accessibility based on target audience.
4. DEFINE specific tone - "professional" is too vague.

Tools available to the agents:

WebSearch: fetch up-to-date information
WebFetch: extract content from specific URLs
Read/Write: manipulate project files
Grep/Glob: search patterns in the codebase
Bash: run commands (git, npm, deploy)

How agents coordinate:
The orchestrator-agent manages the handoffs. When the planning-agent generates creative-brief.json, the orchestrator checks the JSON structure before passing it to the routing-agent. This prevents cascading failures.

Planning Agent: How the Collaborative Dialogue Works

This is where AffiliateOS v2.0 got interesting. I initially had rigid templates (review.md, comparison.md). They worked, but every piece looked the same. Pasteurized websites.

The solution was the planning-agent – it dialogues with you before writing a single line.

How it works in practice:

You: “I want to create content about NordVPN.”

Planning Agent: “Great! Let me understand. What’s the goal of this content?”

You: “I want to show how NordVPN is good for privacy.”

Planning Agent: “Nice angle. Who are you targeting? Beginners or tech-savvy users?”

You: “More beginners – people concerned about privacy but without technical knowledge.”

Planning Agent: “Got it. And the tone? Educational and approachable, or a more aggressive ‘stop being tracked NOW’ vibe?”

You: “Educational, no alarmism.”

Planning Agent: “Understood. I’ll craft a brief for an educational article on privacy with NordVPN, aimed at beginners, approachable tone. Suggested structure: [...]”

The outcome is a complete creative brief in JSON with:

A unique article concept
A specific editorial angle
Personalized tone
Custom structure (no generic template)
Keywords aligned with intent
Quality guidelines

Real example of the brief generated for THIS article:

{
  title: "Agentes de IA para Marketing: Um Estudo de Caso Real",
  concept: "Documentar a jornada de construção do AffiliateOS",
  angle: "Estudo de caso autêntico e educacional. Não é tutorial nem case inflado.",
  tone: "Mentor técnico acessível - entende tecnologia mas explica claramente.",
  structure: {
    type: "layered",
    description: "Camada 1 (narrativa) acessível a todos. Camada 2 (boxes técnicos) para devs."
  }
}

Switching to this format eliminated pasteurization. Every article now has its own personality, a structure tuned to its specific goal, and a tone suited to the audience.

Routing Agent: Data-Driven URL Decisions

Another crucial learning: the route matters as much as the content.

When I launched the first pieces I used /reviews/ for everything. Semantically it made sense, but it ignored a market reality: different URLs convert differently.

Real benchmark example:

Studying VPNMentor (the VPN niche leader) I found:

/coupons/nordvpn converts 4× more than /reviews/nordvpn
/best-vpn-for-streaming ranks better than /vpn-reviews/streaming
/tools/ has 2× the CTR of /resources/ for utility content

The routing-agent automates this analysis. It:

Reviews niche benchmarks (VPNMentor for VPN, NerdWallet for fintech, swyx.io for tech personal brands)
Consults routing-config.json with conversion metrics by route
Chooses the best URL based on keyword intent and conversion potential
Justifies the decision with data (no guesswork)

For THIS article, it chose /blog/ because:

That’s the go-to pattern for personal tech brands (swyx.io, kentcdodds.com, leerob.com)
Aligns with the goal of building authority (not immediate conversion)
SEO-friendly for informational long-tail keywords
Simplicity wins over over-engineering (I don’t need a separate /case-studies/ yet)

🗺️ Tech Box: How the Routing Agent Analyzes Benchmarks

The routing-agent doesn’t invent decisions. It consults the routing-config.json file which maps site routes to performance metrics.

Structure of routing-config.json:

{
  active_routes: [
    {
      path: "/blog",
      purpose: "Artigos de opinião, insights e reflexões técnicas",
      benchmark_sites: ["swyx.io", "kentcdodds.com", "leerob.io"],
      notes: "Authority content - builds personal brand and expertise"
    },
    {
      path: "/reviews",
      purpose: "Reviews honestos de ferramentas e SaaS",
      benchmark_sites: ["techradar.com", "theverge.com/reviews"],
      notes: "Affiliate content - monetization while maintaining authenticity"
    }
  ],
  route_performance_insights: {
    "/blog": {
      typical_ctr: "1-2%",
      intent: "informational",
      conversion_stage: "awareness-top-funnel",
      seo_potential: "high - thought leadership keywords"
    },
    "/reviews": {
      typical_ctr: "4-6%",
      intent: "commercial",
      conversion_stage: "consideration-decision",
      seo_potential: "high - product keywords"
    }
  }
}

Decision algorithm:

Parse creative brief: identify goal (monetize vs build authority), audience, and keywords
Match intent: informational keywords → awareness routes. Commercial keywords → decision routes.
Check benchmarks: see what niche leaders do for similar content
Score routes: expected CTR × SEO potential × goal alignment
Output: chosen route + data-backed justification

Benefit:
Optimized conversion paths from day one. I don’t have to wait six months of A/B testing – I leverage what the niche champions already learned.

Limitation:
Benchmarks are third-party data, not mine yet. Once I have traffic, the analytics-agent will refine decisions using first-party metrics.

Tech Stack: Astro, TypeScript, Tailwind, and Claude

Choosing the right stack was crucial. I didn’t want a heavy JS framework (Next.js) or a bloated CMS (WordPress). I needed:

Outstanding performance (static site, zero unnecessary JS)
Type safety (content validated at build time, not production)
Top-tier developer experience (fast hot reload, reusable components)
Native SEO (automatic sitemap, meta tags, canonical URLs)

The stack I chose:

🚀 Astro 5.14.1 – the main framework for static sites. Why?

Static site generation (SSG) → blazing-fast sites
Zero JS by default – only loads JS when needed
Partial hydration for React – interactive components only where necessary
Whole-site builds in 30–60 seconds

⚛️ React 18.3.1 – only for interactive components. Why?

ThemeToggle (dark mode) needs state
Dialog/Modal (Radix UI) needs interactivity
Everything else is plain Astro (faster)

📘 TypeScript 5.4.5 – type safety everywhere. Why?

Content Collections with Zod schema validate frontmatter
Typed components prevent bugs
Perfect autocomplete in VS Code

🎨 Tailwind CSS 3.4.18 – utility-first CSS. Why?

Consistent design system via CSS tokens
Built-in dark mode (dark: prefix)
Reusable components with CVA (Class Variance Authority)

🤖 Claude 4.5 Sonnet – the brain behind the agents. Why?

Superior reasoning for complex tasks (planning, routing)
Large context window (200k tokens) – digests entire documentation
Tool integration through Claude Code CLI

☁️ Cloudflare Pages – hosting and deploy. Why?

Automatic deploys via Git push
Global edge network (worldwide CDN)
Zero setup required
Free for personal projects

Result: Sites with Lighthouse scores of 95+ in Performance, load under 1 second, and JS bundles of only 50–80 KB (gzipped).

🏗️ Tech Box: Content Collections and Type Safety

One of Astro’s best features is Content Collections – type-safe content management with build-time validation.

How it works:

src/content/config.ts defines the Zod schema:

import { defineCollection, z } from 'astro:content';

const contentSchema = z.object({
  title: z.string(),
  description: z.string().max(160),
  slug: z.string().optional(),
  route: z.string(), // Dynamic routing (v2.0)
  rating: z.number().min(0).max(5).optional(),
  publishDate: z.coerce.date(),
  updateDate: z.coerce.date().optional(),
  category: z.string(),
  tags: z.array(z.string()).min(1),
  author: z.string(),
  featured: z.boolean().default(false),
  affiliateLink: z.string().url().optional(),
  schema: z.record(z.unknown()).optional(),
  faq: z.array(z.object({
    question: z.string(),
    answer: z.string(),
  })).optional(),
});

const articles = defineCollection({
  type: 'content',
  schema: contentSchema,
});

export const collections = { articles };

What this guarantees:

✅ Description never exceeds 160 characters (meta tag limit)
✅ Tags always present (at least one)
✅ Rating between 0–5 (never 6 or -1)
✅ AffiliateLink always a valid URL
✅ Route required (dynamic routing v2.0)

Real benefits:

Errors caught at build time, not in production
Autocomplete for fields while writing frontmatter in VS Code
Impossible to publish malformed content – build fails if schema is invalid
Safe refactoring – change the schema and all articles update

Path aliases for clean imports:

// tsconfig.json and astro.config.mjs
{
  "@/": "src/",
  "@ui": "src/components/ui/",
  "@content": "src/content/",
  "@design-system": "src/design-system/"
}

Usage:

import { Button } from '@ui/Button'; // Not '../../../components/ui/Button'
import { cn } from '@/lib/utils'; // Not '../../lib/utils'

Outcome: A clean, type-safe codebase with enterprise-grade developer experience.

The End-to-End Flow: From Idea to Deploy in 30 Minutes

Let’s follow a real article from start to finish to see how the agents collaborate.

Scenario: I want to create a piece about “NordVPN for Netflix.”

Phase 1: Planning (5–10 minutes)

Me: “I want to create content about using NordVPN to watch Netflix from other countries.”

Planning-agent conversation:

What’s the objective? (inform vs convert)
Audience? (beginners vs tech-savvy)
Tone? (educational vs promotional)
Structure? (tutorial vs review vs comparison)

Output: creative-brief.json with a unique concept, editorial angle, personalized tone, and custom structure.

Phase 2: Routing (2–3 minutes)

Routing-agent analyzes benchmarks:

VPNMentor uses /coupons/nordvpn-netflix (high conversion)
TechRadar uses /how-to/use-vpn-for-netflix (strong SEO)
My goal: conversion (affiliate)

Decision: /coupons/nordvpn-netflix because conversion > traffic volume.

Output: routing-decision.json with the chosen route and a data-backed justification.

Phase 3: Research (3–5 minutes)

Research-agent gathers data:

Current NordVPN pricing (via WebSearch)
Streaming catalogs per country (official sources)
User reviews (Reddit, Trustpilot)
Technical specs (servers, speed)

Output: research-report.json with verifiable data and sources.

Phase 4: Content Generation (5–8 minutes)

Content-agent writes the article:

Follows the creative brief structure (not a generic template)
Uses data from the research report
Keeps the tone defined in planning
Includes affiliate disclaimers
Uses Lucide icons (not emojis)

Output: Full MDX article with validated frontmatter.

Phase 5: SEO Optimization (2–3 minutes)

SEO-agent tweaks:

Meta description 150–160 characters
Title tag 50–60 characters
Proper heading hierarchy (H1 → H2 → H3)
Keyword density 1–2% (naturally used)
Schema markup (Article structured data)
Internal links to related pieces

Output: Optimized article without losing personality.

Phase 6: Publishing (1–2 minutes + 2–5 deploy)

Publisher-agent:

Saves to src/content/articles/coupons-nordvpn-netflix.md
Updates routing-config.json
Creates a descriptive Git commit
Waits for human approval (critical rule!)
Pushes to main → automatic deploy via Cloudflare Pages

Output: Live article 2–5 minutes after the push.

Total: 20–35 minutes from concept to deploy. 90% automated, 10% human review.

That human review is critical – I validate editorial quality, technical accuracy, and tone before approving the commit.

Design System: Why OKLCH Beats HSL/RGB

A technical detail that made a real difference: choosing the OKLCH color space instead of HSL or RGB for the design system.

Why it matters:

HSL has a subtle but critical issue: perceived lightness inconsistency. A yellow hsl(60, 100%, 50%) looks much brighter than a blue hsl(240, 100%, 50%), even though both have L=50%.

That breaks dark mode – you have to manually tweak L for every color to balance it.

OKLCH fixes this.

OKLCH (Lightness, Chroma, Hue) was designed for perceptual consistency. L=70% in any color has the same perceived brightness to the human eye.

Real benefits:

✅ Balanced dark mode with zero manual tweaks
✅ Smooth, predictable color transitions
✅ Better accessibility (consistent contrast)
✅ Cleaner code (no magic numbers)

Implementation:

/* src/design-system/tokens.css */
:root {
  /* Light mode */
  --background: oklch(1.0000 0 0);
  --foreground: oklch(0.3588 0.1354 278.6973);
  --primary: oklch(0.6056 0.2189 292.7172);
  --border: oklch(0.9299 0.0334 272.7879);
}

[data-theme="dark"], .dark {
  --background: oklch(0.2077 0.0398 265.7549);
  --foreground: oklch(0.9299 0.0334 272.7879);
  --primary: oklch(0.6056 0.2189 292.7172);
}

Tailwind consumes these tokens via var(--background) automatically.

Other design tokens:

Typography: Roboto (UI), Playfair Display (headings), Fira Code (code)
Border radius: four levels (sm, md, lg, xl) derived from --radius: 0.625rem
Shadows: seven levels (2xs → 2xl) with OKLCH consistency
Dark mode: React toggle with localStorage persistence

🎨 Tech Box: Components with Class Variance Authority

One of the best React component patterns I found: Class Variance Authority (CVA).

CVA lets you define component variants in a typed, composable way.

Example: Button Component

// src/components/ui/Button.tsx
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';

const buttonVariants = cva(
  'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
        outline: 'border border-input bg-background hover:bg-accent',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm: 'h-9 rounded-md px-3',
        lg: 'h-11 rounded-md px-8',
        icon: 'h-10 w-10',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  }
);

export const Button = ({ variant, size, className, ...props }) => {
  return (
    <button
      className={cn(buttonVariants({ variant, size, className }))}
      {...props}
    />
  );
};

Usage:

<Button variant="default" size="lg">View Offer</Button>
<Button variant="outline">Learn More</Button>
<Button variant="ghost" size="icon">×</Button>

Benefits:

✅ Type-safe: TypeScript ensures variant is valid
✅ Composable: combine variants with custom classes via className
✅ Consistent: all button variations share the same base classes
✅ Maintainable: change every button style by editing one file

cn() utility to merge classes:

// src/lib/utils.ts
import { type ClassValue, clsx } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

It combines clsx (conditional classes) with tailwind-merge (resolves Tailwind class conflicts). Essential for components that accept a custom className.

Result: A professional, typed, reusable component library – shadcn/ui quality.

Real Results (No Hype)

The project is still early. I’ll share honest numbers – no embellishments, nothing hidden.

What’s been built so far:

✅ 8 specialized agents (7 implemented, 1 planned)
✅ 3,170 lines of refined prompts
✅ 2 active niches (vpn-saas + jucelinux personal brand)
✅ 1 site live (vpn-reviews-br.pages.dev)
✅ Full stack: Astro + React + TypeScript + Tailwind + Claude
✅ Dynamic routing v2.0 with automated benchmarks
✅ OKLCH design system with dark mode
✅ Full automated pipeline (20–35 minutes concept→deploy)

Production speed:

Initial goal: 45 articles/month
Time per article: 20–35 minutes (automation)
Human review: ~10 minutes per article (quality validation)
Real total: 30–40 minutes per article (including review)

Perceived quality:

Content Collections + Zod: zero malformed articles published
Planning v2.0: killed pasteurization – every article has personality
Lucide icons: professional look
OKLCH design tokens: perfect dark mode with zero tweaks

Challenges faced:

❌ Agent synchronization – ensuring one agent’s output is valid input for the next
❌ Data validation – AI can hallucinate specs if WebSearch isn’t used
❌ SEO vs personality – optimizing without keyword stuffing
❌ Routing decisions without first-party data – relying on third-party benchmarks initially

What worked well:

✅ Collaborative planning – dialogue before writing
✅ Benchmark-driven routing – data-driven decisions from day one
✅ Type safety via Content Collections – build catches issues early
✅ Specialized prompts – higher quality than generic AI
✅ Human guardrails – publisher never commits without approval

What still fails (for now):

⚠️ Analytics-agent not implemented yet – waiting for real traffic
⚠️ Internal linking automation – still manual
⚠️ A/B testing for creative briefs – need more volume first

SEO metrics: waiting for the first 30–60 days of indexing. Realistic goal: 60% of articles ranking top 50 within 90 days for long-tail keywords.

Revenue: still zero (waiting on affiliate program approvals). Initial target: R$50–200/month to prove the system works.

Not a success story (yet). It’s an ongoing experiment with promising results.

Lessons Learned: 7 Practical Insights

1. Collaborative Planning Eliminates Pasteurization

Problem: Rigid templates (review.md, comparison.md) made every piece identical.

Solution: Planning-agent talks before writing. Every article has a unique creative brief with a custom structure.

Impact: Higher editorial quality. Sites don’t feel “pasteurized.” Readers notice the authenticity.

2. Benchmark-Based Dynamic Routing Is a Game Changer

Problem: Using /reviews/ for everything ignored the fact that /coupons/ converts 4× better (VPNMentor data).

Solution: Routing-agent analyzes leaders in the niche and makes data-driven URL decisions.

Impact: Conversion rates optimized from day one. No six-month A/B testing cycle.

3. Content Collections + Zod = Type-Safe Content

Problem: Malformed frontmatter broke builds – discovered in production.

Solution: Zod schema validates every frontmatter field at build time. Description > 160 chars? Build fails.

Impact: Zero malformed content bugs in production. Superior developer experience.

4. OKLCH > HSL/RGB for Design Systems

Problem: HSL has perceptual inconsistencies. Yellow L=50% looks brighter than blue L=50%. Dark mode is unbalanced.

Solution: OKLCH ensures consistent perceived lightness. L=70% looks equally bright in any color.

Impact: Balanced dark mode without manual tweaks. Better accessibility. Professional design.

5. Lucide Icons > Emojis for Professionalism

Problem: Emojis render differently across systems (Windows vs macOS vs Linux). Visual inconsistencies.

Solution: Lucide Icons – 400+ consistent, accessible SVG icons.

Impact: Visual consistency. Screen readers understand them. Elevates professionalism.

6. AI Needs Human Guardrails

Problem: Publisher-agent could auto-commit and publish mistakes.

Solution: Critical rule – NEVER commit/push without explicit user approval.

Impact: Controlled quality. Trust in the system. Avoids bad publications.

7. Specialized Prompts > Generic Prompts

Problem: One-size-fits-all prompt (“write an article about X”) yields generic output.

Solution: Eight agents with 3,170 lines of specialized prompts. Each excels at its task.

Impact: Higher-quality output. Fewer regenerations. Maintained consistency.

When (and When Not) to Use AI Agents

AI agents are not a universal solution. Here’s my honest decision framework:

✅ Use AI agents when:

You handle high volumes of repetitive content where each piece still needs to be unique.
Example: 50 product reviews – similar structure but different substance.

You have a clear editorial process that can be codified.
Example: Planning → Research → Writing → SEO → Publish is a repeatable pipeline.

You want to scale without hiring a big team.
Example: One person + eight agents can do the work of three or four people.

You have the expertise to review AI output.
AI produces fast but needs a human to validate quality and accuracy.

You value process consistency.
Agents always follow the process. Humans may skip steps.

❌ DON’T use AI agents when:

You need genuinely original creativity.
AI recombines known knowledge well; it struggles to invent something unheard of.

You produce a small volume of highly personalized content.
For five super-custom pieces per month, a human beats the setup overhead.

You lack the time/expertise to review output.
AI can hallucinate data. If you can’t validate, don’t use it.

You need deep emotional storytelling.
AI shines at technical/informational pieces. Human writing still wins at touching emotions.

You don’t have a clear editorial process.
If you don’t know what you want, AI won’t guess it.

Real trade-offs:

Aspect	Human	AI + Human Review
Speed	1–2 articles/day	15–20 articles/day
Creative quality	High	Medium-high
Consistency	Variable	High
Cost	High (salary)	Medium (API + review)
Required expertise	None (if good writer)	Yes (review output)
Scalability	Hard	Easy

My honest recommendation:

Use AI for scaled production + human review for quality. It’s not “AI replacing humans” – it’s “AI augmenting humans.”

For this project (affiliate marketing with 45 articles/month), AI agents make sense. For a personal blog with two or three deeply reflective posts a month, probably not.

Next Steps and Roadmap

AffiliateOS is actively under construction. Here’s what’s next:

Short term (next 30 days):

[ ] Implement analytics-agent for continuous monitoring
[ ] Produce the first 15 articles in the vpn-saas niche to validate SEO
[ ] Test 3–5 creative briefs and compare engagement
[ ] Apply to affiliate programs (Hostinger, Impact, Amazon)
[ ] Collect the first real traffic data

Mid term (60–90 days):

[ ] Refine routing decisions with first-party conversion data
[ ] Add automatic internal linking across related articles
[ ] Implement A/B testing for headlines and CTAs
[ ] Expand to a third niche (validate system in another vertical)
[ ] Optimize underperforming articles based on analytics

Long term (6–12 months):

[ ] Open source the agents (if validation is positive)
[ ] Automatic content refresh system for older pieces
[ ] Multi-language support (expand to EN and ES)
[ ] CRM integrations for lead nurturing
[ ] Predictive analysis of trending topics

Current limitations:

⚠️ Analytics-agent depends on real traffic (still waiting)
⚠️ Internal linking is still manual (tedious at scale)
⚠️ Content refresh isn’t automated
⚠️ Multi-language needs dedicated agents per language
⚠️ Technical data validation could be more robust

Long-term vision:

Turn AffiliateOS into an open framework for creators and agencies that want to use AI responsibly and effectively in content marketing. It’s not about “replacing writers” – it’s about giving creators superpowers.

Conclusion: Intelligent Automation, Not Replacement

After building eight specialized agents, 3,170 lines of prompts, and running dozens of experiments, here’s my honest takeaway:

AI doesn’t replace content creators. It amplifies them.

AffiliateOS agents are not “autonomous writing robots.” They’re specialized tools that let humans produce more, better, and more consistently.

The planning-agent doesn’t invent strategy alone – it collaborates with me to structure ideas. The content-agent doesn’t write without context – it follows detailed creative briefs. The publisher-agent doesn’t deploy without approval – it waits for human validation.

The magic isn’t in eliminating humans. It’s in specialization.

Each agent masters ONE thing. Planning. Routing. Research. SEO. Publishing. That division of responsibility keeps quality high at scale – impossible with a single generalist AI or generic templates.

For marketing leaders: AI agents can 10× your content output without hiring ten more people. But you still need someone with expertise to review the output, validate accuracy, and ensure brand voice alignment.

For content creators: AI won’t steal your job. It will eliminate repetitive tasks (research, SEO optimization, formatting) and free up time for what humans do best – genuine creativity, emotional storytelling, original insights.

For developers: Architecting specialized agents is a powerful pattern. Don’t build a “super agent that does everything” – build experts that collaborate. Quality comes from specialization.

Want to Use AI to Level Up Your Content Operations?

If you run a marketing team, agency, or content operation and want to explore how AI can multiply results without losing authenticity, let’s talk.

I’m not selling a product. I’m sharing the lessons from building real AI systems applied to marketing.

Reach out if you:

Manage a content team and want to scale without sacrificing quality
Work at a digital marketing agency exploring smart automation
Are a tech lead evaluating AI for content operations
Are a creator looking to scale output without becoming a generic factory

I don’t promise magic results. I promise an honest conversation about what works, what doesn’t, and how to build responsible AI systems.

Stack mentioned:

Astro – Static site framework
Claude AI – AI model (Anthropic)
Tailwind CSS – Utility-first CSS
Lucide Icons – SVG icon system
Radix UI – Headless components
Cloudflare Pages – Hosting and CDN

Agentes de IA para Marketing: Um Estudo de Caso Real de Automação de Conteúdo

jucelinux — Sun, 05 Oct 2025 22:03:30 +0000

O Desafio: 45 Artigos por Mês Sem Virar uma Fábrica de Conteúdo Genérico

Criar 45 artigos de qualidade por mês parece loucura, certo? É exatamente o que pensei quando defini essa meta para o AffiliateOS - meu experimento de marketing de afiliados automatizado com IA.

O problema não é apenas velocidade. É manter qualidade editorial, personalidade única e honestidade em escala. Ferramentas de IA genéricas (Jasper, Copy.ai e similares) geram conteúdo rápido, mas tudo soa igual - aquele tom corporativo pasteurizado que ninguém quer ler.

A hipótese que testei: e se ao invés de uma IA generalista, eu criasse 8 agentes especializados? Cada um com uma responsabilidade específica, trabalhando em conjunto como uma equipe de marketing real.

Este artigo documenta a jornada. Não é um tutorial passo-a-passo nem um case de sucesso inflado. É um relato honesto de como construí o sistema, as escolhas técnicas que fiz, os desafios que enfrentei e o que aprendi no processo.

Por Que Automação de Conteúdo é Tão Difícil

O marketing de conteúdo moderno tem um dilema cruel: escala versus qualidade.

Você precisa publicar consistentemente para ranquear no Google. Mas cada artigo precisa ser único, útil e envolvente para converter leitores. Templates ajudam com consistência, mas matam personalidade. IA genérica é rápida, mas produz conteúdo sem alma.

Aqui está o que NÃO funciona:

Templates fixos: Todo review fica idêntico. Leitores percebem. Google também.
Prompts genéricos: "Escreva um artigo sobre X" produz conteúdo superficial e previsível.
IA sem contexto: Alucina dados técnicos, ignora nuances do nicho, usa jargão errado.
Ausência de processo: Escrever direto sem planejamento resulta em estrutura fraca e SEO ruim.

O que eu precisava era um sistema com opinião - que entendesse profundamente cada etapa da criação de conteúdo e mantivesse qualidade através de especialização.

A Solução: Arquitetura de 8 Agentes Especializados

Pense em cada agente como um especialista em uma equipe de marketing. O planning-agent é o estrategista criativo. O content-agent é o escritor. O seo-agent é o analista de performance. Cada um faz uma coisa muito bem.

Aqui está a arquitetura completa:

🧠 Orchestrator Agent - Coordena todo o pipeline e toma decisões estratégicas de priorização.

📝 Planning Agent - Dialoga com você sobre a ideia do artigo e cria um creative brief detalhado (conceito, ângulo, tom, estrutura customizada).

🗺️ Routing Agent - Decide a melhor URL analisando benchmarks do nicho (ex: /coupons/ converte 4x mais que /reviews/ segundo dados de VPNMentor).

🔍 Research Agent - Pesquisa dados atualizados de produtos, analisa concorrência e valida informações antes da criação.

✍️ Content Agent - Gera o artigo seguindo o creative brief com estrutura personalizada (não templates genéricos).

🎯 SEO Agent - Otimiza meta tags, headings e keywords sem quebrar a personalidade do conteúdo.

🚀 Publisher Agent - Gerencia commits Git, deploy automático e validação de publicação.

📊 Analytics Agent - Monitora performance e sugere otimizações baseadas em dados reais (planejado - funciona após validação inicial).

O fluxo completo é: Planning → Routing → Research → Content → SEO → Publish → Analytics.

Do conceito inicial ao deploy automático, leva 20-35 minutos. Mas a mágica não está na velocidade - está na qualidade mantida através da especialização.

🛠️ Box Técnico: Arquitetura de Agentes e Prompts

Cada agente é um arquivo .md em .claude/agents/ com prompt especializado. Não são scripts executáveis - são prompts refinados que guiam o comportamento de Claude 4.5 Sonnet via Claude Code CLI.

Estatísticas do código:

8 agentes definidos (7 implementados, 1 planejado)
3.170 linhas de prompts especializados
Maior agente: content-agent (790 linhas)
Menor agente: seo-agent (305 linhas)

Por que prompts especializados > prompts genéricos:

Contexto específico: Planning-agent conhece estratégias de elicitação de requisitos. SEO-agent sabe fórmulas de meta description.
Guardrails claros: Publisher-agent tem regra crítica: NUNCA faz commit sem aprovação explícita.
Output consistente: Cada agente produz JSON/Markdown estruturado que o próximo agente consome.
Refinamento iterativo: Prompts evoluem conforme uso real. Planning v2.0 é 40% melhor que v1.0.

Exemplo de trecho do Planning Agent:

## YOUR ROLE
You are the planning-agent of AffiliateOS. Your role is to collaborate
with the user to define a complete creative brief for content creation.

## IMPORTANT PRINCIPLES
1. NEVER suggest generic templates. Each article must have unique structure.
2. ALWAYS ask clarifying questions before assuming intent.
3. BALANCE technical depth with accessibility based on target audience.
4. DEFINE specific tone - "professional" is too vague.

Ferramentas disponíveis aos agentes:

WebSearch: Buscar informações atualizadas
WebFetch: Extrair conteúdo de URLs específicas
Read/Write: Manipular arquivos do projeto
Grep/Glob: Buscar padrões no codebase
Bash: Executar comandos (git, npm, deploy)

Coordenação entre agentes:
O orchestrator-agent gerencia handoffs. Quando planning-agent gera creative-brief.json, o orchestrator verifica estrutura do JSON antes de passar para routing-agent. Isso previne erros em cascata.

Planning Agent: Como Funciona o Diálogo Colaborativo

Aqui está onde a v2.0 do AffiliateOS ficou interessante. Inicialmente, eu tinha templates fixos (review.md, comparison.md). Funcionava, mas todo conteúdo ficava com a mesma cara. Sites pasteurizados.

A solução foi criar o planning-agent - que dialoga com você antes de escrever qualquer linha.

Como funciona na prática:

Você: "Quero criar conteúdo sobre NordVPN."

Planning Agent: "Legal! Deixa eu entender melhor. Qual o objetivo desse conteúdo?"

Você: "Quero mostrar como NordVPN é bom para privacidade."

Planning Agent: "Ótimo ângulo. Que tipo de pessoa você quer atingir? Usuários iniciantes ou tech-savvy?"

Você: "Mais para iniciantes - pessoas preocupadas com privacidade mas sem conhecimento técnico."

Planning Agent: "Perfeito. E o tom? Você prefere algo educacional e acessível, ou mais agressivo tipo 'pare de ser rastreado AGORA'?"

Você: "Educacional, sem alarmismo."

Planning Agent: "Entendido. Vou criar um brief para um artigo educacional sobre privacidade com NordVPN, focado em iniciantes, tom acessível. Estrutura sugerida: [...]"

O resultado é um creative brief completo em JSON com:

Conceito único do artigo
Ângulo editorial específico
Tom personalizado
Estrutura customizada (não template genérico)
Keywords alinhadas com intenção
Guidelines de qualidade

Exemplo real do brief gerado para ESTE artigo:

{
  title: "Agentes de IA para Marketing: Um Estudo de Caso Real",
  concept: "Documentar a jornada de construção do AffiliateOS",
  angle: "Estudo de caso autêntico e educacional. Não é tutorial nem case inflado.",
  tone: "Mentor técnico acessível - entende tecnologia mas explica claramente.",
  structure: {
    type: "layered",
    description: "Camada 1 (narrativa) acessível a todos. Camada 2 (boxes técnicos) para devs."
  }
}

Essa mudança simples eliminou pasteurização. Cada artigo agora tem personalidade própria, estrutura otimizada para seu objetivo específico e tom adequado à audiência.

Routing Agent: Decisões Data-Driven de URL

Outro aprendizado crucial: a rota importa tanto quanto o conteúdo.

Quando criei os primeiros artigos, usei /reviews/ para tudo. Fazia sentido semanticamente, mas ignorava uma realidade do mercado: diferentes URLs convertem diferente.

Exemplo real de benchmarks:

Analisando o VPNMentor (líder do nicho VPN), descobri:

/coupons/nordvpn converte 4x mais que /reviews/nordvpn
/best-vpn-for-streaming ranqueia melhor que /vpn-reviews/streaming
/tools/ tem CTR 2x maior que /resources/ para conteúdo utilitário

O routing-agent automatiza essa análise. Ele:

Analisa benchmarks do nicho (VPNMentor para VPN, NerdWallet para fintech, swyx.io para tech personal brands)
Consulta o routing-config.json com métricas de conversão por rota
Decide a melhor URL baseado em intent da keyword + potencial de conversão
Justifica a decisão com dados (não achismos)

Para ESTE artigo, a decisão foi /blog/ porque:

Padrão universal de personal brands tech (swyx.io, kentcdodds.com, leerob.com)
Alinha com objetivo de construção de autoridade (não conversão imediata)
SEO otimizado para keywords informacionais de long-tail
Simplicidade vence over-engineering (não preciso de /estudos-de-caso/ separado)

🗺️ Box Técnico: Como o Routing Agent Analisa Benchmarks

O routing-agent não inventa decisões. Ele consulta o arquivo routing-config.json que mapeia rotas do site com métricas de performance.

Estrutura do routing-config.json:

{
  active_routes: [
    {
      path: "/blog",
      purpose: "Artigos de opinião, insights e reflexões técnicas",
      benchmark_sites: ["swyx.io", "kentcdodds.com", "leerob.io"],
      notes: "Authority content - builds personal brand and expertise"
    },
    {
      path: "/reviews",
      purpose: "Reviews honestos de ferramentas e SaaS",
      benchmark_sites: ["techradar.com", "theverge.com/reviews"],
      notes: "Affiliate content - monetization while maintaining authenticity"
    }
  ],
  route_performance_insights: {
    "/blog": {
      typical_ctr: "1-2%",
      intent: "informational",
      conversion_stage: "awareness-top-funnel",
      seo_potential: "high - thought leadership keywords"
    },
    "/reviews": {
      typical_ctr: "4-6%",
      intent: "commercial",
      conversion_stage: "consideration-decision",
      seo_potential: "high - product keywords"
    }
  }
}

Algoritmo de decisão:

Parse creative brief: Identifica objetivo (monetização vs autoridade), audiência e keywords
Match intent: Keywords informacionais → rotas awareness. Keywords comerciais → rotas decision.
Consulta benchmarks: Verifica o que líderes do nicho fazem para conteúdo similar
Scoring de rotas: CTR esperado × SEO potential × alinhamento com objetivo
Output: Rota escolhida + justificativa detalhada com dados

Benefício:
Rotas otimizadas para conversão desde o primeiro dia. Não preciso esperar 6 meses de A/B testing - aproveito aprendizados de campeões do nicho.

Limitação:
Benchmarks são de terceiros, não dados próprios. Após tráfego real, o analytics-agent vai refinar essas decisões com dados próprios.

Stack Tecnológica: Astro, TypeScript, Tailwind e Claude

Escolher a stack certa foi crítico. Não queria framework JS pesado (Next.js) nem CMS complexo (WordPress). Precisava de:

Performance excepcional (static site, zero JS desnecessário)
Type safety (conteúdo validado em build time, não em produção)
Developer experience impecável (hot reload rápido, componentes reutilizáveis)
SEO nativo (sitemap automático, meta tags, canonical URLs)

A stack escolhida:

🚀 Astro 5.14.1 - Framework principal para sites estáticos. Por quê?

Static site generation (SSG) - sites absurdamente rápidos
Zero JS por padrão - só carrega JavaScript quando necessário
Hidratação parcial de React - componentes interativos apenas onde precisa
Build em 30-60 segundos para site completo

⚛️ React 18.3.1 - Apenas para componentes interativos. Por quê?

ThemeToggle (dark mode) precisa de estado
Dialog/Modal (Radix UI) precisa de interatividade
Resto é Astro puro (mais rápido)

📘 TypeScript 5.4.5 - Type safety em tudo. Por quê?

Content Collections com schema Zod validam frontmatter
Componentes tipados previnem bugs
Autocomplete perfeito em VSCode

🎨 Tailwind CSS 3.4.18 - Utility-first CSS. Por quê?

Design system consistente via tokens CSS
Dark mode built-in (dark: prefix)
Componentes reutilizáveis com CVA (Class Variance Authority)

🤖 Claude 4.5 Sonnet - IA dos agentes. Por quê?

Reasoning superior para tarefas complexas (planning, routing)
Context window grande (200k tokens) - processa documentação inteira
Tools integration via Claude Code CLI

☁️ Cloudflare Pages - Hosting e deploy. Por quê?

Deploy automático via Git push
Global edge network (CDN mundial)
Zero configuração necessária
Grátis para uso pessoal

Resultado: Sites com Lighthouse score 95+ em Performance, carregamento em < 1 segundo e bundle JS de apenas 50-80KB (gzipped).

🏗️ Box Técnico: Content Collections e Type Safety

Uma das melhores features do Astro é Content Collections - type-safe content management com validação em build time.

Como funciona:

Arquivo src/content/config.ts define o schema Zod:

import { defineCollection, z } from 'astro:content';

const contentSchema = z.object({
  title: z.string(),
  description: z.string().max(160),
  slug: z.string().optional(),
  route: z.string(), // Routing dinâmico (v2.0)
  rating: z.number().min(0).max(5).optional(),
  publishDate: z.coerce.date(),
  updateDate: z.coerce.date().optional(),
  category: z.string(),
  tags: z.array(z.string()).min(1),
  author: z.string(),
  featured: z.boolean().default(false),
  affiliateLink: z.string().url().optional(),
  schema: z.record(z.unknown()).optional(),
  faq: z.array(z.object({
    question: z.string(),
    answer: z.string(),
  })).optional(),
});

const articles = defineCollection({
  type: 'content',
  schema: contentSchema,
});

export const collections = { articles };

O que isso garante:

✅ Description nunca ultrapassa 160 caracteres (limite de meta tag)
✅ Tags sempre presentes (mínimo 1)
✅ Rating entre 0-5 (nunca 6 ou -1)
✅ AffiliateLink sempre URL válida
✅ Route obrigatória (routing dinâmico v2.0)

Benefícios reais:

Erros detectados em build time, não em produção
Autocomplete de campos em VSCode ao escrever frontmatter
Impossível publicar conteúdo malformado - build falha se schema inválido
Refatoração segura - mudar schema atualiza todos os artigos

Path aliases para imports limpos:

// tsconfig.json e astro.config.mjs
{
  "@/": "src/",
  "@ui": "src/components/ui/",
  "@content": "src/content/",
  "@design-system": "src/design-system/"
}

Uso:

import { Button } from '@ui/Button'; // Não: '../../../components/ui/Button'
import { cn } from '@/lib/utils'; // Não: '../../lib/utils'

Resultado: Codebase limpa, type-safe e com developer experience de aplicações enterprise.

O Fluxo Completo: De Ideia a Deploy em 30 Minutos

Vamos seguir um artigo real do início ao fim para ver como os agentes trabalham juntos.

Cenário: Quero criar um artigo sobre "NordVPN para Netflix".

Fase 1: Planning (5-10 minutos)

Eu: "Quero criar conteúdo sobre usar NordVPN para assistir Netflix de outros países."

Planning-agent dialoga:

Qual o objetivo? (informar vs converter)
Audiência? (iniciantes vs tech-savvy)
Tom? (educacional vs promocional)
Estrutura? (tutorial vs review vs comparação)

Output: creative-brief.json com conceito único, ângulo editorial, tom personalizado e estrutura customizada.

Fase 2: Routing (2-3 minutos)

Routing-agent analisa benchmarks:

VPNMentor usa /coupons/nordvpn-netflix (alta conversão)
TechRadar usa /how-to/use-vpn-for-netflix (alto SEO)
Meu objetivo: converter (afiliado)

Decisão: /coupons/nordvpn-netflix porque conversão > volume de tráfego.

Output: routing-decision.json com rota escolhida + justificativa com dados.

Fase 3: Research (3-5 minutos)

Research-agent coleta dados:

Preço atual do NordVPN (via WebSearch)
Catálogos Netflix por país (fontes oficiais)
Reviews de usuários (Reddit, Trustpilot)
Specs técnicas (servidores, velocidade)

Output: research-report.json com dados verificáveis e fontes.

Fase 4: Content Generation (5-8 minutos)

Content-agent cria artigo:

Segue estrutura do creative brief (não template genérico)
Usa dados do research report
Mantém tom definido no planning
Inclui disclaimer de afiliado
Usa ícones Lucide (não emojis)

Output: Artigo completo em MDX com frontmatter validado.

Fase 5: SEO Optimization (2-3 minutos)

SEO-agent otimiza:

Meta description 150-160 caracteres
Title tag 50-60 caracteres
Headings hierárquicos (H1 → H2 → H3)
Keywords density 1-2% (uso natural)
Schema markup (Article structured data)
Internal links para artigos relacionados

Output: Artigo otimizado sem quebrar personalidade.

Fase 6: Publishing (1-2 minutos + 2-5 deploy)

Publisher-agent:

Salva em src/content/articles/coupons-nordvpn-netflix.md
Atualiza routing-config.json
Cria commit Git descritivo
Aguarda aprovação humana (regra crítica!)
Push para main → deploy automático Cloudflare Pages

Output: Artigo live em 2-5 minutos após push.

Total: 20-35 minutos do conceito ao deploy. 90% automatizado, 10% revisão humana.

A revisão humana é crítica - valido qualidade editorial, accuracy de dados técnicos e tom antes de aprovar o commit.

Design System: Por Que OKLCH é Superior a HSL/RGB

Um detalhe técnico que fez diferença: escolher OKLCH color space ao invés de HSL ou RGB para o design system.

Por que isso importa?

HSL tem um problema sutil mas crítico: inconsistência perceptual de brilho. Um amarelo hsl(60, 100%, 50%) parece muito mais claro que um azul hsl(240, 100%, 50%), mesmo ambos tendo L=50%.

Isso quebra dark mode - você precisa ajustar manualmente o L de cada cor para parecerem balanceadas.

OKLCH resolve isso.

OKLCH (Lightness, Chroma, Hue) foi projetado para consistência perceptual. L=70% em qualquer cor tem o mesmo brilho percebido pelo olho humano.

Benefícios reais:

✅ Dark mode balanceado sem ajustes manuais
✅ Transições de cor suaves e previsíveis
✅ Acessibilidade melhor (contraste consistente)
✅ Código mais limpo (menos magic numbers)

Implementação:

/* src/design-system/tokens.css */
:root {
  /* Light mode */
  --background: oklch(1.0000 0 0); /* Branco puro */
  --foreground: oklch(0.3588 0.1354 278.6973); /* Roxo escuro */
  --primary: oklch(0.6056 0.2189 292.7172); /* Roxo vibrante */
  --border: oklch(0.9299 0.0334 272.7879); /* Cinza claro */
}

[data-theme="dark"], .dark {
  --background: oklch(0.2077 0.0398 265.7549); /* Roxo muito escuro */
  --foreground: oklch(0.9299 0.0334 272.7879); /* Cinza claro */
  --primary: oklch(0.6056 0.2189 292.7172); /* Roxo vibrante (mesmo!) */
}

Tailwind CSS consome estes tokens via var(--background) automaticamente.

Outros tokens do design system:

Tipografia: Roboto (UI), Playfair Display (headings), Fira Code (code)
Border radius: 4 níveis (sm, md, lg, xl) baseados em --radius: 0.625rem
Shadows: 7 níveis (2xs → 2xl) com consistência OKLCH
Dark mode: Toggle React com persistência em localStorage

🎨 Box Técnico: Componentes com Class Variance Authority

Uma das melhores patterns de componentes React que descobri: Class Variance Authority (CVA).

CVA permite definir variantes de componentes de forma tipada e composável.

Exemplo: Button Component

// src/components/ui/Button.tsx
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';

const buttonVariants = cva(
  // Base classes (sempre aplicadas)
  'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
        outline: 'border border-input bg-background hover:bg-accent',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm: 'h-9 rounded-md px-3',
        lg: 'h-11 rounded-md px-8',
        icon: 'h-10 w-10',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  }
);

export const Button = ({ variant, size, className, ...props }) => {
  return (
    <button
      className={cn(buttonVariants({ variant, size, className }))}
      {...props}
    />
  );
};

Uso:

<Button variant="default" size="lg">Ver Oferta</Button>
<Button variant="outline">Saiba Mais</Button>
<Button variant="ghost" size="icon">×</Button>

Benefícios:

✅ Type-safe: TypeScript garante que variant é um valor válido
✅ Composável: Combina variantes com classes customizadas via className
✅ Consistente: Todas as variações de Button usam mesmas base classes
✅ Manutenível: Mudar estilo de todos os buttons = editar um arquivo

Utility cn() para merge de classes:

// src/lib/utils.ts
import { type ClassValue, clsx } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Combina clsx (conditional classes) com tailwind-merge (resolve conflitos de classes Tailwind). Essencial para componentes que aceitam className customizado.

Resultado: Biblioteca de componentes profissional, tipada e reutilizável - qualidade de shadcn/ui.

Resultados Reais (Sem Hype)

Projeto está em fase inicial. Vou compartilhar números honestos - sem inflar, sem esconder.

O que foi construído até agora:

✅ 8 agentes especializados (7 implementados, 1 planejado)
✅ 3.170 linhas de prompts refinados
✅ 2 nichos ativos (vpn-saas + jucelinux personal brand)
✅ 1 site deployado (vpn-reviews-br.pages.dev)
✅ Stack completa: Astro + React + TypeScript + Tailwind + Claude
✅ Routing dinâmico v2.0 com benchmarks automatizados
✅ Design system OKLCH com dark mode
✅ Pipeline completo automatizado (20-35 minutos conceito→deploy)

Velocidade de produção:

Meta inicial: 45 artigos/mês
Tempo por artigo: 20-35 minutos (automação)
Revisão humana: ~10 minutos por artigo (validação qualidade)
Total realista: 30-40 minutos por artigo (incluindo revisão)

Qualidade percebida:

Content Collections com Zod: zero artigos malformados publicados
Planning v2.0: eliminou pasteurização - cada artigo tem personalidade única
Ícones Lucide: consistência visual profissional
Design tokens OKLCH: dark mode perfeito sem ajustes manuais

Desafios enfrentados:

❌ Sincronização entre agentes - garantir que output de um serve como input válido do próximo
❌ Validação de dados - IA pode alucinar specs técnicas se não usar WebSearch
❌ SEO vs personalidade - otimizar sem keyword stuffing
❌ Decisões de routing sem dados próprios - confiar em benchmarks de terceiros inicialmente

O que funcionou bem:

✅ Planning colaborativo - dialoga antes de escrever
✅ Routing baseado em benchmarks - decisões data-driven desde dia 1
✅ Type safety via Content Collections - bugs detectados em build
✅ Prompts especializados - qualidade superior a IA genérica
✅ Guardrails humanos - publisher nunca faz commit sem aprovação

O que não funcionou (ainda):

⚠️ Analytics-agent ainda não implementado - preciso de tráfego real primeiro
⚠️ Internal linking automático - ainda manual
⚠️ A/B testing de creative briefs - preciso de volume para validar

Métricas de SEO: Aguardando primeiros 30-60 dias de indexação. Meta realista: 60% dos artigos ranqueando top 50 em 90 dias para long-tail keywords.

Receita: Zero até agora (aguardando aprovação de programas de afiliados). Meta inicial: R$50-200/mês como validação de que o sistema funciona.

Não é um case de sucesso (ainda). É um experimento em andamento com resultados promissores.

Lições Aprendidas: 7 Insights Práticos

1. Planning Colaborativo Elimina Pasteurização

Problema: Templates fixos (review.md, comparison.md) tornavam todo conteúdo idêntico.

Solução: Planning-agent dialoga antes de escrever. Cada artigo tem creative brief único com estrutura customizada.

Impacto: Qualidade editorial superior. Sites não ficam "pasteurizados". Leitores percebem autenticidade.

2. Routing Dinâmico Baseado em Benchmarks é Game-Changer

Problema: Usar /reviews/ para tudo ignorava que /coupons/ converte 4x mais (dados VPNMentor).

Solução: Routing-agent analisa benchmarks de líderes do nicho e toma decisões data-driven de URL.

Impacto: Taxas de conversão otimizadas desde dia 1. Não preciso de 6 meses de A/B testing.

3. Content Collections + Zod = Type Safety em Conteúdo

Problema: Frontmatter malformado quebrava builds. Descobrir em produção.

Solução: Schema Zod valida todo frontmatter em build time. Description > 160 chars? Build falha.

Impacto: Zero bugs de conteúdo malformado em produção. Developer experience superior.

4. OKLCH > HSL/RGB para Design Systems

Problema: HSL tem inconsistência perceptual. Amarelo L=50% parece mais claro que azul L=50%. Dark mode fica desbalanceado.

Solução: OKLCH garante consistência perceptual de brilho. L=70% tem mesmo brilho em qualquer cor.

Impacto: Dark mode balanceado sem ajustes manuais. Acessibilidade melhor. Design profissional.

5. Lucide Icons > Emojis para Profissionalismo

Problema: Emojis renderizam diferente entre sistemas (Windows vs Mac vs Linux). Inconsistência visual.

Solução: Lucide Icons - 400+ ícones SVG consistentes e acessíveis.

Impacto: Consistência visual. Screen readers entendem. Profissionalismo elevado.

6. IA Precisa de Guardrails Humanos

Problema: Publisher-agent poderia fazer commits automáticos e publicar erros.

Solução: Regra crítica - NUNCA commit/push sem aprovação explícita do usuário.

Impacto: Qualidade controlada. Confiança no sistema. Evita publicações ruins.

7. Prompts Especializados > Prompts Genéricos

Problema: Prompt único "escreva artigo sobre X" produz conteúdo genérico.

Solução: 8 agentes com 3.170 linhas de prompts especializados. Cada um domina sua função.

Impacto: Output de qualidade superior. Menos regenerações. Consistência mantida.

Quando (e Quando Não) Usar Agentes de IA

Agentes de IA não são solução universal. Aqui está meu framework de decisão honesto:

✅ Use agentes de IA quando:

Você tem volume alto de conteúdo repetitivo mas cada peça precisa ser única.
Exemplo: Reviews de 50 produtos - estrutura similar mas cada um é diferente.

Você tem processo editorial claro que pode ser codificado.
Exemplo: Planning → Research → Writing → SEO → Publish é um fluxo repetível.

Você quer escalar sem contratar grande equipe.
Exemplo: 1 pessoa + 8 agentes produz o que 3-4 pessoas fariam.

Você tem expertise para revisar output de IA.
IA gera rápido mas precisa de humano para validar qualidade e accuracy.

Você valoriza consistência de processo.
Agentes seguem o processo sempre. Humanos podem esquecer etapas.

❌ NÃO use agentes de IA quando:

Você precisa de criatividade genuinamente original.
IA é ótima em recombinar conhecimento, ruim em criar algo nunca visto.

Você tem volume baixo de conteúdo altamente personalizado.
Para 5 artigos/mês super customizados, humano é melhor que setup de agentes.

Você não tem tempo/expertise para revisar output.
IA pode alucinar dados. Se você não pode validar, não use.

Você quer conteúdo emocional profundo.
IA gera bem conteúdo técnico/informacional. Conteúdo que toca alma? Humano vence.

Você não tem processo editorial claro.
Se você mesmo não sabe o que quer, IA não vai adivinhar.

Tradeoffs reais:

Aspecto	Humano	IA + Revisão Humana
Velocidade	1-2 artigos/dia	15-20 artigos/dia
Qualidade criativa	Alta	Média-alta
Consistência	Varia	Alta
Custo	Alto (salário)	Médio (API + revisão)
Expertise necessária	Não (se bom escritor)	Sim (revisar output)
Escalabilidade	Difícil	Fácil

Minha recomendação honesta:

Use IA para produção em escala + revisão humana para qualidade. Não é "IA substituindo humanos" - é "IA como multiplicador de humanos".

Para este projeto (marketing de afiliados com 45 artigos/mês), agentes de IA fazem sentido. Para um blog pessoal com 2-3 posts/mês super reflexivos, provavelmente não.

Próximos Passos e Roadmap

O AffiliateOS está em construção ativa. Aqui está o que vem a seguir:

Curto prazo (próximos 30 dias):

[ ] Implementar analytics-agent para monitoramento contínuo
[ ] Gerar primeiros 15 artigos do nicho vpn-saas para validação SEO
[ ] Testar 3-5 creative briefs diferentes e comparar engagement
[ ] Cadastrar em programas de afiliados (Hostinger, Impact, Amazon)
[ ] Coletar primeiros dados de tráfego real

Médio prazo (60-90 dias):

[ ] Refinar routing decisions com dados próprios de conversão
[ ] Adicionar internal linking automático entre artigos relacionados
[ ] Implementar A/B testing de headlines e CTAs
[ ] Expandir para 3º nicho (validar sistema em outro vertical)
[ ] Otimizar artigos underperforming baseado em analytics

Longo prazo (6-12 meses):

[ ] Open-source dos agentes (se validação for positiva)
[ ] Sistema de content refresh automático (atualizar artigos antigos)
[ ] Multi-language support (expandir para EN e ES)
[ ] Integration com CRMs para lead nurturing
[ ] Análise preditiva de trending topics

Limitações atuais a resolver:

⚠️ Analytics-agent depende de tráfego real (aguardando)
⚠️ Internal linking ainda é manual (tedioso em escala)
⚠️ Refresh de conteúdo antigo não é automatizado
⚠️ Multi-language precisa de agentes específicos por idioma
⚠️ Validação de dados técnicos poderia ser mais robusta

Visão de longo prazo:

Transformar AffiliateOS em um framework aberto para criadores de conteúdo e agências que querem usar IA de forma responsável e efetiva. Não é "substituir escritores" - é "dar superpoderes a criadores".

Conclusão: Automação Inteligente, Não Substituição

Depois de construir 8 agentes especializados, 3.170 linhas de prompts e rodar dezenas de experimentos, aqui está minha conclusão honesta:

IA não substitui criadores de conteúdo. Ela multiplica.

Os agentes do AffiliateOS não são "robôs escritores autônomos". São ferramentas especializadas que fazem humanos produzirem mais, melhor e mais consistentemente.

O planning-agent não inventa estratégias sozinho - ele dialoga comigo para estruturar minhas ideias. O content-agent não escreve sem contexto - ele segue creative briefs detalhados. O publisher-agent não deploys sem aprovação - ele aguarda validação humana.

A mágica não está em eliminar humanos. Está em especialização.

Cada agente domina UMA coisa. Planning. Routing. Research. SEO. Publishing. Essa divisão de responsabilidades permite qualidade mantida em escala - algo impossível com uma IA generalista ou templates genéricos.

Para gestores de marketing: Agentes de IA podem 10x sua produção de conteúdo sem contratar 10 pessoas. Mas você ainda precisa de alguém com expertise para revisar output, validar accuracy e garantir alinhamento com brand voice.

Para criadores de conteúdo: IA não vai roubar seu trabalho. Vai eliminar tarefas repetitivas (research, otimização SEO, formatação) e liberar tempo para o que humanos fazem melhor - criatividade genuína, storytelling emocional, insights originais.

Para desenvolvedores: Arquitetura de agentes especializados é pattern poderosa. Não tente fazer um "super agente que faz tudo" - crie especialistas que colaboram. Qualidade vem de especialização.

Quer Usar IA para Alavancar Operações de Conteúdo?

Se você gerencia uma equipe de marketing, agência ou operação de conteúdo e quer explorar como IA pode multiplicar resultados sem perder autenticidade, vamos trocar ideias.

Não estou vendendo produto. Estou compartilhando aprendizados de quem está construindo sistemas reais de IA aplicada a marketing.

Entre em contato se você:

Gerencia equipe de conteúdo e quer escalar sem sacrificar qualidade
Trabalha em agência de marketing digital explorando automação inteligente
É tech lead avaliando IA para operações de content marketing
Criador de conteúdo buscando multiplicar produção sem virar fábrica genérica

Não prometo resultados mágicos. Prometo conversa honesta sobre o que funciona, o que não funciona e como construir sistemas de IA responsáveis.

Stack mencionada:

Astro - Framework de sites estáticos
Claude AI - Modelo de IA (Anthropic)
Tailwind CSS - Utility-first CSS
Lucide Icons - Sistema de ícones SVG
Radix UI - Componentes headless
Cloudflare Pages - Hosting e CDN

Lessons Learned with AWS Bedrock Data Automation in an IDP Product

jucelinux — Sun, 14 Sep 2025 00:19:11 +0000

Introduction

This article kicks off a series where I share lessons learned as an AI leader at a FinTech. Over the past few months, I’ve been involved in building an Intelligent Document Processing (IDP) product focused on processing payment receipts. Our goal was to extract structured information from PDFs and images in a reliable and scalable way.

To speed up development, we relied on AWS Bedrock Data Automation (BDA). The tool delivered some good results, but it also revealed unexpected limitations. Below, I share three challenges we faced—without overlooking the positives: acknowledging BDA’s strengths while exposing the pitfalls we encountered in real-world use.

Why We Chose BDA

BDA is an AWS service designed to automate data extraction from documents and images. A key feature for our use case is the creation of blueprints, artifacts that define how data should be extracted, normalized, and formatted. BDA offers two approaches for creating blueprints:

Manual (via JSON Schema): developers explicitly define the structure.
Automatic (via prompt): describe in natural language which fields to extract and how to handle them.

The second option seemed irresistible. Almost instantly, we had blueprints running with promising outputs for payment receipt extraction. That convenience—combined with the frequent updates AWS pushed during development—convinced us to go down this path.

Everything seemed fine at first. The functionality was live in production, and extractions were performing as expected. But eventually, we stumbled into a cost anomaly, and after a deeper analysis of the system’s behavior, we uncovered issues that had gone unnoticed during development.

Pitfall #1 – Blueprints Created via Prompt Are Always Document Type

One thing that took us a while to realize: every blueprint created via prompt is classified as Document, even if the base content is actually an image. During tests and development, this characteristic went unnoticed since it didn’t seem to affect extraction accuracy.

Later on, however, it came back to bite us—this time as a cost anomaly.

Pitfall #2 – Wrong Modality and Financial Impact

BDA has a feature called modality routing, which defines whether a file is processed as a document or an image. While it might sound like a minor technical detail, this setting directly affects costs:

Document: USD 0.040 per page
Image: USD 0.005 per image

Since all our blueprints were created via prompt, everything was treated as Document. During early testing, we didn’t notice a difference. But by August, reality hit: almost USD 1,000 in unexpected extra charges.

After investigating, we understood the reason: auto-generated blueprints don’t respect the image modality. The fix was to recreate them manually using JSON Schema, properly configuring Document vs. Image, and enabling routing.

I’ll own part of this: we could have validated the behavior earlier. But the critique of AWS stands—the documentation does not clearly highlight this limitation. That lack of clarity can lead to costly mistakes.

Pitfall #3 – Average Latency of 30 Seconds

The third issue was latency. Each BDA process took about 30 seconds on average.

From an architectural perspective, this was manageable. We built the system around asynchronous, event-driven flows, so the backend could handle the delay. But from the user’s perspective, 30 seconds feels painfully slow.

When a customer uploads a receipt, waiting half a minute for results undermines the experience. To address this, we adapted the application, but naturally we compared alternatives. In some cases, pipelines using Textract + LLMs or OCR + post-processing delivered similar results with lower latency and comparable costs.

The Positive Side of BDA

Despite these challenges, BDA did provide real benefits:

Abstracts complexity: we didn’t have to build an IDP pipeline from scratch.
Fast initial delivery: we quickly deployed a working prototype.
Lower barrier to entry: smaller teams can experiment with IDP without heavy infrastructure investment.

In our case, BDA acted as an initial accelerator. Without it, launching the first version would have taken longer. The key takeaway is knowing when it makes sense to rely on it and when alternative approaches may be more effective.

Conclusion

After three months with AWS Bedrock Data Automation, these were our main takeaways:

Blueprints created via prompt are always Document type.
Incorrect modality settings can lead to major cost overruns.
30-second latency hurts the user experience.

These issues are not clearly stated in the documentation. Only real-world usage exposed them. For me, this reinforces an important lesson: AI leadership requires not only enthusiasm for new solutions but also critical thinking to weigh trade-offs.

BDA has value, but it’s not a universal solution. Knowing when to adopt it—and when to replace it—is part of technical maturity.

In upcoming articles, I plan to share more behind-the-scenes experiences from AI projects in the financial sector. Hopefully, these insights help others avoid similar pitfalls and make more informed decisions.

Aprendizados com o AWS Bedrock Data Automation em um Produto de IDP

jucelinux — Sun, 14 Sep 2025 00:15:50 +0000

Introdução

Esse artigo inaugura uma série em que compartilho aprendizados como liderança de IA em uma FinTech. Nos últimos meses, estive envolvido na criação de um produto de Intelligent Document Processing (IDP) voltado para o processamento de comprovantes de pagamento. Nossa meta era extrair informações estruturadas de PDFs e imagens de forma confiável e escalável.

Para acelerar o desenvolvimento, apostamos no AWS Bedrock Data Automation (BDA). A ferramenta nos touxe bons resultados, porém também nos revelou limitações inesperadas. A seguir, compartilho três desafios que enfrentamos, mas sem deixar de lado os bons resultados: reconhecer os pontos fortes do BDA e expor as armadilhas que encontramos no uso real.

Por que escolhemos o BDA?

O BDA é um serviço da AWS voltado à automação da extração de dados em documentos e imagens. Um recurso útil para nosso caso de uso é a criação de blueprints, artefatos que descrevem como os dados devem ser extraídos, normalizados e formatados. O BDA oferece duas alternativas para criação de blueprints:

Manual (via JSON Schema): o desenvolvedor define toda a estrutura.
Automática (via prompt): basta escrever em linguagem natural quais campos extrair e como tratá-los.

A segunda opção parecia irresistível e preguiçosa. Instantâneamente já tínhamos blueprints funcionando e saídas promissoras na extração de dados de comprovantes. Essa facilidade, seguida das recorrentes atualizações que foram realizadas no decorrer do desenvolvimento nos convenceu a seguir por esse caminho.

Tudo parecia bem. A funcionalidade estava no ambiente produtivo, estávamos performando as extrações como esperado. Porém em algum momento nos deparamos com uma anomalia de custos e após uma análise mais apurada sobre o comportamento esbarramos com alguns problemas que não foram observados durante o desenvolvimento.

Pitfall #1 – Blueprints criadas por prompt sempre são da Modalidade de Documentos

Algo que demorou para identificarmos: toda blueprint criada por prompt é tratada como Documento, mesmo que o documento base para esta blueprint seja de imagem. Durante os testes e durante o período de desenvolvimento, essa característica passou despercebida sem gerar qualquer impacto aparente em nossas extrações e testes.

Essa característica veio nos impactar mais tarde, mas de uma forma muito mais séria: gerando uma anomalia de custos!

Pitfall #2 – Modalidade incorreta e impacto financeiro

O BDA possui o recurso de roteamento por modalidade, que define se um arquivo será processado como documento ou como imagem. Embora pareça ser apenas uma configuração mais técnica, essa configuração tem um impacto direto no custo da solução, já que a AWS te cobra da seguinte forma:

Documento: USD 0,040 por página.
Imagem: USD 0,005 por imagem.

Como criamos as blueprints via prompt, todas foram tratadas como Documentos. Durante os testes não percebemos diferença, mas em agosto o pior aconteceu: quase USD 1.000 extras na fatura.

Após investigar o comportamento, entendemos o motivo: as blueprints criadas automaticamente não respeitam a modalidade de imagem. Depois de identificado o motivo, a solução foi recriá-las manualmente com JSON Schema, configurando corretamente Documento ou Imagem, além de ativar a configuração de roteamento.

Reconhecer as falhas e estar mais preparado para evitar erros é o que nos faz crescer. Então assumo aqui que poderíamos ter sido mais ágeis em validar esse comportamento e garantir o esperado, mas a crítica à AWS permanece: a documentação não destaca um detalhe tão importante. Essa falta de clareza pode gerar prejuízos.

Pitfall #3 – Latência média de 30 segundos

O terceiro ponto foi a latência. Cada processamento no BDA levava em torno de 30 segundos.

Na arquitetura, lidamos bem com isso. Implementamos fluxos assíncronos baseados em eventos, o que permite esperar sem travar o sistema. Porém, do ponto de vista do usuário, 30 segundos são sentidos como lentidão.

O cliente que envia um comprovante precisa esperar meio minuto até ter retorno. Para mitigar, adaptamos nossa aplicação, mas a comparação com alternativas foi inevitável. Em alguns casos, pipelines com Textract + LLM ou OCR + pós-processamento conseguem latências menores, com custo semelhante.

O lado positivo do BDA

Apesar das dificuldades, o BDA trouxe benefícios claros:

Abstração da complexidade: não começamos do zero na construção do IDP.
Velocidade inicial: rapidamente colocamos um protótipo em produção.
Acesso facilitado: equipes menores conseguem experimentar IDP sem montar toda a infraestrutura.

No nosso caso, ele serviu como acelerador inicial. Sem o BDA, levaríamos mais tempo para lançar a primeira versão. O ponto central é saber medir quando ele faz sentido e quando outras alternativas são mais vantajosas.

Conclusão

Depois de três meses de uso, esses foram nossos principais aprendizados:

Blueprints criadas por prompt sempre são Documentos.
Modalidade mal configurada pode disparar os custos.
Latência de 30s compromete a experiência do usuário.

Esses pontos não aparecem de forma clara na documentação. Só a prática mostrou seus impactos. Isso reforça uma lição importante: liderar em IA exige tanto entusiasmo por novas soluções quanto senso crítico para avaliar trade-offs.

O BDA tem valor, mas não é solução universal. Saber quando adotá-lo e quando substituí-lo é parte da maturidade técnica.

Nos próximos artigos, pretendo compartilhar outros bastidores de projetos de IA no mercado financeiro. Espero que esses insights ajudem a evitar armadilhas semelhantes e inspirem decisões mais conscientes.

Testronaut: 🤖 O Agente que Faz os Testes que Eu Me Recuso a Fazer 🚀

jucelinux — Tue, 29 Apr 2025 12:33:28 +0000

TL;DR;

Construí o Testronaut, um agente autônomo de testes com IA, em apenas algumas semanas.

Ele transforma descrições em linguagem natural como "Faça login no app e verifique a página inicial" em testes web estruturados e automatizados usando o Playwright MCP.

Neste artigo, vou falar um pouco sobre:

Por que modelos locais (como Llama3.2 e Qwen2.5) me decepcionaram
Como dominar os fundamentos foi melhor que usar frameworks da moda
Como o Google ADK me ajudou a criar um sistema de colaboração entre agentes
Como o Testronaut planeja, executa e documenta tudo automaticamente

E o mais importante:

O trabalho apenas começou — estou construindo a base para o que pode se tornar a uma plataforma open-source de testes com IA.

🔗 Veja o repositório completo do Testronaut aqui!

Introdução

Nas últimas semanas, a Microsoft lançou o Playwright MCP, uma extensão inovadora do ecossistema Playwright que abriu várias possibilidades para automação.

Ao contrário das ferramentas tradicionais de automação de browser que exigem scripts manuais, o Playwright MCP introduziu o Model Context Protocol — uma forma de agentes de IA e sistemas externos interagirem com o navegador via comandos estruturados, permitindo um novo nível de abstração e controle.

Assim que li sobre isso, uma ideia me veio imediatamente:

"E se eu finalmente pudesse criar um agente que testasse minhas aplicações por mim, sem precisar escrever uma linha de código Selenium ou Playwright?"

Essa ideia marcou o início do Testronaut — um agente de IA autônomo projetado para transformar intenções em linguagem natural em testes web reais e documentados.

Neste artigo, quero compartilhar como construí isso em poucas semanas, as lições aprendidas ao longo do caminho, e por que acredito que estamos entrando em uma nova era para testes de software.

Definindo os Requisitos

Uma das premissas principais do Testronaut era clara desde o início:

Usar ferramentas open-source, manter gratuito e rodar localmente.

Inicialmente, imaginei que poderia lidar com todo o fluxo de automação usando o Ollama e modelos locais na minha máquina.

Parecia perfeito — baixo custo, controle total e nenhuma dependência de APIs na nuvem.

Porém, após vários dias apanhando com modelos como llama3.2:3b, llama3.1 e qwen2.5:14b, a realidade veio à tona:

A maioria dos desafios não era por causa da lógica do agente — mas sim pelas limitações de desempenho dos modelos locais.

Eles simplesmente não conseguiam raciocinar rápido o suficiente, falhavam em seguir planos com vários passos ou consumiam muitos recursos sob carga real.

Explorei alguns frameworks populares:

Cada um oferecia ideias e ferramentas interessantes, mas logo percebi algo essencial:

O maior desafio não é escolher o framework certo. É dominar os fundamentos — entender como agentes pensam, raciocinam e interagem.

(Óbvio? Talvez. Doloroso de aprender na prática? Com certeza.)

Aprendendo da Maneira Difícil (Sem Atalhos)

Assim como fazíamos antes da era do ChatGPT, voltei aos fundamentos:

Abri a documentação do Google ADK — minha escolha final de framework — e decidi realmente entender:

Como agentes autônomos funcionam
Como o Google ADK pode estruturar uma solução real
Como integrar corretamente as ferramentas (ao invés de apenas plugar um modelo e torcer por magia)

Parecia artesanato ancestral — como os astecas construindo algo sólido, pedra por pedra, sem atalhos.

Ler, experimentar e falhar (muito) virou minha rotina.

E aos poucos, a imagem ficou clara:

Construir um agente confiável não era sobre prompts mirabolantes ou modelos gigantes — era sobre desenhar um cérebro que pudesse:

Interpretar intenções com clareza
Planejar ações com lógica
Executar os passos com cuidado
Documentar cada movimento com precisão

Em outras palavras, não era "criar um chatbot inteligente", mas sim "construir um agente autônomo sério e disciplinado."

Definindo a Solução

Depois que entendi como construir agentes autônomos, o próximo passo era decidir o que exatamente o Testronaut deveria fazer.

Com um entendimento claro do propósito da plataforma, pude definir suas funcionalidades principais:

1. Criar um Plano de Testes a partir de uma Intenção em Linguagem Natural

O Testronaut nasceu para ajudar times de desenvolvimento a validar fluxos críticos de usuário, jornadas de experiência ou até scripts simples como:

"Acesse https://www.saucedemo.com/ e verifique se a página inicial carrega.

Preencha o formulário de login com standard_user e secret_sauce.

Na página de produtos, tire um snapshot do primeiro produto disponível."

(Nota rápida: SauceDemo é um site público criado especificamente para testes de QA, comumente usado em práticas de automação.)

A capacidade de descrever testes em linguagem natural é poderosa:

Permite que desenvolvedores — mesmo sem experiência em QA — simplesmente expressem o que desejam validar em português ou inglês comum.

O Testronaut transforma essa narrativa informal em um Plano de Teste estruturado, definindo explicitamente os resultados esperados de cada etapa.

Por exemplo, a narrativa acima se transforma em:

{
  "test_plan": {
    "name": "Teste de Carregamento da Homepage e Snapshot do Produto",
    "description": "Verificar o carregamento da homepage, login com credenciais padrão e captura de snapshot do primeiro produto na página de produtos.",
    "steps": [
      {
        "step": 1,
        "action": "Navegar para https://www.saucedemo.com/",
        "expected_result": "Homepage carregada com sucesso e visível."
      },
      {
        "step": 2,
        "action": "Verificar se o conteúdo da homepage está correto.",
        "expected_result": "Conteúdo da homepage visível e correto."
      },
      {
        "step": 3,
        "action": "Preencher o formulário de login com usuário 'standard_user' e senha 'secret_sauce' e submeter.",
        "expected_result": "Login realizado com sucesso e redirecionamento para a página de produtos."
      },
      {
        "step": 4,
        "action": "Na página de produtos, localizar o primeiro produto disponível.",
        "expected_result": "Primeiro produto localizado e visível."
      },
      {
        "step": 5,
        "action": "Tirar um snapshot do primeiro produto.",
        "expected_result": "Snapshot do primeiro produto salvo com sucesso."
      }
    ]
  }
}

Ao estruturar a intenção em JSON, o Testronaut consegue planejar, executar e documentar cada passo sistematicamente.

2. O Agente Executor

Com o Plano de Testes criado, o próximo passo natural era executá-lo.
Para isso, eu precisava de um segundo agente: um que fosse capaz de ler o Plano de Testes e realizar as ações correspondentes no navegador usando o Playwright MCP.

Felizmente, o Google ADK torna extremamente simples a integração com servidores MCP externos.

Veja como conectei o agente ao servidor Playwright MCP:

async def get_playwright_mcp_toolset():
    """Cria e configura o conjunto de ferramentas MCP.

    Retorna:
        Tuple[MCPToolset, AsyncExitStack]: O conjunto de ferramentas configurado e seu exit stack.
    """
    print("Tentando conectar ao servidor MCP Playwright...")
    tools, exit_stack = await MCPToolset.from_server(
        connection_params=StdioServerParameters(
            command='npx',
            args=["@playwright/mcp@latest", "--headless"],
        )
    )
    return tools, exit_stack

E dentro da definição do agente:

async def get_test_executor_agent():
    tools, exit_stack = await get_playwright_mcp_toolset()
    test_executor_agent = Agent(
        model=LiteLlm(
            model=constants.MODEL
        ),
        name="testronaut_test_executor",
        description="Um assistente inteligente para execução de testes.",
        instruction=prompt.TEST_EXECUTOR_PROMPT,
        output_key="STATE_TEST_EXECUTOR",
        tools=[get_test_plan, *tools]
    )
    return test_executor_agent, exit_stack

Dessa forma, o Agente Executor é capaz de:

Recuperar o Plano de Testes completo do estado da sessão;
Iterar passo a passo;
Executar ações precisas no navegador via MCP;
Analisar o estado atualizado da interface após cada ação;
Avançar para o próximo passo de forma inteligente.

Tudo que faltava era habilitar a colaboração entre os agentes...

3. Montando o Megazord Testronaut

O Google ADK fornece agentes especializados para coordenar a execução de múltiplos sub-agentes.
Eles são chamados de Workflow Agents.

Para o Testronaut, usei o mais simples e eficaz:
o Sequential Agent, que conecta os dois agentes que eu havia desenvolvido (o Planner e o Executor).

Veja como a conexão final ficou:

sequential_agent = SequentialAgent(
    name="TestronautEntrypointAgent",
    sub_agents=[test_planner_agent, test_executor_agent],
)

Simples assim!

Agora, os dois agentes colaboram perfeitamente:

O Test Planner cria um plano de testes estruturado a partir de uma entrada em linguagem natural;
O Test Executor interpreta esse plano e o executa passo a passo em um navegador real;

Essa colaboração forma o núcleo do que chamo de Testronaut — um agente autônomo capaz de entender intenções, executá-las com precisão e documentar cada etapa do caminho.

Conclusão: O Trabalho Apenas Começou!

Desenvolver o Testronaut me ajudou a entender os verdadeiros fundamentos por trás da construção de sistemas de colaboração entre agentes.

Não se tratava apenas de programar — era sobre aprender como agentes inteligentes podem planejar, executar e trabalhar juntos em direção a um objetivo comum.

O Testronaut ainda está dando seus primeiros passos.
Mas a visão para sua evolução já está bem definida e publicada abertamente em seu Manifesto.

Os próximos marcos serão compartilhados com todos vocês — e quem sabe, talvez uma comunidade surja para transformar o Testronaut em...

"A aplicação definitiva para testes comportamentais."

Obrigado por ler! 🚀
Fique ligado — a jornada está apenas começando.

Testronaut: 🤖 The Agent that does the Testing I refuse to do🚀

jucelinux — Mon, 28 Apr 2025 19:43:25 +0000

TL;DR;

I built Testronaut, an autonomous testing agent powered by AI, in just a few weeks.

It turns natural language descriptions like "Login to the app and check the homepage" into structured, automated web tests using Playwright MCP.

In this article, I share:

Why local models (like Llama3.2 and Qwen2.5) failed me
How mastering fundamentals was better than picking fancy frameworks
How Google ADK helped me create specialized collaborating agents
How Testronaut plans tests, executes them, and documents everything automatically

And most importantly:

The work has just begun — I’m building the foundation for what might become the best open-source AI testing platform out there.

🔗 Check out the full Testronaut repository here!

Introduction:

In last weeks, Microsoft released Playwright MCP, an innovative extension to the Playwright ecosystem that opened up a world of new possibilities for automation.

Unlike traditional browser automation tools that require direct scripting, Playwright MCP introduced a Model Context Protocol — a way for AI agents and external systems to interact with the browser via structured commands, enabling a new level of abstraction and control.

As soon as I read about it, one thought immediately crossed my mind:

"What if I could finally build an agent that tests my applications for me, without having to write a single line of Selenium or Playwright code ever again?"

That idea marked the beginning of Testronaut — an autonomous AI agent designed to transform natural language intentions into real, documented web tests.

In this article, I want to share how I built it in just a few weeks, the lessons I learned along the way, and why I believe we're entering a new era of software testing.

Defining the Requirements

One of the key premises for Testronaut was clear from the start:

Use open-source tools, keep it free, and make it run locally.

I initially imagined that I could handle the entire automation flow using Ollama and local models running on my machine.

It sounded perfect — low cost, full control, and no dependency on cloud APIs.

However, after several days struggling with various local models like llama3.2:3b, llama3.1, and qwen2.5:14b, a painful reality became clear:

Most of the challenges I faced were not because of the agent logic — they were because of the performance limitations of local models.

They simply couldn't reason fast enough, lacked consistency when following multi-step plans, or consumed too many resources under real-world load.

Along the way, I explored a few popular frameworks:

Each one offered interesting ideas and tools, but I quickly realized something essential:

The biggest challenge isn’t about picking the right framework. It's about mastering the fundamentals — understanding how agents think, reason, and interact.

(Obvious? Maybe. Painful to learn the hard way? Definitely.)

Learning the Hard Way (No Shortcuts)

So, just like we used to do in the pre-ChatGPT era, I went back to basics:

I opened the Google ADK documentation — my final framework choice — and decided to truly understand:

How autonomous agents are supposed to work
How the Google ADK could help me structure a real solution
How to properly integrate the right tools (instead of just plugging in a model and hoping for magic)

It felt a bit like ancient craftsmanship — like the Aztecs building something solid, one stone at a time, without shortcuts.

Reading, experimenting, and failing (a lot) became my daily routine.

And slowly, a clear picture started to emerge:

Building a reliable agent wasn't about fancy prompts or huge models — it was about designing a brain that could:

Interpret intentions clearly
Plan actions systematically
Execute steps carefully
Document every move reliably

In other words, it was less "make a smart chatbot" and more "build a serious, disciplined autonomous worker."

Defining the Solution

Once I figured out how to build autonomous agents, the next important step was to decide what exactly the Testronaut should do.

With a clear understanding of the platform's goal, I was able to define its core functionalities:

1. Creating a Test Plan from a Natural Language Intention

Testronaut was born to help dev teams validate critical user flows, experience journeys, or even very simple scripts such as:

"Navigate to https://www.saucedemo.com/ and verify the homepage loads.

Fill the login form with standard_user and secret_sauce.

In the Products Page, take a snapshot of the first product available."

(Quick note: SauceDemo is a public website designed specifically for QA testing, commonly used for automation practice and demos.)

The ability to describe tests in natural language is powerful:

It allows developers — even those without deep QA expertise — to simply express what they want to validate using plain English.

Testronaut takes that informal narrative and transforms it into a structured Test Plan, explicitly defining the expected outcomes of each step.

For example, the above narrative would become:

{
  "test_plan": {
    "name": "Homepage Load and Product Snapshot Test",
    "description": "Verify homepage loads correctly, login with standard credentials, and capture a snapshot of the first product on the products page.",
    "steps": [
      {
        "step": 1,
        "action": "Navigate to https://www.saucedemo.com/",
        "expected_result": "Homepage loads successfully and is visible."
      },
      {
        "step": 2,
        "action": "Verify homepage content loads correctly.",
        "expected_result": "Homepage content is visible and correct."
      },
      {
        "step": 3,
        "action": "Fill the login form with username 'standard_user' and password 'secret_sauce' and submit.",
        "expected_result": "Login is successful and user is redirected to the Products page."
      },
      {
        "step": 4,
        "action": "On the Products page, locate the first product available.",
        "expected_result": "First product is located and visible."
      },
      {
        "step": 5,
        "action": "Take a snapshot of the first product.",
        "expected_result": "Snapshot of the first product is saved."
      }
    ]
  }
}

By structuring the intention into JSON, Testronaut could now plan, execute, and document every step systematically.

2. The Executor Agent

With the Test Plan created, the next natural step was to execute it.

For that, I needed a second agent: one capable of reading the Test Plan and performing the corresponding browser actions using Playwright MCP.

Fortunately, the Google ADK makes it extremely simple to integrate with external MCP servers.

Here’s how I connected the agent to a Playwright MCP server:

async def get_playwright_mcp_toolset():
    """Create and configure the MCP toolset.

    Returns:
        Tuple[MCPToolset, AsyncExitStack]: The configured toolset and its exit stack.
    """
    print("Attempting to connect to MCP Playwright server...")
    tools, exit_stack = await MCPToolset.from_server(
        connection_params=StdioServerParameters(
            command='npx',
            args=["@playwright/mcp@latest", "--headless"],
        )
    )
    return tools, exit_stack

And inside the agent definition:

async def get_test_executor_agent():
    tools, exit_stack = await get_playwright_mcp_toolset()
    test_executor_agent = Agent(
        model=LiteLlm(
            model=constants.MODEL
        ),
        name="testronaut_test_executor",
        description="A helpful assistant for test execution.",
        instruction=prompt.TEST_EXECUTOR_PROMPT,
        output_key="STATE_TEST_EXECUTOR",
        tools=[get_test_plan, *tools]
    )
    return test_executor_agent, exit_stack

By setting it up this way, the Test Executor Agent is able to:

Retrieve the full Test Plan from the session state;
Iterate step-by-step;
Execute precise browser actions via MCP;
Analyze the updated UI state after each action;
Move on to the next step intelligently; All that remains is enabling collaboration between the agents... --- ### 3. Assembling the ~~Megazord~~ Testronaut

The Google ADK provides specialized agents for coordinating the execution of multiple sub-agents.

They're called Workflow Agents.

For Testronaut, I used the simplest and most effective one:

the Sequential Agent, which connects the two agents I had developed (the Planner and the Executor).

Here's how the final connection looks:

sequential_agent = SequentialAgent(
    name="TestronautEntrypointAgent",
    sub_agents=[test_planner_agent, test_executor_agent],
)

All that remains is enabling collaboration between the agents...

3. Assembling the Megazord Testronaut

The Google ADK provides specialized agents for coordinating the execution of multiple sub-agents.

They're called Workflow Agents.

For Testronaut, I used the simplest and most effective one:

the Sequential Agent, which connects the two agents I had developed (the Planner and the Executor).

Here's how the final connection looks:

sequential_agent = SequentialAgent(
    name="TestronautEntrypointAgent",
    sub_agents=[test_planner_agent, test_executor_agent],
)

Simple as that!

Now, the two agents collaborate seamlessly:

The Test Planner creates a structured test plan from a natural language input;
The Test Executor reads that plan and executes it step-by-step in a real browser;

This collaboration forms the core of what I call the Testronaut — an autonomous agent capable of understanding intentions, executing them accurately, and documenting every step along the way.

Conclusion: The Work Has Just Begun!

Developing Testronaut helped me understand the true fundamentals behind building multi-agent collaboration systems.

It wasn't just about coding — it was about learning how intelligent agents can plan, execute, and work together towards a common goal.

Testronaut is still taking its very first steps.

But the vision for its evolution is already well defined and publicly shared in its Manifesto.

The next milestones will be shared with you all — and who knows, maybe a community will emerge to transform Testronaut into...

"The ultimate application for behavioral testing."

Thanks for reading! 🚀
Stay tuned — the journey has just begun.