DEV Community: Alair Joao Tavares

Debugging Legacy Bottlenecks with AI: A Systematic Workflow for Complex Codebases

Alair Joao Tavares — Fri, 21 Aug 2026 13:09:26 +0000

Debugging Legacy Bottlenecks with AI: A Systematic Workflow for Complex Codebases

Legacy codebases have a particular kind of gravity. The older and more critical the system, the more carefully you have to move — every change risks pulling on threads you didn't know were connected. I spent a significant chunk of a recent high-intensity day doing exactly this: stabilizing a production admin platform, resolving a long-standing bug in a cash-polling monitoring system, and doing it all without breaking the existing business logic that the platform depends on.

What made the difference wasn't just experience or patience — it was integrating Claude Code into my debugging workflow in a deliberate, systematic way. I want to walk through how I approach legacy debugging with AI assistance, what worked, what didn't, and the mental model I've developed for using these tools safely in production-critical environments.

The Problem with Legacy Debugging

When I say "legacy bottlenecks," I don't necessarily mean old code. I mean code that carries institutional weight: business logic baked into its structure, undocumented assumptions, and a blast radius large enough that a careless refactor can cascade into production incidents.

The specific issue I was debugging involved an alarm system in a cash-polling monitor. The bug was subtle: transient errors were triggering alarms that weren't being cleared when subsequent successful operations resolved the underlying problem. The system was crying wolf — but on a platform where financial monitoring is involved, a persistent false alarm is almost as bad as a missed real one.

The codebase had grown organically. The alarm logic was spread across several modules, and the state transitions weren't immediately obvious from reading any single file. This is the exact scenario where AI-assisted navigation earns its keep.

Step 1: Use AI to Build a Map Before You Touch Anything

The worst mistake I used to make in legacy debugging was jumping straight to the suspicious area and starting to poke at it. You end up with a local understanding of a global problem.

My first step now is to use Claude Code as a navigator, not a fixer. I paste in the relevant modules and ask it to explain the data flow and state transitions without suggesting any changes. The goal is to build a shared mental model.

For the alarm issue, I fed in the polling service, the alarm manager, and the error-handling middleware, then asked:

"Walk me through how an alarm gets raised and then cleared in this system. Don't suggest fixes — just trace the execution path."

The response surfaced something I'd missed on my initial read: the alarm clear condition was only evaluated at the start of a polling cycle, not at the end. So if an error occurred mid-cycle, the alarm fired — but the successful completion of that same cycle never triggered a clear check. The fix was straightforward once I understood the flow, but finding it manually would have taken significantly longer.

Here's a simplified TypeScript example of the pattern I found — and the corrected version:

// BEFORE: Alarm clear only evaluated at cycle start
class PollingMonitor {
  private alarmActive: boolean = false;

  async runCycle(): Promise<void> {
    // Clear check only happens here, at the top
    if (this.alarmActive) {
      await this.evaluateClearCondition();
    }

    try {
      await this.pollCashData();
    } catch (error) {
      this.alarmActive = true;
      await this.triggerAlarm(error);
    }
  }

  private async evaluateClearCondition(): Promise<void> {
    // This never sees the result of the current cycle
    const lastKnownStatus = await this.getLastStatus();
    if (lastKnownStatus === 'healthy') {
      this.alarmActive = false;
      await this.clearAlarm();
    }
  }
}

// AFTER: Alarm clear evaluated after successful completion
class PollingMonitor {
  private alarmActive: boolean = false;

  async runCycle(): Promise<void> {
    try {
      await this.pollCashData();

      // If we get here, the cycle succeeded — check if we should clear
      if (this.alarmActive) {
        await this.clearAlarm();
        this.alarmActive = false;
      }
    } catch (error) {
      if (!this.alarmActive) {
        this.alarmActive = true;
        await this.triggerAlarm(error);
      }
    }
  }
}

The fix is small. The understanding required to make it safely is not. That's the distinction I keep coming back to.

Step 2: Validate Assumptions with Targeted Tests Before Refactoring

Once I had a theory about the bug, I didn't immediately write the fix. I wrote a test that would fail against the current behavior and pass against the intended behavior. This is something I've adopted from TDD, but it's especially valuable in legacy contexts because it forces you to articulate exactly what you believe the broken behavior is.

I asked Claude Code to help me draft the test case based on the execution trace we'd built together:

import { PollingMonitor } from './polling-monitor';

describe('PollingMonitor alarm lifecycle', () => {
  let monitor: PollingMonitor;
  let mockPollCashData: jest.Mock;
  let mockTriggerAlarm: jest.Mock;
  let mockClearAlarm: jest.Mock;

  beforeEach(() => {
    mockPollCashData = jest.fn();
    mockTriggerAlarm = jest.fn();
    mockClearAlarm = jest.fn();

    monitor = new PollingMonitor({
      pollCashData: mockPollCashData,
      triggerAlarm: mockTriggerAlarm,
      clearAlarm: mockClearAlarm,
    });
  });

  it('should clear an active alarm when a subsequent cycle succeeds', async () => {
    // First cycle: simulate a transient error
    mockPollCashData.mockRejectedValueOnce(new Error('Connection timeout'));
    await monitor.runCycle();
    expect(mockTriggerAlarm).toHaveBeenCalledTimes(1);

    // Second cycle: the error resolves itself
    mockPollCashData.mockResolvedValueOnce({ status: 'healthy' });
    await monitor.runCycle();

    // This was the failing assertion before the fix
    expect(mockClearAlarm).toHaveBeenCalledTimes(1);
  });

  it('should not trigger duplicate alarms for consecutive failures', async () => {
    mockPollCashData.mockRejectedValue(new Error('Persistent failure'));

    await monitor.runCycle();
    await monitor.runCycle();
    await monitor.runCycle();

    // Alarm should only trigger once, not three times
    expect(mockTriggerAlarm).toHaveBeenCalledTimes(1);
  });
});

Running this test against the unmodified code confirmed my hypothesis. The first test failed exactly as predicted. That gave me confidence that I understood the bug correctly before writing a single line of fix.

This approach — hypothesis → test → fix → verify — is the safest loop I've found for legacy work. It also gives you regression coverage as a free byproduct.

Step 3: Constrain the AI to Your Boundaries

One of the most important skills I've developed with AI-assisted debugging is learning to be explicit about constraints. Claude Code, like any capable tool, will try to be helpful — and in a legacy codebase, "helpful" can mean suggesting a refactor that's technically cleaner but breaks something you can't see from the snippet you shared.

I've started prefacing my prompts with explicit guardrails:

"The following code is in production and changes must be minimal. Do not suggest renaming, restructuring, or extracting new abstractions. Only address the specific behavior described."

This sounds obvious, but it makes a real difference. Without this framing, I'd frequently get responses that rewrote the entire class in a more idiomatic style — which might be correct in isolation but introduces risk in a system with dozens of call sites I haven't audited.

The same principle applies when I'm using AI to help with TypeScript type safety in legacy modules. A lot of the codebases I work in have any types scattered through them, and while I want to improve type coverage, I don't want to do it all at once. I ask the AI to tighten types only in the specific function being modified, and to use type assertions at boundaries rather than propagating changes:

// I'll often see this in legacy code
function processAlarmPayload(payload: any): void {
  const severity = payload.severity;
  const timestamp = payload.timestamp;
  // ...
}

// My constrained improvement: type the function boundary, leave internals stable
interface AlarmPayload {
  severity: 'low' | 'medium' | 'high' | 'critical';
  timestamp: string;
  sourceId: string;
  message?: string;
}

function processAlarmPayload(payload: AlarmPayload): void {
  // Internal logic unchanged — we've only added a typed contract at the boundary
  const severity = payload.severity;
  const timestamp = payload.timestamp;
  // ...
}

Small, bounded improvements compound over time without introducing the risk of a big-bang refactor.

Step 4: Document What You Learned, Not Just What You Changed

This is the step I most often skipped when I was less experienced, and I've come to think of it as the most important one for legacy systems specifically.

After resolving the alarm bug, I didn't just commit the fix. I added a comment block explaining why the clear check happens at the end of a successful cycle rather than the beginning — and what the consequence of moving it back would be. Future me, or anyone else touching this code, deserves to know the answer is deliberate:

async runCycle(): Promise<void> {
  try {
    await this.pollCashData();

    /**
     * Alarm clear is intentionally evaluated AFTER successful poll completion,
     * not at cycle start. Evaluating at the start would miss cases where the
     * current cycle itself resolves a transient error — the alarm would persist
     * until the *next* cycle started, causing false-positive alert fatigue.
     * 
     * See: [issue tracker reference or PR link]
     */
    if (this.alarmActive) {
      await this.clearAlarm();
      this.alarmActive = false;
    }
  } catch (error) {
    if (!this.alarmActive) {
      this.alarmActive = true;
      await this.triggerAlarm(error);
    }
  }
}

I've also started keeping a short debugging log in my PR descriptions that captures the hypothesis, the test that confirmed it, and the decision rationale for the approach taken. Claude Code actually helps here too — I'll dump my session notes and ask it to help me synthesize them into a coherent PR description. It's a small thing but it dramatically improves code review quality.

Practical Tips for AI-Assisted Legacy Debugging

Start with comprehension, not modification. Always ask the AI to explain before it suggests. The explanation step catches misunderstandings before they become bad fixes.

Feed context incrementally. Don't paste an entire legacy codebase and ask what's wrong. Start with the module closest to the bug, add neighboring modules only when the AI identifies a gap. This keeps the context window focused and the responses more precise.

Treat AI suggestions as hypotheses. Every suggestion the AI makes is a starting point for investigation, not a conclusion. I verify suggestions against my actual test suite before committing to them.

Use AI to generate edge case tests. Once I have a working fix, I'll ask Claude Code: "What edge cases might this implementation miss?" It reliably surfaces scenarios I didn't think to test — race conditions, boundary values, state combinations that only happen in production.

Keep a change log of AI-assisted sessions. When I've used AI to understand a complex piece of logic, I note it in my commit message or PR. It helps me remember which parts of my mental model came from AI inference (and might need verification) versus parts I traced directly through the code.

Key Takeaways

Debugging legacy systems with AI assistance isn't about letting the AI rewrite your codebase. It's about using it as an intelligent navigator that can hold a lot of context simultaneously — which is exactly what's hard about legacy work.

My workflow now follows a consistent pattern: map first, hypothesize, validate with tests, apply a minimal fix, and document the reasoning. Claude Code accelerated every step of this on the alarm monitoring bug, turning what might have been a day-long investigation into a focused, confident fix.

The discipline is in knowing what to ask for and what to refuse. Constrain the AI to your actual problem, verify everything it tells you, and let the tests be the source of truth. Legacy codebases reward caution — and AI tools, used carefully, make that caution faster rather than slower.

Depurando Gargalos Legados com IA: Um Workflow Sistemático para Codebases Complexas

Alair Joao Tavares — Fri, 21 Aug 2026 13:08:47 +0000

Depurando Gargalos Legados com IA: Um Workflow Sistemático para Codebases Complexas

Todo desenvolvedor que já colocou a mão em um sistema legado sabe como é aquela sensação: você abre o repositório, olha para uma função de 400 linhas sem testes, e percebe que qualquer mudança pode derrubar algo em produção que ninguém sequer sabe que existe. Foi exatamente esse contexto que enfrentei recentemente ao trabalhar na estabilização de uma plataforma administrativa consolidada — um sistema de monitoramento financeiro com lógica de negócios crítica, anos de acúmulo técnico e zero margem para erro.

O que mudou minha abordagem dessa vez foi integrar o Claude Code ao meu workflow de debugging. Não como uma bala de prata, mas como um parceiro de raciocínio sistemático. Neste artigo, vou compartilhar o processo que desenvolvi para navegar, refatorar e depurar restrições legadas com segurança — usando TypeScript como linguagem principal e IA como copiloto.

O Problema: Alarmes Fantasmas em um Sistema de Monitoramento

O sistema em questão era uma plataforma administrativa com um módulo de cash-polling — basicamente um mecanismo que monitora operações financeiras em intervalos regulares e dispara alarmes quando detecta anomalias. O bug era sutil e antigo: erros transientes estavam sendo persistidos incorretamente, de modo que uma operação que falhava momentaneamente e depois se recuperava com sucesso ainda aparecia como "em alarme" no dashboard.

O problema parecia simples na superfície, mas a lógica de estado do alarme estava espalhada por vários módulos interdependentes. Mudar qualquer coisa sem entender o fluxo completo era como desarmar uma bomba sem o manual.

Minha primeira tentativa foi a abordagem clássica: ler o código linearmente, traçar o fluxo à mão, tentar reproduzir o bug localmente. Depois de algumas horas, eu tinha um mapa mental fragmentado e muita incerteza. Foi aí que mudei de estratégia.

Usando IA para Mapear Território Desconhecido

A primeira coisa que aprendi ao usar o Claude Code em codebases legadas é que a ferramenta é mais útil quando você a trata como um interlocutor para raciocínio estruturado, não como um gerador de código automático.

Meu workflow ficou assim:

1. Contexto antes de código

Antes de pedir qualquer sugestão de fix, eu alimentava o modelo com contexto rico: o comportamento esperado do sistema, o comportamento observado, e os trechos de código relevantes. Algo como:

"Este módulo de polling verifica o status de operações financeiras a cada N segundos. Quando uma operação falha, um alarme é ativado. Quando a operação seguinte tem sucesso, o alarme deveria ser desativado. O bug é que o alarme persiste mesmo após o sucesso. Aqui está a função de atualização de estado..."

Essa abordagem me economizou tempo porque as sugestões vinham calibradas para o comportamento real do sistema, não para um caso genérico.

2. Hipóteses antes de soluções

Em vez de pedir "como corrigir isso?", eu perguntava: "Quais são as possíveis causas para esse comportamento, dado este código?" Isso gerava uma lista de hipóteses que eu podia validar sistematicamente — muito mais confiável do que seguir o primeiro instinto.

O modelo identificou algo que eu tinha passado por cima: a função de reset do alarme só era chamada quando a operação completava sem nenhum erro anterior na sessão, ignorando o caso em que erros transientes já tinham sido registrados. Era uma condição de guarda mal posicionada.

3. Validação incremental com TypeScript

Quando chegou a hora de implementar, optei por refatorar a lógica de estado do alarme em uma função pura e testável. Aqui está uma versão simplificada e sanitizada do padrão que usei:

// Antes: lógica de alarme acoplada ao handler de polling
async function pollOperation(operationId: string): Promise<void> {
  try {
    const result = await fetchOperationStatus(operationId);
    if (result.status === 'ERROR') {
      await triggerAlarm(operationId);
    }
    // BUG: sem lógica de reset quando status é 'OK' após erro anterior
  } catch (err) {
    await triggerAlarm(operationId);
    logger.error('Polling failed', { operationId, err });
  }
}

// Depois: lógica de estado extraída e explícita
type AlarmState = 'ACTIVE' | 'RESOLVED' | 'IDLE';

interface OperationAlarmContext {
  operationId: string;
  currentAlarmState: AlarmState;
  lastSuccessAt: Date | null;
}

function resolveAlarmTransition(
  context: OperationAlarmContext,
  operationStatus: 'OK' | 'ERROR' | 'TRANSIENT_ERROR'
): AlarmState {
  const { currentAlarmState } = context;

  if (operationStatus === 'OK') {
    // Sucesso sempre resolve o alarme, independente do histórico
    return currentAlarmState === 'ACTIVE' ? 'RESOLVED' : 'IDLE';
  }

  if (operationStatus === 'TRANSIENT_ERROR') {
    // Erros transientes ativam alarme, mas não bloqueiam resolução futura
    return 'ACTIVE';
  }

  // Erro persistente mantém ou ativa alarme
  return 'ACTIVE';
}

async function pollOperation(
  context: OperationAlarmContext
): Promise<OperationAlarmContext> {
  let operationStatus: 'OK' | 'ERROR' | 'TRANSIENT_ERROR';

  try {
    const result = await fetchOperationStatus(context.operationId);
    operationStatus = result.status === 'ERROR' ? 'ERROR' : 'OK';
  } catch (err) {
    // Falha na rede ou timeout = erro transiente
    operationStatus = 'TRANSIENT_ERROR';
    logger.warn('Transient polling failure', { operationId: context.operationId, err });
  }

  const nextAlarmState = resolveAlarmTransition(context, operationStatus);

  if (nextAlarmState === 'RESOLVED') {
    await resolveAlarm(context.operationId);
  } else if (nextAlarmState === 'ACTIVE' && context.currentAlarmState !== 'ACTIVE') {
    await triggerAlarm(context.operationId);
  }

  return {
    ...context,
    currentAlarmState: nextAlarmState,
    lastSuccessAt: operationStatus === 'OK' ? new Date() : context.lastSuccessAt,
  };
}

A diferença crítica: a nova versão trata a transição de estado de forma explícita. Um sucesso após qualquer tipo de erro — transiente ou não — agora corretamente move o alarme para RESOLVED. Isso eliminou o bug.

O benefício adicional de extrair resolveAlarmTransition como função pura foi imediato: eu consegui testar todas as transições de estado sem precisar mockar chamadas de rede.

// Testes das transições de estado — sem mocks complexos
describe('resolveAlarmTransition', () => {
  const baseContext: OperationAlarmContext = {
    operationId: 'op-001',
    currentAlarmState: 'IDLE',
    lastSuccessAt: null,
  };

  it('deve resolver alarme ativo quando operação tem sucesso', () => {
    const context = { ...baseContext, currentAlarmState: 'ACTIVE' as AlarmState };
    const result = resolveAlarmTransition(context, 'OK');
    expect(result).toBe('RESOLVED');
  });

  it('deve manter IDLE quando operação tem sucesso sem alarme ativo', () => {
    const result = resolveAlarmTransition(baseContext, 'OK');
    expect(result).toBe('IDLE');
  });

  it('deve ativar alarme em erro transiente', () => {
    const result = resolveAlarmTransition(baseContext, 'TRANSIENT_ERROR');
    expect(result).toBe('ACTIVE');
  });

  it('deve resolver alarme mesmo após histórico de erros transientes', () => {
    const context = { ...baseContext, currentAlarmState: 'ACTIVE' as AlarmState };
    const result = resolveAlarmTransition(context, 'OK');
    expect(result).toBe('RESOLVED');
  });
});

Navegando Dependências Conflitantes: O Outro Front

Enquanto resolvía o bug de alarme, outro desafio consumia energia em paralelo: uma atualização de SDK que quebrou o processo de build por conta de conflitos entre pacotes. Esse tipo de problema — dependências que se contradizem, versões incompatíveis que somem em builds específicos — é onde a IA também se mostrou valiosa, mas de uma forma diferente.

Aqui o padrão que funcionou foi diagnóstico assistido por busca exaustiva. Em vez de tentar resolver o conflito intuitivamente, eu usava o modelo para gerar uma árvore de hipóteses sobre quais combinações de versões poderiam ser compatíveis, e então validava sistematicamente.

Por exemplo, ao lidar com versões conflitantes de uma biblioteca de área segura entre plataformas diferentes, o raciocínio ficou assim:

# Inspecionar o grafo de dependências para identificar versões requeridas
npx npm-why react-native-safe-area-context

# Ver todas as versões instaladas na árvore
npm list react-native-safe-area-context --all

# Forçar resolução para uma versão específica compatível com ambas as plataformas
# (em package.json, usando resolutions)

{
  "resolutions": {
    "react-native-safe-area-context": "4.x.x"
  },
  "overrides": {
    "react-native-safe-area-context": "4.x.x"
  }
}

O que aprendi nesse processo: a IA é excelente para raciocinar sobre grafos de dependência quando você fornece o output dos comandos de diagnóstico como contexto. Colar o resultado de npm list e perguntar "onde está o conflito?" gera análises muito mais rápidas do que ler a árvore manualmente.

Boas Práticas que Consolidei

Depois desse dia intenso, algumas práticas cristalizaram como parte permanente do meu workflow para codebases legadas com IA:

1. Sempre extraia lógica de negócio crítica em funções puras antes de refatorar. Funções puras são testáveis isoladamente, e isso é seu maior aliado quando o contexto de integração é opaco. Se eu não consigo escrever um teste unitário simples para a lógica, é sinal de que ela está acoplada demais.

2. Use IA para gerar hipóteses, não soluções diretas. Em sistemas legados, o problema raramente é o que parece na superfície. Pedir ao modelo para listar possíveis causas antes de sugerir fixes aumenta a qualidade do diagnóstico.

3. Documente o raciocínio junto com o código. Em refatorações de lógica crítica, adicionei comentários explicando por que cada transição de estado existe — não apenas o que ela faz. Isso foi especialmente importante porque eu sabia que outra pessoa (ou eu mesmo, em seis meses) precisaria entender as decisões sem ter o histórico do bug.

4. Valide em fatias pequenas. Cada mudança em código legado foi acompanhada de um teste antes de avançar. O custo de escrever o teste é sempre menor do que o custo de depurar uma regressão em produção.

5. Trate erros transientes explicitamente. Esse foi o aprendizado central do bug de alarme. Sistemas de polling e monitoramento precisam distinguir entre falhas permanentes e falhas que se recuperam. Ignorar essa distinção cria estados inconsistentes que são difíceis de reproduzir e ainda mais difíceis de depurar.

Conclusão

Trabalhar em código legado com IA não é sobre deixar a ferramenta escrever o código por você — é sobre ter um interlocutor que não se cansa de raciocinar junto. O que mudou na minha abordagem foi a sistematização: contexto rico antes de qualquer pergunta, hipóteses antes de soluções, validação incremental em cada passo.

O bug de alarme que resolvei existia há bastante tempo porque a lógica de transição de estado estava implícita e distribuída. Torná-la explícita — como uma função pura com casos claramente nomeados — foi tanto a solução quanto a prevenção para bugs similares no futuro.

Se você está encarando um sistema legado parecido, meu conselho principal é: resista à tentação de corrigir o sintoma sem entender o estado. Desenhe as transições, nomeie os casos, escreva os testes. A IA pode acelerar essa exploração, mas o raciocínio sistemático ainda é seu.

Decoupling External Services: Implementing the Provider Pattern for E-Signature Integration in Django

Alair Joao Tavares — Wed, 29 Jul 2026 21:56:36 +0000

The Problem With Hardcoding Third-Party Integrations

Not long ago, I finished integrating a second e-signature provider into one of my Django projects. The first provider had been baked in for months — function calls scattered across service modules, API response parsing tangled up with business logic, and environment variables with the provider's name literally in the key. It worked, but it was the kind of code that makes you nervous every time requirements change.

When the requirement came to add DocuSign alongside the existing provider, I had two options: fork the logic everywhere and double down on the mess, or stop and design a proper abstraction. I chose the latter, and what I landed on was the Provider Pattern — a clean interface that lets me plug in any e-signature backend without touching the orchestration layer at all.

In this article, I'll walk through how I structured the abstraction, how I made Django's settings system do the heavy lifting for provider selection, and what I learned along the way about keeping third-party integrations from colonizing your codebase.

Designing the Abstract Interface First

The core idea behind the provider pattern is simple: define a contract that all providers must fulfill, then write your business logic against that contract — never against a specific implementation.

I started by asking myself: what does an e-signature provider actually do from my application's perspective? Stripping away DocuSign-specific concepts, I landed on three operations:

Create an envelope (a signable document package)
Get the signing URL for a recipient
Check the status of an envelope

Everything else — authentication flows, webhook payloads, API versioning — is the provider's problem, not my application's.

Here's the abstract base class I wrote:

# esignature/providers/base.py

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Optional


@dataclass
class SigningRecipient:
    name: str
    email: str
    recipient_id: str = "1"


@dataclass
class EnvelopeResult:
    envelope_id: str
    status: str
    provider: str


@dataclass
class SigningUrlResult:
    url: str
    expires_at: Optional[str] = None


class BaseESignatureProvider(ABC):
    """
    Abstract interface for e-signature providers.
    All concrete providers must implement these methods.
    """

    @abstractmethod
    def create_envelope(
        self,
        document_name: str,
        document_bytes: bytes,
        recipients: list[SigningRecipient],
        subject: str = "Please sign this document",
    ) -> EnvelopeResult:
        """
        Upload a document and create a signing envelope.
        Returns an EnvelopeResult with the provider's envelope identifier.
        """
        ...

    @abstractmethod
    def get_signing_url(
        self,
        envelope_id: str,
        recipient: SigningRecipient,
        return_url: str,
    ) -> SigningUrlResult:
        """
        Generate an embedded signing URL for a specific recipient.
        """
        ...

    @abstractmethod
    def get_envelope_status(self, envelope_id: str) -> str:
        """
        Returns a normalized status string: 'sent', 'completed', 'voided', 'declined'.
        """
        ...

Notice that I'm using plain dataclasses for the return types rather than provider-specific response objects. This is deliberate. My application code should never see a DocuSign EnvelopeSummary or any other SDK-native type — that's implementation detail that stops at the provider boundary.

The normalized status strings are equally important. DocuSign has its own status vocabulary, and if I ever add another provider, theirs will differ too. Normalizing at the interface level means my business logic has exactly one vocabulary to deal with.

Implementing the DocuSign Provider

With the interface defined, I implemented the DocuSign-specific class. This is the only place in the codebase where DocuSign's SDK, authentication quirks, and API conventions actually matter.

# esignature/providers/docusign.py

import base64
from docusign_esign import (
    ApiClient,
    EnvelopesApi,
    EnvelopeDefinition,
    Document,
    Signer,
    SignHere,
    Tabs,
    Recipients,
)
from docusign_esign.client.auth import OAuthToken
from django.conf import settings

from .base import (
    BaseESignatureProvider,
    EnvelopeResult,
    SigningRecipient,
    SigningUrlResult,
)


STATUS_MAP = {
    "sent": "sent",
    "delivered": "sent",
    "completed": "completed",
    "voided": "voided",
    "declined": "declined",
    "created": "draft",
}


class DocuSignProvider(BaseESignatureProvider):
    def __init__(self):
        self._client = self._build_client()

    def _build_client(self) -> ApiClient:
        client = ApiClient()
        client.host = settings.ESIGNATURE_DOCUSIGN_BASE_URL
        client.set_default_header(
            "Authorization",
            f"Bearer {self._get_access_token()}",
        )
        return client

    def _get_access_token(self) -> str:
        # In production I use JWT grant auth; simplified here for clarity
        api_client = ApiClient()
        api_client.host = settings.ESIGNATURE_DOCUSIGN_AUTH_URL
        token: OAuthToken = api_client.request_jwt_user_token(
            client_id=settings.ESIGNATURE_DOCUSIGN_CLIENT_ID,
            user_id=settings.ESIGNATURE_DOCUSIGN_USER_ID,
            oauth_host_name=settings.ESIGNATURE_DOCUSIGN_AUTH_HOST,
            private_key_bytes=settings.ESIGNATURE_DOCUSIGN_PRIVATE_KEY.encode(),
            expires_in=3600,
        )
        return token.access_token

    def create_envelope(
        self,
        document_name: str,
        document_bytes: bytes,
        recipients: list[SigningRecipient],
        subject: str = "Please sign this document",
    ) -> EnvelopeResult:
        document = Document(
            document_base64=base64.b64encode(document_bytes).decode("utf-8"),
            name=document_name,
            file_extension="pdf",
            document_id="1",
        )

        signers = [
            Signer(
                email=r.email,
                name=r.name,
                recipient_id=r.recipient_id,
                routing_order="1",
                tabs=Tabs(
                    sign_here_tabs=[
                        SignHere(
                            anchor_string="/sig/",
                            anchor_units="pixels",
                            anchor_x_offset="0",
                            anchor_y_offset="0",
                        )
                    ]
                ),
            )
            for r in recipients
        ]

        envelope_definition = EnvelopeDefinition(
            email_subject=subject,
            documents=[document],
            recipients=Recipients(signers=signers),
            status="sent",
        )

        api = EnvelopesApi(self._client)
        result = api.create_envelope(
            account_id=settings.ESIGNATURE_DOCUSIGN_ACCOUNT_ID,
            envelope_definition=envelope_definition,
        )

        return EnvelopeResult(
            envelope_id=result.envelope_id,
            status=STATUS_MAP.get(result.status, result.status),
            provider="docusign",
        )

    def get_signing_url(
        self,
        envelope_id: str,
        recipient: SigningRecipient,
        return_url: str,
    ) -> SigningUrlResult:
        from docusign_esign import RecipientViewRequest

        view_request = RecipientViewRequest(
            authentication_method="none",
            client_user_id=recipient.recipient_id,
            recipient_id=recipient.recipient_id,
            return_url=return_url,
            user_name=recipient.name,
            email=recipient.email,
        )

        api = EnvelopesApi(self._client)
        result = api.create_recipient_view(
            account_id=settings.ESIGNATURE_DOCUSIGN_ACCOUNT_ID,
            envelope_id=envelope_id,
            recipient_view_request=view_request,
        )

        return SigningUrlResult(url=result.url)

    def get_envelope_status(self, envelope_id: str) -> str:
        api = EnvelopesApi(self._client)
        result = api.get_envelope(
            account_id=settings.ESIGNATURE_DOCUSIGN_ACCOUNT_ID,
            envelope_id=envelope_id,
        )
        return STATUS_MAP.get(result.status, result.status)

A few things I want to highlight here:

The STATUS_MAP dictionary is the seam between DocuSign's world and my application's world. When I add another provider, it will have its own map — but the values on the right side of that map stay the same.
The __init__ calls _build_client(), which handles authentication. I deliberately kept authentication inside the provider class. It's tempting to pass an already-authenticated client in from outside, but that just moves provider-specific concerns up the stack.
I store provider credentials under clearly namespaced settings keys (ESIGNATURE_DOCUSIGN_*). When I add a second provider, it gets its own namespace (ESIGNATURE_ANOTHERPROVIDER_*), and there's no ambiguity.

Wiring It Together: The Provider Registry

With the abstract base and at least one concrete implementation in place, I needed a way to select the right provider at runtime without littering if/elif chains across the codebase. I built a small registry module for this:

# esignature/registry.py

from django.conf import settings
from django.utils.module_loading import import_string

from .providers.base import BaseESignatureProvider

_BUILT_IN_PROVIDERS = {
    "docusign": "esignature.providers.docusign.DocuSignProvider",
    "mock": "esignature.providers.mock.MockESignatureProvider",
}


def get_esignature_provider() -> BaseESignatureProvider:
    """
    Returns an instantiated e-signature provider based on Django settings.

    Set ESIGNATURE_PROVIDER in settings to a provider key ('docusign', 'mock')
    or a full dotted path to a custom class.
    """
    provider_setting = getattr(settings, "ESIGNATURE_PROVIDER", "mock")

    dotted_path = _BUILT_IN_PROVIDERS.get(provider_setting, provider_setting)

    provider_class = import_string(dotted_path)

    if not issubclass(provider_class, BaseESignatureProvider):
        raise TypeError(
            f"{dotted_path} must be a subclass of BaseESignatureProvider"
        )

    return provider_class()

And in settings.py (or environment-specific overrides):

# settings/production.py
ESIGNATURE_PROVIDER = "docusign"

ESIGNATURE_DOCUSIGN_BASE_URL = env("ESIGNATURE_DOCUSIGN_BASE_URL")
ESIGNATURE_DOCUSIGN_AUTH_URL = env("ESIGNATURE_DOCUSIGN_AUTH_URL")
ESIGNATURE_DOCUSIGN_AUTH_HOST = env("ESIGNATURE_DOCUSIGN_AUTH_HOST")
ESIGNATURE_DOCUSIGN_CLIENT_ID = env("ESIGNATURE_DOCUSIGN_CLIENT_ID")
ESIGNATURE_DOCUSIGN_USER_ID = env("ESIGNATURE_DOCUSIGN_USER_ID")
ESIGNATURE_DOCUSIGN_ACCOUNT_ID = env("ESIGNATURE_DOCUSIGN_ACCOUNT_ID")
ESIGNATURE_DOCUSIGN_PRIVATE_KEY = env("ESIGNATURE_DOCUSIGN_PRIVATE_KEY")

# settings/testing.py
ESIGNATURE_PROVIDER = "mock"

The import_string utility from Django is doing quiet but important work here — it lets me support fully-qualified class paths as provider values, so a team using a custom or third-party provider class doesn't need to fork this registry file.

Switching providers in a container environment is now a single environment variable change. That was a concrete requirement during the DocuSign integration, where I needed the orchestration to pick up the new provider variables without any code deployment.

The Mock Provider: Making Tests Sane

One of the immediate benefits I felt was in testing. Before the abstraction, unit tests for document-related workflows would either hit DocuSign's sandbox API (slow, flaky, rate-limited) or require elaborate monkeypatching. Now, I have a MockESignatureProvider that's a first-class citizen:

# esignature/providers/mock.py

import uuid
from .base import BaseESignatureProvider, EnvelopeResult, SigningRecipient, SigningUrlResult


class MockESignatureProvider(BaseESignatureProvider):
    """
    In-memory provider for use in tests and local development.
    Stores envelope state in a class-level dict so assertions are easy.
    """

    _envelopes: dict[str, dict] = {}

    def create_envelope(
        self,
        document_name: str,
        document_bytes: bytes,
        recipients: list[SigningRecipient],
        subject: str = "Please sign this document",
    ) -> EnvelopeResult:
        envelope_id = str(uuid.uuid4())
        self._envelopes[envelope_id] = {
            "document_name": document_name,
            "recipients": recipients,
            "subject": subject,
            "status": "sent",
        }
        return EnvelopeResult(
            envelope_id=envelope_id,
            status="sent",
            provider="mock",
        )

    def get_signing_url(
        self,
        envelope_id: str,
        recipient: SigningRecipient,
        return_url: str,
    ) -> SigningUrlResult:
        return SigningUrlResult(
            url=f"https://mock-signing.example.com/sign/{envelope_id}/{recipient.recipient_id}"
        )

    def get_envelope_status(self, envelope_id: str) -> str:
        envelope = self._envelopes.get(envelope_id)
        if not envelope:
            raise ValueError(f"Envelope {envelope_id} not found in mock store")
        return envelope["status"]

    # Test helper — not part of the interface
    def simulate_completion(self, envelope_id: str) -> None:
        if envelope_id in self._envelopes:
            self._envelopes[envelope_id]["status"] = "completed"

A Django test using this looks straightforward:

# tests/test_document_service.py

from django.test import TestCase, override_settings
from esignature.registry import get_esignature_provider
from esignature.providers.base import SigningRecipient


@override_settings(ESIGNATURE_PROVIDER="mock")
class DocumentSigningServiceTest(TestCase):
    def test_envelope_created_and_status_tracked(self):
        provider = get_esignature_provider()

        recipient = SigningRecipient(
            name="Jane Smith",
            email="jane@example.com",
        )

        result = provider.create_envelope(
            document_name="Contract.pdf",
            document_bytes=b"%PDF-1.4 fake pdf content",
            recipients=[recipient],
        )

        self.assertEqual(result.status, "sent")
        self.assertEqual(result.provider, "mock")

        status = provider.get_envelope_status(result.envelope_id)
        self.assertEqual(status, "sent")

        # Simulate a webhook callback completing the envelope
        provider.simulate_completion(result.envelope_id)

        status = provider.get_envelope_status(result.envelope_id)
        self.assertEqual(status, "completed")

No mocking library magic, no patch() gymnastics. The test reads exactly like the business logic it's covering.

Practical Tips From the Trenches

Don't leak SDK types through your interface. The moment a return type from your abstract method references docusign_esign.SomeModel, you've coupled everything that imports from the interface to the DocuSign SDK. Use your own dataclasses or TypedDicts.

Normalize error handling too. I didn't show this above for brevity, but I also defined a small ESignatureError exception hierarchy in base.py. Each provider catches its own SDK exceptions and re-raises as ESignatureError subclasses. That way my service layer only ever handles one exception family.

Be careful with provider instantiation cost. DocuSign's JWT authentication involves an HTTP round-trip. If get_esignature_provider() is called per-request, you're paying that cost constantly. In my setup, I wrapped the result in a Django-scoped cache or used lazy instantiation at the module level, depending on the view's threading model.

Container orchestration becomes easier. When I rolled out DocuSign, the only change to my docker-compose and deployment manifests was adding the new ESIGNATURE_DOCUSIGN_* environment variables and changing ESIGNATURE_PROVIDER. The application code that orchestrates document workflows didn't get a single commit.

Write the second provider before you think you need it. The mock provider isn't just for tests — building it forced me to verify that my interface was actually generic enough. If I'd written the interface and only implemented DocuSign, I might have left implicit assumptions baked in that would have broken the moment a real second provider arrived.

Conclusion

The provider pattern isn't a new idea, but applying it deliberately to third-party service integrations in Django pays dividends fast. Here's what I came away with:

Define the interface first, derived from what your application actually needs — not from what the third-party API offers.
Normalize at the boundary: statuses, error types, and return shapes should all be your vocabulary, translated from the provider's by the time they leave the implementation class.
Use Django's settings and import_string to make provider selection a deployment-time decision, not a code change.
The mock provider is a first-class deliverable, not an afterthought. It makes your tests fast, isolated, and honest about what the interface contract actually is.

When the next e-signature provider comes up in a requirements meeting, I won't dread the integration work — I'll just implement the three abstract methods, add a settings key, and everything else keeps working.

Desacoplando Serviços Externos: Implementando o Provider Pattern para Integração de Assinatura Eletrônica

Alair Joao Tavares — Wed, 29 Jul 2026 21:54:50 +0000

O Problema que me Fez Repensar Tudo

Eu estava no meio de uma tarefa que parecia simples: adicionar o DocuSign como um segundo provedor de assinatura eletrônica em um sistema que já usava outro serviço. A lógica de negócio para envio de documentos, controle de status e callbacks já existia — e estava completamente entrelaçada com o provedor original.

O que deveria ser uma adição cirúrgica virou um exercício de arqueologia de código. Cada ponto de integração estava espalhado por views, tasks Celery e services Django, todos chamando diretamente a API do provedor original. Adicionar um segundo provedor sem refatorar significava duplicar lógica, criar condicionais if provider == 'docusign' por todo o codebase, e tornar qualquer terceiro provedor no futuro ainda mais doloroso.

Foi nesse momento que decidi parar, respirar, e implementar o Provider Pattern de forma adequada. Neste artigo, vou mostrar exatamente como estruturei essa abstração em Django, usando a integração com DocuSign como exemplo concreto.

O que é o Provider Pattern e por que ele resolve esse problema

O Provider Pattern (às vezes chamado de Strategy Pattern no contexto de comportamentos intercambiáveis) é uma forma de encapsular implementações concretas atrás de uma interface comum. A ideia central é simples: o código de orquestração não precisa saber qual provedor está sendo usado — ele só precisa saber o que o provedor é capaz de fazer.

No meu caso, a interface precisava responder a três perguntas:

Como enviar um documento para assinatura?
Como consultar o status de uma assinatura?
Como processar um webhook/callback de atualização?

Qualquer provedor — DocuSign, outro serviço ou até um mock para testes — precisa responder a essas três perguntas da mesma forma, do ponto de vista do código que os consome.

A Estrutura de Diretórios

Antes de escrever qualquer código, organizei os arquivos assim:

esignature/
├── __init__.py
├── providers/
│   ├── __init__.py
│   ├── base.py          # Interface abstrata
│   ├── docusign.py      # Implementação DocuSign
│   └── mock.py          # Implementação para testes
├── registry.py          # Registro de provedores disponíveis
├── service.py           # Orquestrador principal
└── models.py            # Models de domínio (envelope, status, etc.)

Essa separação foi intencional: cada arquivo tem uma responsabilidade única e o service.py nunca importa diretamente nenhum provedor concreto.

Definindo a Interface Abstrata

O primeiro passo foi criar a classe base. Em Python, uso abc.ABC e abc.abstractmethod para garantir que qualquer provedor que esqueça de implementar um método falhe em tempo de instanciação, não em tempo de execução.

# esignature/providers/base.py

from abc import ABC, abstractmethod
from dataclasses import dataclass
from datetime import datetime
from typing import Optional


@dataclass
class SignatureRequest:
    """Representa uma solicitação de assinatura normalizada."""
    document_id: str
    document_name: str
    document_content: bytes  # PDF em bytes
    signer_email: str
    signer_name: str
    subject: str
    message: Optional[str] = None
    redirect_url: Optional[str] = None


@dataclass
class SignatureResult:
    """Resultado retornado após o envio bem-sucedido."""
    external_envelope_id: str   # ID gerado pelo provedor externo
    signing_url: Optional[str]  # URL para assinatura embedded, se aplicável
    status: str                 # 'sent', 'delivered', etc.
    raw_response: dict          # Resposta bruta para auditoria


@dataclass
class SignatureStatus:
    """Status atual de um envelope já enviado."""
    external_envelope_id: str
    status: str                 # 'sent', 'delivered', 'completed', 'declined', 'voided'
    completed_at: Optional[datetime]
    declined_reason: Optional[str]
    raw_response: dict


class BaseESignatureProvider(ABC):
    """Interface que todo provedor de assinatura eletrônica deve implementar."""

    @abstractmethod
    def send_for_signature(self, request: SignatureRequest) -> SignatureResult:
        """
        Envia um documento para assinatura.
        Deve retornar um SignatureResult com o ID externo do envelope.
        """
        raise NotImplementedError

    @abstractmethod
    def get_envelope_status(self, external_envelope_id: str) -> SignatureStatus:
        """
        Consulta o status atual de um envelope pelo ID externo.
        """
        raise NotImplementedError

    @abstractmethod
    def process_webhook_payload(self, payload: dict) -> SignatureStatus:
        """
        Processa o payload recebido de um webhook do provedor
        e retorna um SignatureStatus normalizado.
        """
        raise NotImplementedError

    @property
    @abstractmethod
    def provider_name(self) -> str:
        """Identificador único deste provedor (ex: 'docusign')."""
        raise NotImplementedError

Perceba que os métodos trabalham com dataclasses de domínio próprio (SignatureRequest, SignatureResult, SignatureStatus), não com os tipos nativos de cada SDK. Isso é crucial: o service.py fala a língua do meu domínio, não a língua do DocuSign.

Implementando o Provedor DocuSign

Com a interface definida, implementei o provedor concreto do DocuSign. Aqui é onde a complexidade do SDK externo fica isolada:

# esignature/providers/docusign.py

import base64
from datetime import datetime
from typing import Optional

import docusign_esign as docusign
from django.conf import settings

from .base import (
    BaseESignatureProvider,
    SignatureRequest,
    SignatureResult,
    SignatureStatus,
)


class DocuSignProvider(BaseESignatureProvider):
    """
    Implementação do provedor de assinatura usando a API do DocuSign.
    Toda a complexidade do SDK fica confinada aqui.
    """

    provider_name = 'docusign'

    def __init__(self):
        self._client = None

    def _get_api_client(self) -> docusign.ApiClient:
        """Inicializa e autentica o cliente DocuSign via JWT."""
        if self._client is not None:
            return self._client

        api_client = docusign.ApiClient()
        api_client.set_base_path(settings.DOCUSIGN_BASE_URL)

        # Autenticação JWT — as credenciais vêm de variáveis de ambiente
        api_client.configure_jwt_authorization_flow(
            private_key_bytes=settings.DOCUSIGN_PRIVATE_KEY.encode(),
            oauth_host_name=settings.DOCUSIGN_OAUTH_HOST,
            client_id=settings.DOCUSIGN_CLIENT_ID,
            user_id=settings.DOCUSIGN_IMPERSONATED_USER_ID,
            expires_in=3600,
        )

        self._client = api_client
        return self._client

    def send_for_signature(self, request: SignatureRequest) -> SignatureResult:
        api_client = self._get_api_client()
        envelopes_api = docusign.EnvelopesApi(api_client)

        # Monta o documento no formato esperado pelo DocuSign
        document = docusign.Document(
            document_base64=base64.b64encode(request.document_content).decode('ascii'),
            name=request.document_name,
            file_extension='pdf',
            document_id='1',
        )

        # Configura o signatário
        signer = docusign.Signer(
            email=request.signer_email,
            name=request.signer_name,
            recipient_id='1',
            routing_order='1',
        )

        # Adiciona uma aba de assinatura no final do documento
        sign_here = docusign.SignHere(
            anchor_string='/sig1/',
            anchor_units='pixels',
            anchor_y_offset='10',
            anchor_x_offset='20',
        )
        signer.tabs = docusign.Tabs(sign_here_tabs=[sign_here])

        envelope_definition = docusign.EnvelopeDefinition(
            email_subject=request.subject,
            email_blurb=request.message or '',
            documents=[document],
            recipients=docusign.Recipients(signers=[signer]),
            status='sent',
        )

        result = envelopes_api.create_envelope(
            account_id=settings.DOCUSIGN_ACCOUNT_ID,
            envelope_definition=envelope_definition,
        )

        return SignatureResult(
            external_envelope_id=result.envelope_id,
            signing_url=None,  # Para fluxo embedded, geraria a URL aqui
            status=result.status,
            raw_response=result.to_dict(),
        )

    def get_envelope_status(self, external_envelope_id: str) -> SignatureStatus:
        api_client = self._get_api_client()
        envelopes_api = docusign.EnvelopesApi(api_client)

        envelope = envelopes_api.get_envelope(
            account_id=settings.DOCUSIGN_ACCOUNT_ID,
            envelope_id=external_envelope_id,
        )

        completed_at = None
        if envelope.completed_date_time:
            completed_at = datetime.fromisoformat(
                envelope.completed_date_time.replace('Z', '+00:00')
            )

        return SignatureStatus(
            external_envelope_id=external_envelope_id,
            status=envelope.status,
            completed_at=completed_at,
            declined_reason=None,  # Buscaria dos recipients em caso de 'declined'
            raw_response=envelope.to_dict(),
        )

    def process_webhook_payload(self, payload: dict) -> SignatureStatus:
        """
        O DocuSign envia Connect webhooks com uma estrutura específica.
        Aqui normalizamos para nosso formato interno.
        """
        envelope_id = payload.get('envelopeId') or payload.get('EnvelopeID', '')
        status = (payload.get('status') or payload.get('Status', '')).lower()

        completed_at = None
        if status == 'completed' and payload.get('completedDateTime'):
            completed_at = datetime.fromisoformat(
                payload['completedDateTime'].replace('Z', '+00:00')
            )

        return SignatureStatus(
            external_envelope_id=envelope_id,
            status=status,
            completed_at=completed_at,
            declined_reason=payload.get('declinedReason'),
            raw_response=payload,
        )

Também criei um provedor mock para testes, que segue a mesma interface mas nunca faz chamadas externas:

# esignature/providers/mock.py

import uuid
from datetime import datetime, timezone

from .base import (
    BaseESignatureProvider,
    SignatureRequest,
    SignatureResult,
    SignatureStatus,
)


class MockESignatureProvider(BaseESignatureProvider):
    """Provedor falso para uso em testes e ambientes de desenvolvimento."""

    provider_name = 'mock'

    def send_for_signature(self, request: SignatureRequest) -> SignatureResult:
        fake_id = str(uuid.uuid4())
        return SignatureResult(
            external_envelope_id=fake_id,
            signing_url=f'https://mock.example.com/sign/{fake_id}',
            status='sent',
            raw_response={'mock': True, 'envelope_id': fake_id},
        )

    def get_envelope_status(self, external_envelope_id: str) -> SignatureStatus:
        return SignatureStatus(
            external_envelope_id=external_envelope_id,
            status='completed',
            completed_at=datetime.now(tz=timezone.utc),
            declined_reason=None,
            raw_response={'mock': True},
        )

    def process_webhook_payload(self, payload: dict) -> SignatureStatus:
        return SignatureStatus(
            external_envelope_id=payload.get('envelope_id', 'mock-id'),
            status=payload.get('status', 'completed'),
            completed_at=datetime.now(tz=timezone.utc),
            declined_reason=None,
            raw_response=payload,
        )

O Registro e o Service Layer

Com os provedores definidos, precisei de uma forma de selecionar o correto em runtime. Criei um registro simples controlado por configuração:

# esignature/registry.py

from django.conf import settings
from django.core.exceptions import ImproperlyConfigured

from .providers.base import BaseESignatureProvider
from .providers.docusign import DocuSignProvider
from .providers.mock import MockESignatureProvider

_PROVIDER_MAP = {
    'docusign': DocuSignProvider,
    'mock': MockESignatureProvider,
}


def get_esignature_provider() -> BaseESignatureProvider:
    """
    Retorna uma instância do provedor configurado em settings.

    Configure em settings.py:
        ESIGNATURE_PROVIDER = 'docusign'  # ou 'mock' para testes
    """
    provider_key = getattr(settings, 'ESIGNATURE_PROVIDER', None)

    if not provider_key:
        raise ImproperlyConfigured(
            'A configuração ESIGNATURE_PROVIDER não está definida em settings.'
        )

    provider_class = _PROVIDER_MAP.get(provider_key)

    if not provider_class:
        available = ', '.join(_PROVIDER_MAP.keys())
        raise ImproperlyConfigured(
            f'Provedor "{provider_key}" não encontrado. '
            f'Provedores disponíveis: {available}'
        )

    return provider_class()

E o service layer que o resto da aplicação usa — este é o único ponto de entrada público:

# esignature/service.py

import logging
from typing import Optional

from .models import DocumentEnvelope
from .providers.base import SignatureRequest, SignatureStatus
from .registry import get_esignature_provider

logger = logging.getLogger(__name__)


class ESignatureService:
    """
    Orquestrador principal. Não conhece nenhum provedor concreto.
    Toda a lógica de negócio vive aqui; a lógica de integração vive nos providers.
    """

    def __init__(self):
        self.provider = get_esignature_provider()

    def send_document_for_signature(
        self,
        document_id: str,
        document_name: str,
        document_content: bytes,
        signer_email: str,
        signer_name: str,
    ) -> DocumentEnvelope:
        """
        Envia um documento para assinatura e persiste o resultado.
        """
        request = SignatureRequest(
            document_id=document_id,
            document_name=document_name,
            document_content=document_content,
            signer_email=signer_email,
            signer_name=signer_name,
            subject=f'Documento para assinatura: {document_name}',
        )

        logger.info(
            'Enviando documento para assinatura via provedor %s',
            self.provider.provider_name,
        )

        result = self.provider.send_for_signature(request)

        # Persiste o envelope no banco com o ID externo
        envelope = DocumentEnvelope.objects.create(
            document_id=document_id,
            provider=self.provider.provider_name,
            external_envelope_id=result.external_envelope_id,
            status=result.status,
            signing_url=result.signing_url,
            raw_provider_response=result.raw_response,
        )

        logger.info(
            'Envelope %s criado com sucesso (externo: %s)',
            envelope.pk,
            envelope.external_envelope_id,
        )

        return envelope

    def handle_webhook(self, payload: dict, provider_name: str) -> Optional[DocumentEnvelope]:
        """
        Processa um webhook recebido e atualiza o status do envelope.
        """
        status: SignatureStatus = self.provider.process_webhook_payload(payload)

        try:
            envelope = DocumentEnvelope.objects.get(
                external_envelope_id=status.external_envelope_id,
                provider=provider_name,
            )
        except DocumentEnvelope.DoesNotExist:
            logger.warning(
                'Webhook recebido para envelope desconhecido: %s',
                status.external_envelope_id,
            )
            return None

        envelope.status = status.status
        envelope.completed_at = status.completed_at
        envelope.raw_provider_response = status.raw_response
        envelope.save(update_fields=['status', 'completed_at', 'raw_provider_response'])

        return envelope

Boas Práticas que Aprendi na Prática

Depois de implementar e iterar sobre esse padrão, algumas lições ficaram bem claras:

1. Nunca exponha tipos do SDK externo fora do provider. Se o docusign.Envelope vazar para o service.py, você criou um acoplamento escondido. As dataclasses de domínio (SignatureResult, SignatureStatus) são o contrato, não os tipos do SDK.

2. O campo raw_response é seu melhor amigo para debugging. Sempre persisto a resposta bruta do provedor no banco. Quando um webhook chega com um status inesperado, ter o payload original salvo economiza horas de investigação.

3. Configure o provedor via settings.py, não via código. Trocar ESIGNATURE_PROVIDER = 'mock' em settings_test.py faz todos os testes rodarem sem nenhuma chamada externa. Sem mocks, sem patches — só configuração.

4. Use variáveis de ambiente para credenciais do provedor, nunca hardcode. Cada provedor tem suas próprias credenciais. Eu as injeto via variáveis de ambiente e as leio em settings.py:

# settings.py
import os

ESIGNATURE_PROVIDER = os.environ.get('ESIGNATURE_PROVIDER', 'mock')

# Credenciais DocuSign
DOCUSIGN_CLIENT_ID = os.environ.get('DOCUSIGN_CLIENT_ID', '')
DOCUSIGN_ACCOUNT_ID = os.environ.get('DOCUSIGN_ACCOUNT_ID', '')
DOCUSIGN_IMPERSONATED_USER_ID = os.environ.get('DOCUSIGN_IMPERSONATED_USER_ID', '')
DOCUSIGN_PRIVATE_KEY = os.environ.get('DOCUSIGN_PRIVATE_KEY', '')
DOCUSIGN_BASE_URL = os.environ.get('DOCUSIGN_BASE_URL', 'https://demo.docusign.net/restapi')
DOCUSIGN_OAUTH_HOST = os.environ.get('DOCUSIGN_OAUTH_HOST', 'account-d.docusign.com')

5. Teste o contrato, não a implementação. Escreva testes contra a interface BaseESignatureProvider, não contra DocuSignProvider diretamente:

# tests/test_esignature_service.py

from django.test import TestCase, override_settings

from esignature.service import ESignatureService


@override_settings(ESIGNATURE_PROVIDER='mock')
class ESignatureServiceTests(TestCase):

    def setUp(self):
        self.service = ESignatureService()

    def test_send_document_creates_envelope(self):
        envelope = self.service.send_document_for_signature(
            document_id='doc-123',
            document_name='Contrato de Prestação de Serviços',
            document_content=b'%PDF-1.4 fake content',
            signer_email='cliente@example.com',
            signer_name='João da Silva',
        )

        self.assertIsNotNone(envelope.external_envelope_id)
        self.assertEqual(envelope.provider, 'mock')
        self.assertEqual(envelope.status, 'sent')

    def test_webhook_updates_envelope_status(self):
        envelope = self.service.send_document_for_signature(
            document_id='doc-456',
            document_name='Termo de Aceite',
            document_content=b'%PDF-1.4 fake content',
            signer_email='cliente@example.com',
            signer_name='Maria Oliveira',
        )

        webhook_payload = {
            'envelope_id': envelope.external_envelope_id,
            'status': 'completed',
        }

        updated = self.service.handle_webhook(webhook_payload, provider_name='mock')
        self.assertEqual(updated.status, 'completed')

Conclusão

Quando terminei essa refatoração, adicionar o DocuSign foi questão de escrever um único arquivo — docusign.py — sem tocar em nenhuma outra parte do sistema. Se amanhã eu precisar integrar um terceiro provedor, o processo é idêntico: implementar BaseESignatureProvider, registrar no _PROVIDER_MAP, e alterar uma variável de ambiente.

Os principais aprendizados que levo dessa experiência:

O Provider Pattern isola a complexidade dos SDKs externos no lugar certo — dentro do provedor, não espalhada pelo codebase.
Dataclasses de domínio são a cola que permite que provedores completamente diferentes falem a mesma língua para o código de orquestração.
Registro controlado por configuração torna o swap de provedores uma operação de infraestrutura, não de código.
O provedor mock não é apenas para testes — é a documentação viva de como um novo provedor deve se comportar.

Se você está integrando qualquer serviço externo que pode potencialmente ser trocado no futuro — pagamentos, notificações, armazenamento, assinatura eletrônica — esse padrão vai te poupar dores de cabeça consideráveis lá na frente.

26,8 Bilhões de Tokens em 46 Dias: Minha Experiência Extrema Operando o Claude Code

Alair Joao Tavares — Fri, 17 Apr 2026 22:03:56 +0000

Em 46 dias ativos — um período de trabalho ininterrupto, operando praticamente todos os dias —, minha integração com o Claude Code atingiu uma escala que redefiniu minha forma de desenvolver software. Não usei a inteligência artificial apenas para tirar dúvidas pontuais; eu a transformei no meu sistema operacional de desenvolvimento.

Para dar a dimensão exata desse fluxo, consolidei as métricas desse período:

Métrica	Valor
Tokens totais processados	26.834.648.621 (26,83 bilhões)
Sessões registradas	1.272
Mensagens de assistente no transcript	369.470 linhas
Arquivos únicos editados (`Edit`/`Write`)	4.585
Projetos distintos tocados	39
Tempo em sessão (wall-clock)	~5.121 horas
Média diária	~583M tokens · ~27 sessões
Média por sessão	~21M tokens

Para colocar em perspectiva: 26,83 bilhões de tokens equivalem a aproximadamente 20 bilhões de palavras processadas. É o equivalente a ler, reler, editar e discutir cinco Wikipédias inteiras em inglês em pouco mais de seis semanas. E o detalhe mais importante: isso foi feito por um único desenvolvedor, operando 39 projetos em paralelo.

A Alavancagem do Prompt Cache: Trabalhando com Contextos Densos

O número bruto impressiona, mas a composição desses tokens conta uma história muito mais interessante sobre engenharia de software moderna. Analisando as amostras dos transcripts brutos, temos a seguinte divisão:

Produtivo (output + cache creation): ~570 milhões de tokens. Isso é o que o Claude efetivamente cria de novo para mim.
Alavancagem (cache read): ~26,26 bilhões de tokens. Isso é o que é relido do cache a cada turno da conversa.

Ou seja, para cada 1 token novo gerado, aproximadamente 46 tokens de contexto são reaproveitados do cache.

É exatamente essa mecânica que torna as sessões longas — nas quais passo horas mergulhado em uma mesma base de código — economicamente viáveis. Cerca de 90% do contexto de cada nova mensagem é servido a 10% do preço, graças ao prompt cache. Esse rácio é o indicador silencioso de como eu trabalho: foco em sessões densas, com contexto amplo e persistente, e não em dezenas de perguntas isoladas. É o modo "abro o repositório, seguro o contexto e resolvo três features juntas", distanciando-me completamente do uso tradicional de um "chatbot de dúvidas pontuais".

Onde os Tokens Foram Gastos: Meus Top 3 Projetos

#	Projeto	Tokens	Sessões	Linhas
1	StriveX (plataforma mobile/web)	6,15 B	210	54.505
2	Activi.dev (plataforma SaaS)	4,68 B	185	88.789
3	NZR KDP (app infantil)	4,36 B	137	39.649

Meus três projetos-bandeira concentraram ~57% de todos os tokens. Não foi por acaso: são plataformas robustas (um app mobile completo, a plataforma Activi.dev com mais de 30 features ativas e um app infantil com backend complexo). Cada uma dessas bases puxa um contexto extenso a cada interação.

No Activi.dev, especificamente, gerei 88.789 linhas de transcript em 185 sessões. É a maior densidade de trabalho da amostra, o que faz todo o sentido: é o projeto onde cada feature nasce, é especificada, implementada e revisada em um fluxo contínuo, sem intermediação.

Além desses três, mantive 36 outros projetos em rotação simultânea — desde sistemas para o banco privado Mercantil (Nexxera) até o SaaS de saúde Elosaúde, passando por ferramentas internas e experimentos. Como mencionei: eu não uso o Claude Code em um projeto; eu o utilizo como o ambiente onde o projeto acontece.

O Meu Ritmo: Os Dias Mais Pesados

Data	Tokens	Sessões
2026-04-02	2,73 B	56
2026-04-06	2,39 B	32
2026-04-14	2,31 B	29
2026-04-03	1,28 B	18
2026-04-01	1,28 B	65
2026-04-16	1,20 B	32
2026-03-23	1,18 B	28
2026-04-15	1,17 B	52
2026-04-11	1,05 B	4
2026-04-05	852 M	15

Tive dez dias superando a marca de 850 milhões de tokens. Meu pico absoluto foi em 02/04, atingindo 2,73 bilhões em 56 sessões — o que significa iniciar uma sessão nova aproximadamente a cada 25 minutos ao longo de 24 horas. Esse é o meu perfil operacional: não trabalho no formato "das 9h às 18h". Eu trabalho em rajadas de hiperfoco, inserido no contexto do projeto certo, exatamente enquanto o problema está quente na minha mente.

A Escolha do Arsenal: Modelos Utilizados

Modelo	Sessões	Tokens
claude-opus-4-6	378	22,20 B
claude-opus-4-7	13	539 M
claude-sonnet-4-6	11	391 M
claude-haiku-4-5	1	130 M

O Opus 4.6 é o meu cavalo de tração, respondendo por 83% das sessões e 92% dos tokens totais. Comecei a adotar o Opus 4.7 nas últimas semanas do período avaliado. O modelo Sonnet aparece em sessões mais curtas, enquanto o Haiku atua estritamente no papel de subagente leve (para ToolSearch e leituras superficiais rápidas).

Minha estratégia é clara: eu escolho conscientemente o Opus para o trabalho pesado e arquitetural, reservando os modelos menores apenas como auxiliares especializados. Nunca os utilizo como um simples corte reflexo de custos, pois o contexto e a capacidade de raciocínio profundo são inegociáveis.

IA na Prática: As Ferramentas que Invoquei

Para entender o que realmente aconteceu nesses 46 dias, precisamos olhar para as ferramentas que a IA executou sob meu comando:

Bash (28.790 execuções): Testes rodando, migrations aplicadas, rotinas de build/deploy, comandos git e análise de logs. Eu sou o tipo de desenvolvedor que não pergunta à IA "como faço o migrate?". Eu instruo a aplicação, leio o erro retornado, corrijo em tempo real e sigo em frente.
Edit e Write (19.698 operações): Cerca de 19,7 mil modificações diretas em 4.585 arquivos únicos. Isso não é autocomplete de código; é cirurgia de precisão em múltiplos arquivos por turno de conversa.
Read, Grep e Glob (~23.000 operações): Mais de 23 mil operações de leitura dirigida. O princípio básico de mapear minuciosamente a base antes de alterar qualquer linha.
Playwright (3.529 operações): Ações de click, snapshot, navigate, evaluate, screenshot e wait. Eu verifiquei a interface de usuário (UI) de forma visual e automatizada, sem depender do "achismo de que compilou".
TodoWrite (3.192 invocações): Demonstra um fluxo de trabalho estruturado, de planejamento, rastreio e fechamento de tarefas, sem improvisos.
Agent (2.004 chamadas): Delegação real para subagentes (como exploradores de código, revisores de PRs e analistas de documentação). Um fluxo multi-agente operando na prática, muito além de demonstrações teóricas.

Esses números validam a instrução raiz que escrevi no meu arquivo CLAUDE.md: "Para mudanças de UI, inicie o dev server e use a feature no navegador antes de reportar conclusão". Eu exigi esse comportamento, e ele foi executado milhares de vezes.

O Que Significam 46 Dias e 39 Projetos

Os dados convergem para uma conclusão clara: eu não uso a IA como um atalho; eu a transformei em um multiplicador de escopo.

Escopo paralelo extremo: Gerenciar 39 projetos simultâneos — incluindo plataformas SaaS, sistemas financeiros corporativos complexos, ferramentas internas e projetos experimentais — permite que um desenvolvedor solo cubra o terreno que convencionalmente exigiria uma equipe inteira.
Densidade por sessão: A média de 21M de tokens por sessão reflete iterações profundas, onde a mágica da alavancagem de cache de 46x realmente acontece.
Consistência ininterrupta: Zero dias ociosos no período. Isso não foi uma "sprint" forçada; esse se tornou o meu ritmo natural.

O grand total — 26,83 bilhões de tokens, 1.272 sessões, 4.585 arquivos únicos editados e 39 projetos — funciona muito bem como uma manchete impressionante. Mas o que esses números escondem é muito mais valioso: eles são o subproduto de um sistema de trabalho meticulosamente construído.

Sessões densas, projetos diversificados, modelos escolhidos por sua função específica, ferramentas automatizadas agindo como braços mecânicos de alta precisão. Quando você trata ferramentas como o Claude Code não como um "Stack Overflow de luxo", mas como um colega de pareamento incansável, é isso que 26,8 bilhões de tokens conseguem comprar.

Nota sobre a metodologia: Os dados deste artigo foram extraídos da tabela ClaudeCodeSessionActivity do backend do Activi.dev. Essa tabela é populada pelo hook SessionEnd do Claude Code em cada máquina onde o meu token de integração está configurado. A contagem de tokens segue rigorosamente a contabilidade do campo usage da API da Anthropic (input direto + output + cache creation + cache read).

Scaling Myself: Processing 26.8 Billion Tokens in 46 Days with Claude Code

Alair Joao Tavares — Fri, 17 Apr 2026 22:03:51 +0000

For 46 straight days, I submerged myself in code, treating AI not as a glorified chatbot, but as the underlying operating system of my development workflow. Over this non-stop span, I used Claude Code to push my productivity to levels that would conventionally demand an entire engineering team.

Here is exactly what happens when you put Claude Code in the driver's seat, backed by the raw data of my daily workflow.

By the Numbers: 46 Days of Uninterrupted Coding

To understand the scale of this experiment, we have to look at the baseline metrics. Over 46 active days, my Claude Code integration processed an immense volume of data:

Metric	Value
Total tokens	26,834,648,621 (26.83 billion)
Sessions recorded	1,272
Assistant transcript lines	369,470
Unique files edited	4,585 (via `Edit`/`Write`)
Distinct projects	39
Wall-clock session time	~5,121 hours
Daily average	~583M tokens · ~27 sessions
Average per session	~21M tokens

For context: 26.83 billion tokens equates to roughly 20 billion words. That is on the order of reading, re-reading, editing, and discussing five full English Wikipedias in just over six weeks. And this was driven by one developer alone, operating 39 projects in parallel.

Context Caching: The Secret to Massive AI Leverage

The raw number is impressive, but the composition of those tokens tells a much more interesting story. When sampling my raw transcripts, a distinct pattern emerges:

Productive tokens (output + cache creation): ~570M tokens — this is what Claude creates anew for me.
Leverage tokens (cache read): ~26.26B tokens — this is what I re-read from the prompt cache at every conversation turn.

In other words, for every 1 new token I generate, ~46 tokens of context are reused from the cache.

This caching ratio is exactly how my long sessions—spending hours submerged in a single codebase—stay economically viable. By utilizing the prompt cache, 90% of the context for every new message is served at 10% of the base price.

This ratio is also the silent tell of how I actually work: dense sessions with massive, persistent context, not 50 tiny isolated questions. I operate in an "open the repo, hold the context, solve three things together" mode, rather than treating the AI as a one-off chatbot.

Where the Tokens Went: Managing 39 Projects in Parallel

#	Project	Tokens	Sessions	Transcript lines
1	nzrgym.com (mobile/web platform)	6.15 B	210	54,505
2	Activi.dev (this platform)	4.68 B	185	88,789
3	colorim.com.br (kids app)	4.36 B	137	39,649

My three flagship projects concentrate ~57% of all tokens. This is not by accident. These are my largest codebases—a full mobile platform, the Activi.dev platform with 30+ live features, and a children's app with a heavy backend. Each project pulls massive amounts of context into every conversation turn.

On Activi.dev specifically, I logged 88,789 transcript lines across 185 sessions. This represents the highest work density in my sample, which tracks perfectly: it's the project where every feature I build is born, specified, implemented, and reviewed directly, without intermediaries.

Beyond these three, I keep 36 other projects in simultaneous rotation. These range from private financial stacks (Mercantil, Nexxera) to healthcare SaaS (Elosaúde), down to internal tooling and weekend experiments. I don't just use Claude Code on a project—I use it as the foundational layer for all my software development.

Working in Bursts: My Heaviest Development Days

Day	Tokens	Sessions
2026-04-02	2.73 B	56
2026-04-06	2.39 B	32
2026-04-14	2.31 B	29
2026-04-03	1.28 B	18
2026-04-01	1.28 B	65
2026-04-16	1.20 B	32
2026-03-23	1.18 B	28
2026-04-15	1.17 B	52
2026-04-11	1.05 B	4
2026-04-05	852 M	15

Ten of my active days eclipsed 850 million tokens. My absolute peak hit on April 2nd, processing 2.73 billion tokens across 56 sessions—averaging a fresh session roughly every 25 minutes over a 24-hour window.

This reflects my specific developer profile: I don't work a traditional "9 to 5". I work in intense, focused bursts, diving deep into a project's context while the problem is still hot.

Model Selection: Picking the Right Tool for the Job

Model	Sessions	Tokens
claude-opus-4-6	378	22.20 B
claude-opus-4-7	13	539 M
claude-sonnet-4-6	11	391 M
claude-haiku-4-5	1	130 M

Claude Opus 4.6 is my undeniable workhorse, accounting for 83% of tagged sessions and 92% of total tokens. I only recently began folding Opus 4.7 into the mix. Sonnet typically shows up in my shorter, faster sessions, while Haiku plays the role of a lightweight subagent (handling ToolSearch and targeted reads).

My strategy is deliberate: I pick Opus for the heavy architectural lifting, keeping the smaller models strictly as specialized helpers. I don't use smaller models as a reflexive cost-cutting measure; I prioritize capability first.

Execution over Autocomplete: How I Used AI Tools

Tool	Invocations
`Bash`	28,790
`Read`	15,714
`Edit`	15,365
`Grep`	6,356
`Write`	4,333
`Playwright`	3,529
`TodoWrite`	3,192
`Agent`	2,004
`ToolSearch`	1,123
`Glob`	845

Translating these invocations into actual developer behavior:

28.8k Bash executions: I ran tests, applied database migrations, handled deployments, executed git commands, and read logs. I don't ask the AI "how do I migrate?"—I have it run the command, read the error, fix the code, and move on.
15.4k Edits + 4.3k Writes: This resulted in ~19.7k file modifications across 4,585 unique files. This isn't simple autocomplete; this is multi-file surgery in a single conversation turn.
15.7k Reads + 6.4k Greps + 845 Globs: Approximately 23k directed-read operations. My workflow relies on mapping the architecture thoroughly before making a single cut.
2k Agent calls: I heavily delegated to subagents (for codebase exploration, code reviews, and spec documentation). This is a functional multi-agent workflow, not a tech demo.
~3.5k Playwright operations: The AI actively clicked, navigated, evaluated, and took screenshots to visually verify UI changes, ensuring we didn't just stop at "it compiled, so it must be fine."

These numbers perfectly align with the core instruction I placed in my root CLAUDE.md file:

"For UI changes, start the dev server and use the feature in the browser before reporting it done."

I enforced that rule, and the AI followed it thousands of times.

Conclusion: AI as a Scope Multiplier

Looking back at the data, the conclusion is absolute: I do not use AI as a shortcut. I have turned AI into a scope multiplier.

Massive Parallel Scope: I actively maintain 39 projects, covering B2B SaaS platforms, complex fintech systems, internal AI-augmented developer tools, and rapid experimental hacks. I am one human executing the roadmap of a conventional team.
Extreme Context Density: Averaging 21M tokens per session with over 369,000 transcript lines proves my reliance on long, context-heavy iterations, rather than brief pings.
46x Caching Leverage: By staying inside the context window and iterating deeply, I extract maximum value from Claude Code.
Process Discipline: The 3,192 TodoWrite and 2,004 Agent invocations prove I don't "wing it." I plan, delegate, track, and close.
Relentless Consistency: 46 active days out of a 46-day window. Zero idle days. This isn't a temporary sprint; this is my new baseline pace.

The headline metrics—26.83 billion tokens, 1,272 sessions, 4,585 unique files, 39 projects—make for a spectacular tagline. But the reality underneath is far more valuable. It is the byproduct of a rigorously built system. I use dense sessions, strict model delegation, heavily mechanical tool usage, and most importantly, an approach that treats Claude Code as a senior pairing partner rather than a luxury Stack Overflow.

That is what 26.8 billion tokens can buy when you know exactly what you're doing.

Arquitetando CI/CD para Monorepos Mobile: Integrando npm Workspaces, EAS Builds e GitHub Actions

Alair Joao Tavares — Thu, 16 Apr 2026 19:13:45 +0000

Arquitetando CI/CD para Monorepos Mobile: Integrando npm Workspaces, EAS Builds e GitHub Actions

O desenvolvimento de aplicações mobile modernas frequentemente exige o compartilhamento de código entre diferentes plataformas, como web, backend e mobile. É nesse cenário que a arquitetura de monorepo brilha, permitindo que você mantenha todo o seu ecossistema em um único repositório. No entanto, quando introduzimos o React Native na equação, especialmente utilizando o ecossistema do Expo, a configuração de pipelines de CI/CD (Continuous Integration e Continuous Deployment) pode se tornar um desafio considerável.

Neste artigo, vamos explorar como construir um pipeline de CI/CD robusto e eficiente para um monorepo mobile. Combinaremos o poder do npm Workspaces para o gerenciamento de pacotes, o Expo Application Services (EAS) para a automação de builds em nuvem, e o GitHub Actions para orquestrar as rotinas de release, com foco especial no fluxo de iOS.

O Desafio dos Monorepos no Desenvolvimento Mobile

Quando trabalhamos com um repositório simples contendo apenas o app mobile, as ferramentas de build conseguem encontrar facilmente o package.json, o node_modules e os arquivos de configuração. Porém, em um monorepo, a estrutura muda. As dependências muitas vezes são içadas (hoisted) para a raiz do repositório, e o código do aplicativo precisa resolver módulos que vivem em pastas adjacentes (ex: packages/shared-ui).

Se o seu serviço de build (como o EAS) não for instruído corretamente sobre como lidar com essa estrutura, os builds falharão por não encontrarem pacotes internos ou por erros de resolução no Metro Bundler (o empacotador padrão do React Native).

Para resolver isso, utilizaremos o npm Workspaces, que tem suporte nativo para linkagem de pacotes locais.

1. Estruturando o Monorepo com npm Workspaces

A base da nossa arquitetura começa na organização das pastas e no arquivo package.json raiz. Vamos assumir que estamos construindo uma aplicação em TypeScript, o padrão ouro para aplicações React Native escaláveis.

Uma estrutura de monorepo ideal se parece com isso:

meu-monorepo/
├── package.json
├── package-lock.json
├── tsconfig.base.json
├── apps/
│   └── mobile-app/         # Nosso app React Native/Expo
│       ├── package.json
│       ├── eas.json
│       ├── App.tsx
│       └── tsconfig.json
└── packages/
    └── shared-types/       # Pacote TypeScript compartilhado
        ├── package.json
        ├── src/index.ts
        └── tsconfig.json

Na raiz do repositório, o seu package.json deve declarar os workspaces:

{
  "name": "example-monorepo",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ],
  "scripts": {
    "build:shared": "npm run build -w packages/shared-types",
    "start:mobile": "npm run start -w apps/mobile-app"
  }
}

Configurando um Pacote Compartilhado (TypeScript)

Vamos criar um arquivo genérico no nosso pacote shared-types para garantir que a tipagem flua perfeitamente pelo monorepo.

// packages/shared-types/src/index.ts
export interface UserProfile {
  id: string;
  username: string;
  email: string;
  preferences: {
    notificationsEnabled: boolean;
    theme: 'light' | 'dark';
  };
}

export const formatUsername = (user: UserProfile): string => {
  return `@${user.username.toLowerCase()}`;
};

No package.json do seu app mobile (apps/mobile-app/package.json), você adiciona a dependência referenciando a versão local:

{
  "name": "@example/mobile-app",
  "version": "1.0.0",
  "dependencies": {
    "expo": "~51.0.0",
    "react": "18.2.0",
    "react-native": "0.74.1",
    "@example/shared-types": "*"
  }
}

Ao rodar npm install na raiz do repositório, o npm criará symlinks (links simbólicos) automáticos. O app mobile agora consegue importar UserProfile como se fosse um pacote npm público.

2. Configurando o EAS Build para o Monorepo

O Expo Application Services (EAS) é um serviço de nuvem incrivelmente poderoso para compilar apps React Native. No entanto, ele precisa ser configurado especificamente para entender que está rodando dentro de um monorepo.

Primeiro, certifique-se de que o Metro Bundler do React Native entenda os symlinks criados pelo npm workspaces. No seu apps/mobile-app/metro.config.js:

// apps/mobile-app/metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const path = require('path');

const projectRoot = __dirname;
const monorepoRoot = path.resolve(projectRoot, '../..');

const config = getDefaultConfig(projectRoot);

// Adiciona a raiz do monorepo para que pacotes internos sejam resolvidos
config.watchFolders = [monorepoRoot];

// Configura a resolução de nós do Metro
config.resolver.nodeModulesPaths = [
  path.resolve(projectRoot, 'node_modules'),
  path.resolve(monorepoRoot, 'node_modules'),
];

module.exports = config;

Em seguida, vamos ajustar o arquivo eas.json no app mobile. O segredo aqui é garantir que o EAS instale as dependências a partir da raiz do monorepo, e não apenas na pasta do aplicativo.

{
  "cli": {
    "version": ">= 7.0.0",
    "appVersionSource": "remote"
  },
  "build": {
    "base": {
      "env": {
        "EXPO_USE_PATH_ALIASES": "1"
      }
    },
    "production": {
      "extends": "base",
      "node": "18.x",
      "ios": {
        "image": "latest"
      }
    }
  }
}

Por padrão, se você acionar um build na pasta do app, o EAS tentará subir apenas o código do app. É necessário garantir que o comando seja rodado a partir do root, ou configurar o eas ignore adequadamente. Vamos lidar com isso elegantemente no próximo passo usando o GitHub Actions.

3. Automatizando Releases de iOS com GitHub Actions

Aqui é onde a mágica da automação acontece. Em vez de rodar o processo de build do EAS manualmente na sua máquina, correndo o risco de compilar código desatualizado, vamos configurar um workflow no GitHub Actions que será disparado toda vez que fizermos push na branch main ou criarmos uma tag de release.

Crie um arquivo em .github/workflows/ios-release.yml:

name: iOS Production Release

on:
  push:
    branches:
      - main
    paths:
      - 'apps/mobile-app/**'
      - 'packages/**'
      - 'package.json'
      - 'package-lock.json'

jobs:
  build-ios:
    name: Build & Submit iOS App via EAS
    runs-on: ubuntu-latest

    # Usamos o diretório raiz como padrão para os comandos iniciais
    defaults:
      run:
        working-directory: ./

    steps:
      - name: 🏗 Checkout do repositório
        uses: actions/checkout@v4

      - name: ⚙️ Setup do Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
          cache-dependency-path: 'package-lock.json'

      - name: 📦 Instalar Dependências (Monorepo)
        run: npm ci

      - name: 🚀 Setup do Expo e EAS
        uses: expo/expo-github-action@v8
        with:
          eas-version: latest
          token: ${{ secrets.EXPO_TOKEN }}

      - name: 🍎 Build para iOS
        # Mudamos para o diretório do app especificamente para rodar o comando EAS
        working-directory: ./apps/mobile-app
        run: |
          eas build --platform ios \
                    --profile production \
                    --non-interactive \
                    --auto-submit
        env:
          EXPO_APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.EXPO_APPLE_APP_SPECIFIC_PASSWORD }}

Entendendo o Workflow

Condições de Execução (on.push.paths): O workflow só é disparado se houver modificações na pasta do app mobile, nos pacotes compartilhados ou nas dependências principais. Isso economiza valiosos minutos de CI e não aciona builds mobile desnecessários se você alterar apenas o backend.
Setup e Cache (actions/setup-node): Uma etapa essencial. Utilizamos o arquivo package-lock.json para criar um cache eficiente do npm. Em um monorepo, isso corta o tempo de instalação pela metade.
Instalação das dependências (npm ci): É executado na raiz do repositório. Isso garante que todos os workspaces sejam inicializados e os symlinks criados corretamente.
Expo Action (expo/expo-github-action): Esta action oficial injeta as credenciais do EAS no ambiente. Você deve criar um Personal Access Token no portal do Expo e adicioná-lo nas Secrets do repositório (EXPO_TOKEN).
O Comando de Build: Observe que alteramos o diretório de trabalho apenas no momento do build (./apps/mobile-app). A flag --non-interactive é vital para impedir que o terminal trave aguardando input de usuário. A flag --auto-submit envia o app automaticamente para o TestFlight ou App Store após o build bem-sucedido (desde que as credenciais da Apple estejam devidamente preenchidas via secrets do EAS ou variáveis de ambiente).

Boas Práticas e Dicas de Ouro

1. Lidando com Credenciais da Apple

A submissão automática para iOS exige que o EAS tenha acesso à sua conta da Apple Developer. O recomendado é usar a integração oficial do EAS. Em vez de armazenar o password no repositório, você pode criar uma App-Specific Password na Apple e cadastrá-la com a variável EXPO_APPLE_APP_SPECIFIC_PASSWORD para submissões sem falhas de MFA (Multi-Factor Authentication).

2. Versionamento e Gerenciamento de Configuração

No EAS, prefira o padrão "appVersionSource": "remote" no eas.json e gerencie o número da versão dinamicamente através de scripts pré-build ou utilizando o auto-incremento nativo do EAS (eas build:version:set). Isso evita conflitos de merge desagradáveis em arquivos app.json no monorepo.

3. Evite Subir a Pasta node_modules

Em monorepos muito grandes, o upload dos arquivos para a nuvem do EAS pode ser lento. Configure corretamente um arquivo .easignore no diretório do seu app mobile para garantir que ele não copie o node_modules (o EAS irá rodar o npm install novamente em sua própria máquina de build) nem pastas de outros aplicativos irrelevantes para o mobile.

Exemplo de arquivo .easignore no root do monorepo (se for subir do root):

apps/web-app/
apps/backend-api/
**/node_modules/
.git/

Conclusão

Configurar um pipeline de CI/CD em um ambiente monorepo pode parecer desafiador no início. A separação estrita de escopos, gerenciada pelo npm workspaces, interage de forma complexa com os empacotadores nativos como o Metro.

Entretanto, ao configurar as rotas corretamente no Metro Bundler, orquestrar as instalações a partir da raiz com as Actions do GitHub, e entregar o pacote completo para o EAS, você cria uma máquina de automação formidável.

Aplicar essas práticas significa que seu time poderá focar no que realmente importa: desenvolver funcionalidades incríveis e resolver problemas dos usuários, deixando o processo burocrático de build, compilação de chaves e distribuição para a nuvem. Menos horas gastas no Xcode, mais tempo programando em TypeScript.

AI-Augmented Developer: Transformando Agentes de IA em Engenheiros Disciplinados

Alair Joao Tavares — Wed, 15 Apr 2026 19:45:32 +0000

O Problema Oculto do Desenvolvimento com IA

Quem desenvolve com Inteligência Artificial conhece bem o ciclo: você descreve uma nova feature, o agente sai escrevendo código antes mesmo de entender completamente o problema, ignora os testes, inventa contexto e, três horas depois, você está revisando um diff de 800 linhas para descobrir que metade da implementação não faz o que foi pedido.

A culpa não é exclusivamente do modelo de IA. O problema raiz é a ausência de processo. Engenheiros de software sêniores não começam a programar impulsivamente — eles especificam, planejam, testam e revisam. Faltava aos agentes autônomos esse mesmo rigor metodológico.

É exatamente essa lacuna que o framework AI-Augmented Developer resolve.

O que é o AI-Augmented Developer?

O AI-Augmented Developer (aiadev) é um framework de workflow completo focado em agentes de codificação. Ele instala um conjunto de skills componíveis e fornece instruções iniciais (prompts de sistema) que garantem que o agente utilize essas habilidades automaticamente, sem que o desenvolvedor precise se lembrar de acioná-las a cada interação.

A filosofia do framework é pautada em quatro pilares inegociáveis:

Spec-first: Nenhum código é gerado sem uma especificação prévia aprovada.
Test-first: O ciclo RED-GREEN-REFACTOR é tratado como um contrato, não como uma sugestão.
Evidência sobre afirmação: O agente deve verificar a execução do código antes de declarar que o trabalho foi concluído com sucesso.
Simplicidade como meta primária: Os princípios YAGNI (You Aren't Gonna Need It) e DRY (Don't Repeat Yourself) são leis.

O fluxo de trabalho padrão opera como uma esteira contínua de oito etapas lógicas:

specify → clarify → plan → tasks → implement
                                       │
                          test-driven-development (por tarefa)
                          systematic-debugging (em falhas)
                          checklist (segurança, perf, a11y, i18n…)
                                       ↓
                               analyze → requesting-code-review → finishing-a-branch

Cada etapa atua como uma skill que dispara sozinha quando o contexto exige. O agente é instruído a não pular etapas ou inventar contexto, apresentando sempre a especificação (spec) antes de escrever o primeiro teste.

A Constituição: Sete Artigos Fundamentais

O coração do framework reside no arquivo constitution.md. Ele contém sete princípios que toda decisão técnica tomada pela IA precisa respeitar:

Spec-first: Sem especificação aprovada, não há código.
Test-first: Todo teste deve falhar antes de sua respectiva implementação.
Simplicidade: Busca-se sempre a solução mais simples e viável.
Evidência sobre afirmação: O agente deve rodar, provar e mostrar resultados reais.
Provider pattern: Dependências externas devem ficar isoladas atrás de interfaces.
Privacy by design: Dados sensíveis nunca devem vazar para o contexto das LLMs.
Atribuição: Trabalhos derivados devem sempre receber os devidos créditos.

Todo plano arquitetural gerado pela skill plan carrega um Constitution Check. Se um artigo for quebrado, o desvio é registrado em uma tabela de Complexity Tracking junto com sua justificativa. Sem essa disciplina e rastreabilidade, o framework se recusa a avançar.

A Evolução Acelerada do Framework

Entre 14 e 15 de abril de 2026, o projeto evoluiu de forma expressiva da versão 0.3 para a 0.11. Cada release foi focada em resolver fricções reais de quem utiliza a ferramenta no dia a dia.

v0.3 — Instalação Interativa (`aiadev install`)

A CLI em Python substituiu de vez os scripts manuais antigos. Um único comando agora renderiza um preset no projeto (substituindo variáveis e posicionando arquivos), contando com modos --dry-run, --uninstall e detecção de drift (desvios) contra edições manuais.

v0.4 & v0.5 — Suporte Multiplataforma

Em duas atualizações, o framework abraçou as cinco principais ferramentas de IA para desenvolvimento do mercado: Claude Code, Cursor, Codex, OpenCode e Gemini CLI. Cada integração possui um handler isolado e modular (~30 linhas) com 100% de cobertura de testes.

v0.6 — Escopo Global de Usuário

A flag --scope user permite instalar as skills uma única vez por máquina (sob ~/.<plataforma>/skills/). Todo projeto na sua estação herda automaticamente o catálogo global, mantendo apenas arquivos específicos (como CLAUDE.md e constitution.md) em nível local.

v0.7 — Publicação no PyPI

O comando pip install aiadev tornou-se a via oficial de distribuição. O pacote (wheel) já embute recursos essenciais (como templates/, schemas/, skills/ e agents/), eliminando a necessidade de clonar o repositório. O processo de publicação utiliza OIDC trusted publishing para maior segurança.

v0.8 — Sistema Robusto de Extensões

O comando aiadev extension add <git-url> abriu portas para a distribuição de presets de terceiros. Agora, a comunidade e empresas podem criar catálogos públicos ou privados. Para evitar conflitos, funcionalidades embutidas (built-ins) têm prioridade em caso de colisão de nomes.

v0.9 — Instalação Completa e Sincronização

Um marco do projeto. O comando de instalação passou a equipar o projeto com toda a esteira de uma vez, incluindo dezenas de slash commands, agentes, regras e skills. Além disso, o novo aiadev sync permite atualizar projetos existentes de forma inteligente, usando introspecção de dependências (package.json, pyproject.toml, Makefile, etc.) para gerar as configurações automaticamente.

v0.10 — Namespaces e Especificações Sequenciais

Os comandos foram organizados via namespaces (ex: /aiadev:specify). As especificações deixaram os diretórios com nomes arbitrários e adotaram identificadores sequenciais (specs/0001-<slug>/). E o principal para usuários lusófonos: aiadev init --language pt-BR garante que todo o pipeline da IA interaja em português do Brasil.

v0.11 — Integração MCP Universal

O Model Context Protocol (MCP) tornou-se um cidadão de primeira classe. Basta declarar seus servidores MCP uma vez em mcps.yaml e o aiadev install cuida da tradução para o formato nativo exigido por cada plataforma (Claude, Cursor, Gemini, etc.).

Por Que Isso Importa Para o Seu Time?

A rápida evolução do framework é prova do próprio método: o aiadev se aplica a si mesmo. As especificações do projeto vivem em specs/, os planos são gerados pela skill plan e os commits seguem a padronização imposta pela skill tasks.

Para desenvolvedores que utilizam IA, o framework ataca quatro dores crônicas simultaneamente:

Problema Comum	A Solução do Framework (`aiadev`)
Agente codifica sem entender a feature	A skill `specify` obriga a validação da especificação primeiro.
Código sem testes ou testes tardios	A skill `test-driven-development` força a adoção do ciclo RED-GREEN-REFACTOR.
Decisões técnicas perdidas ou esquecidas	A skill `analyze` detecta e reporta divergências entre spec, plan, tasks e o código final.
Configuração tediosa em todo projeto novo	Comandos unificados (`install`, `--scope user`, extensões) automatizam o setup.

E o maior benefício: você não precisa invocar manualmente as etapas. As skills são projetadas para disparar de forma autônoma nos momentos corretos, em qualquer uma das plataformas suportadas, entregando um Pull Request limpo ao final do processo.

Como Começar

Adotar o framework é rápido e exige apenas o ambiente Python configurado:

# 1. Instale a CLI globalmente
pip install aiadev

# 2. Acesse o seu projeto e instale o preset adequado à sua stack
cd meu-projeto
aiadev install --preset lean              # Pipeline genérico e enxuto
aiadev install --preset django-drf-react  # Foco em Web full-stack
aiadev install --preset mobile-ops        # Foco em Cloud Run + Expo

# 3. Escolha a sua plataforma de IA favorita (Padrão: claude-code)
aiadev install --preset lean --platform cursor

# 4. Quer interagir em português? Inicialize com a flag de idioma
aiadev init --language pt-BR

# 5. Verifique se a instalação está correta
aiadev doctor

Inicie uma nova sessão, solicite a criação de uma feature em linguagem natural e assista ao seu agente puxar a skill specify antes de digitar a primeira linha de código.

Quem Deveria Usar?

Desenvolvedores Solo: Que buscam maximizar a produtividade da IA sem abrir mão da qualidade e organização de software.
Equipes: Que necessitam de um processo de IA consistente e previsível em um ambiente com múltiplos contribuidores.
Empresas: Que desejam padronizar metodologias no uso de IA generativa, sem se tornarem reféns de uma única ferramenta do mercado.
Mantenedores de Infraestrutura: Que podem tirar proveito do sistema de extensões para distribuir presets de arquitetura internos de forma eficiente.

Próximos Passos

Com a esteira de desenvolvimento completa, suporte a cinco plataformas principais e integração nativa com MCP estabelecidos, o roadmap futuro mira na criação de presets temáticos adicionais (como Dados, Machine Learning e Infraestrutura), telemetria opt-in para avaliar o desempenho das skills e novas ferramentas voltadas à validação de especificações por múltiplos agentes especializados.

O objetivo inicial, porém, já foi conquistado: construir um framework completo para o uso produtivo, disciplinado o suficiente para projetos de alto nível e aberto para a comunidade evoluir e adaptar.

Repositório Oficial: https://github.com/suportly/ai-augmented-developer
Versão Atual: 0.11.0 (Lançada em 15/abr/2026)
Licença: MIT
Instalação rápida: pip install aiadev

AI-Augmented Developer: How to Turn Your AI Agent into a Disciplined Engineer

Alair Joao Tavares — Wed, 15 Apr 2026 19:45:30 +0000

The Problem Nobody Wants to Admit

If you build software with AI, you know the loop: you describe a feature, and the agent jumps straight into writing code before understanding the problem. It skips the tests, invents context, and three hours later, you're reviewing an 800-line diff only to find half of it doesn't do what you asked.

This isn't just the model's fault. It's the absence of process. Senior engineers don't open the editor first—they specify, plan, test, and review. The AI agent is missing that exact same methodology.

That's exactly what the AI-Augmented Developer framework delivers.

What is AI-Augmented Developer?

AI-Augmented Developer (aiadev) is a complete workflow framework for coding agents. It installs a set of composable skills and bootstrap instructions that ensure the agent uses them automatically—so you don't have to remember to prompt it correctly.

The philosophy is blunt:

Spec-first: No code is written without an approved specification.
Test-first: RED-GREEN-REFACTOR is a contract, not a suggestion.
Evidence over claims: The agent must verify its work before declaring success.
Simplicity as a primary goal: YAGNI (You Aren't Gonna Need It) and DRY (Don't Repeat Yourself) are laws, not tips.

The standard pipeline enforces an eight-stage engineering lifecycle:

specify → clarify → plan → tasks → implement
                                       │
                          test-driven-development (per task)
                          systematic-debugging (on failures)
                          checklist (security, perf, a11y, i18n…)
                                       ↓
                               analyze → requesting-code-review → finishing-a-branch

Each stage is a "skill" that fires autonomously at the right moment. The agent doesn't skip steps or hallucinate context; it explicitly shows you the spec before writing its first test.

The Constitution: Seven Non-Negotiable Rules

The heart of the framework is constitution.md, containing seven principles every technical decision must honor:

Spec-first — No approved spec, no code.
Test-first — A failing test must exist before implementation.
Simplicity — Build the simplest thing that works.
Evidence over claims — Run it, prove it, show it.
Provider pattern — Keep external dependencies behind interfaces.
Privacy by design — Sensitive data never leaks to LLMs.
Attribution — Credit every derivative work.

Every plan produced by the plan skill carries a Constitution Check table. If the agent breaks an article, the violation goes into a Complexity Tracking section with a required justification. Without this discipline, the framework refuses to move forward.

Rapid Evolution: 9 Releases in 48 Hours

Between April 14 and 15, 2026, the project rapidly shipped from v0.3 to v0.11. Each release tackled a real friction point for daily users.

v0.3: Interactive `aiadev install`

A Python CLI replaced ad-hoc scripts. A single command now renders a preset (substituting variables and placing files) into your project, complete with --dry-run, --uninstall, and drift detection against hand edits.

v0.4: Cursor Support

The first platform handler beyond Claude Code. It introduced full end-to-end round-trip support, fully documented.

v0.5: Codex, OpenCode, and Gemini Integration

Three more platforms arrived in a single release. The five major AI development tools are now officially covered: Claude Code, Cursor, Codex, OpenCode, and Gemini CLI. Each handler is a self-contained ~30-line module with 100% test coverage.

v0.6: User-Level Scope

Running --scope user installs skills once per machine under ~/.<platform>/skills/. Every project on your workstation inherits the same catalog with no repeated setup, while files containing project-specific variables (CLAUDE.md, constitution.md) stay local to the project.

v0.7: PyPI Distribution

You can now simply run pip install aiadev. The wheel bundles constitution.md, templates/, schemas/, skills/, presets/, and agents/—no repo clone required. It is published via OIDC trusted publishing, with no tokens stored in the repository.

v0.8: Extension System

aiadev extension add <git-url> allows anyone to ship third-party preset catalogs. Community catalogs, private corporate presets, and experimental builds are now supported. Built-ins win on name collisions, notifying users with a yellow warning when an extension is shadowed.

v0.9: Full Pipeline Installation and `aiadev sync`

The biggest paradigm shift. The install command now equips a project with the entire pipeline at once: 14 slash commands, 3 agents, 5 coding rules, and the full catalog of generic skills. The new aiadev sync command pulls framework updates into existing projects and regenerates an  block inside CLAUDE.md based on project introspection (package.json, pyproject.toml, Cargo.toml, go.mod, docker-compose, etc.).

v0.10: Namespacing and Sequential Specs

Slash commands gained a structured namespace (e.g., /aiadev:specify, /aiadev:plan). Specs transitioned from a feature-<slug>/ scheme to zero-padded sequential IDs (specs/0001-<slug>/). Additionally, aiadev init --language pt-BR configures the entire pipeline to operate in the user's chosen language.

v0.11: Universal Model Context Protocol (MCP)

The Model Context Protocol is now a first-class citizen. You declare servers once in mcps.yaml, and aiadev install translates them to each platform's native format:

Claude Code: .mcp.json
Cursor: .cursor/mcp.json
Gemini CLI: .gemini/settings.json
Codex: .codex/config.toml
OpenCode: opencode.json

MCP stops being repetitive boilerplate and becomes a simple configuration detail.

Why This Framework Matters

Nine releases in 48 hours, each solving a concrete pain point without regressions or breaking changes. That is the framework successfully applying itself to itself: specs live under specs/, plans were generated by the plan skill, and commits follow the feat(<area>): T<N> <title> pattern enforced by the tasks skill.

For anyone building with AI, aiadev solves four critical problems at once:

Developer Pain Point	Framework Solution
Agent codes without understanding the problem	The `specify` skill forces specification first.
Code lacks tests, or tests are an afterthought	The `test-driven-development` skill enforces RED-GREEN-REFACTOR.
Forgotten decisions and scope drift	The `analyze` skill reports divergence between the spec, plan, tasks, and code.
Tedious manual setup per project	`aiadev install` + `--scope user` + extensions automate everything.

Best of all: you don't need to manually invoke anything. Skills fire autonomously at the right moment across all five supported platforms, backed by a single MCP server declaration, ultimately delivering a clean PR.

Getting Started

# 1. Install the CLI
pip install aiadev

# 2. Enter a project and install the preset that fits
cd your-project
aiadev install --preset lean              # Generic pipeline
aiadev install --preset django-drf-react  # Full-stack web
aiadev install --preset mobile-ops        # Cloud Run + Expo

# 3. Pick your preferred platform (default is claude-code)
aiadev install --preset lean --platform cursor

# 4. Working in another language? Initialize with a language flag
aiadev init --language en

# 5. Verify your installation
aiadev doctor

Start a fresh session, ask for a feature in natural language, and watch the agent instinctively reach for specify before writing a single line of code.

Who is it For?

Solo developers who want maximum productivity without sacrificing code quality.
Teams that need a consistent, unified process across multiple human contributors and AI agents.
Enterprises looking to standardize AI usage without vendor lock-in to a single platform.
Platform engineering teams maintaining internal tooling—the extensions system perfectly handles corporate distribution.

What's Next?

With the core pipeline complete, five major platforms wired, and MCP fully integrated, the foundation is solid. The natural next steps include themed presets (data engineering, machine learning, infrastructure), opt-in telemetry to determine which skills generate the most value, and specialized agents to automatically validate specs.

But the core promise is already here: the framework is complete enough for daily use, disciplined enough for serious production projects, and open enough for the community to evolve.

Repository: github.com/suportly/ai-augmented-developer
Current version: 0.11.0 (Apr 15, 2026)
License: MIT
Install: pip install aiadev

Como Tornar o Claude Code Mais Inteligente

Alair Joao Tavares — Tue, 14 Apr 2026 14:11:26 +0000

O Problema: Quando o Modelo Decide Não Pensar

O Adaptive Thinking funciona assim: antes de cada resposta, o modelo avalia a complexidade percebida da sua requisição e aloca tokens de raciocínio proporcionalmente. Tarefa simples? Poucos tokens. Tarefa complexa? Mais tokens.

O problema é que essa avaliação falha com frequência preocupante. Boris Cherny, do time do Claude Code na Anthropic, confirmou publicamente no Hacker News que em certos turnos o modo adaptativo alocava zero tokens de raciocínio — o modelo literalmente decidia não pensar antes de responder.

O resultado era previsível: fabricações confiantes. SHAs de commits que não existiam, versões de API inventadas, pacotes que nunca foram publicados — tudo entregue com a mesma assertividade de uma resposta correta. E o padrão era claro: os turnos com raciocínio profundo acertavam; os turnos com zero raciocínio fabricavam.

Esse cenário piorou em março de 2026, quando o nível de esforço padrão caiu de high para medium. Com menos esforço e raciocínio adaptativo, o modelo passou a economizar em duas frentes ao mesmo tempo — e a qualidade despencou para quem trabalhava em projetos complexos.

A Solução: Forçar um Orçamento Fixo de Raciocínio

Quando você define CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1, o Claude Code para de deixar o modelo escolher quanto pensar. Em vez disso, ele utiliza um orçamento fixo de tokens de raciocínio em todos os turnos, controlado pela variável MAX_THINKING_TOKENS.

Na prática, isso significa que mesmo quando o modelo acha que a tarefa é simples, ele ainda é obrigado a pensar antes de responder. Aquele bug "trivial" que na verdade envolve uma race condition em três microsserviços? O modelo vai analisar em vez de chutar.

Mas a flag sozinha resolve apenas metade do problema. Para máximo impacto, combine-a com o nível de esforço:

export CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1
export CLAUDE_CODE_EFFORT_LEVEL=high

Com essas duas configurações ativas, o Claude Code mantém o nível máximo de raciocínio em todos os turnos, sem nunca decidir autonomamente "economizar" tokens. O modelo pensa com profundidade constante, indiscriminadamente.

O Que Muda na Prática

A diferença é perceptível já nas primeiras interações:

Debugging complexo. Em vez de sugerir "tente adicionar um print aqui", o modelo analisa o fluxo inteiro, identifica dependências entre módulos e aponta a causa raiz — mesmo quando ela está a três camadas de abstração do sintoma.

Refatoração multi-arquivo. O modelo mantém o contexto entre arquivos e propõe mudanças coerentes em vez de editar cada arquivo isoladamente, introduzindo inconsistências.

Decisões de arquitetura. Ao perguntar "qual padrão usar aqui?", o modelo pondera trade-offs reais em vez de entregar a resposta genérica mais provável.

Menos alucinações. Sem a possibilidade de pular o raciocínio, o modelo verifica nomes de pacotes, versões de API e identificadores antes de afirmá-los — reduzindo drasticamente as fabricações que corroem a confiança.

Configuração Completa

Linux e macOS (Bash/Zsh)

Para aplicar apenas à execução atual:

CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 CLAUDE_CODE_EFFORT_LEVEL=high claude

Para tornar persistente, adicione ao seu ~/.bashrc ou ~/.zshrc:

export CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1
export CLAUDE_CODE_EFFORT_LEVEL=high

Windows (PowerShell)

Para a sessão atual:

$env:CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING = "1"
$env:CLAUDE_CODE_EFFORT_LEVEL = "high"
claude

Para tornar persistente, adicione ao seu perfil ($PROFILE):

$env:CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING = "1"
$env:CLAUDE_CODE_EFFORT_LEVEL = "high"

Via settings.json do Claude Code

Se preferir manter a configuração dentro do ecossistema do Claude Code:

{
  "env": {
    "CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING": "1"
  }
}

O nível de esforço também pode ser definido com o comando /effort high dentro da sessão ou configurado no mesmo arquivo de settings.

Quando Usar (e Quando Não Usar)

Essa configuração consome mais tokens em todas as respostas — é o preço da profundidade. Por isso vale calibrar por tipo de tarefa:

Use DISABLE_ADAPTIVE_THINKING=1 + effort high/max quando:

Estiver debugando bugs complexos em codebases grandes
Fizer refatoração ou migração multi-arquivo
Precisar de decisões arquiteturais fundamentadas
Trabalhar com APIs desconhecidas ou pouco documentadas
Orquestrar múltiplos agentes em tarefas críticas

Mantenha o adaptive thinking ativado quando:

Fizer tarefas simples: commits, leitura de código, perguntas rápidas
Usar sub-agentes para operações triviais
A latência for mais importante que a profundidade

Uma abordagem prática é criar um alias no seu shell:

alias claude-deep="CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 CLAUDE_CODE_EFFORT_LEVEL=max claude"

Assim você mantém o claude padrão para tarefas leves e invoca claude-deep quando precisa de raciocínio máximo.

Conclusão

O Claude Code com Opus 4.6 é extraordinariamente capaz — mas sua configuração padrão prioriza eficiência sobre profundidade. Para quem trabalha em projetos complexos, isso significa conviver com respostas rasas e fabricações evitáveis.

CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 não é um hack obscuro. É um workaround reconhecido oficialmente pela equipe do Claude Code enquanto investigam a subalocação de raciocínio no modo adaptativo. Combinada com effort=high, essa configuração transforma o Claude Code de um assistente apressado em um engenheiro que pensa antes de falar.

O controle está nas suas mãos. Use-o.

Tags: claude-code · anthropic · cli · produtividade · extended-thinking

Reduzindo o TTFT em Streaming de IA: Padrões de Arquitetura para Flush por Yield no Django

Alair Joao Tavares — Mon, 13 Apr 2026 13:45:13 +0000

Reduzindo o TTFT em Streaming de IA: Padrões de Arquitetura para Flush por Yield no Django

A era das aplicações impulsionadas por Inteligência Artificial (IA) trouxe novas expectativas de experiência do usuário (UX). Quando interagimos com um Large Language Model (LLM), como modelos de chat ou assistentes de código, a expectativa é ver a resposta aparecer na tela palavra por palavra, quase instantaneamente. Ninguém quer ficar encarando um ícone de carregamento por 15 segundos enquanto o servidor processa a resposta completa.

É aqui que entra uma métrica crucial na arquitetura de aplicações de IA: o Time-To-First-Token (TTFT), ou o Tempo até o Primeiro Token. O TTFT mede a latência entre a solicitação do usuário e a entrega do primeiro pedaço de texto gerado pelo modelo.

Neste artigo, vamos explorar como fazer a transição do ciclo tradicional de requisição/resposta do Django para uma arquitetura de streaming assíncrono. Vamos entender como utilizar o ASGI, as views assíncronas (AsyncIO) e o padrão de flush por yield contínuo para reduzir drasticamente o TTFT em suas aplicações Django.

1. O Gargalo do Ciclo Padrão de Resposta (WSGI)

Historicamente, o Django foi construído sobre o protocolo WSGI (Web Server Gateway Interface), que é fundamentalmente síncrono. O ciclo de vida de uma requisição típica funciona da seguinte forma:

O servidor recebe a requisição.
A view é chamada e executa sua lógica.
O servidor aguarda a view retornar um objeto HttpResponse completo.
A resposta inteira é enviada de volta ao cliente de uma só vez.

Quando integramos chamadas a APIs de LLMs sob esse paradigma, criamos um enorme gargalo. Veja o exemplo de uma view síncrona tradicional:

import json
from django.http import JsonResponse
from meu_app.services import llm_service

def chat_sincrono_view(request):
    user_prompt = request.POST.get('prompt', '')

    # A execução BLOQUEIA aqui até que todo o texto seja gerado
    full_response = llm_service.generate_full_text(user_prompt)

    return JsonResponse({
        'status': 'success',
        'response': full_response
    })

Neste cenário, se o modelo levar 10 segundos para gerar um parágrafo de 300 palavras, o usuário ficará olhando para uma tela vazia por exatamente 10 segundos. O TTFT é igual ao tempo total de geração. Isso resulta em uma péssima experiência de usuário e pode levar a timeouts no balanceador de carga ou no proxy reverso.

2. A Transição para ASGI e Views Assíncronas

Para resolver esse problema, precisamos adotar o padrão assíncrono. O Django introduziu suporte a views assíncronas a partir da versão 3.1 e vem aprimorando seu ecossistema ASGI (Asynchronous Server Gateway Interface) nas versões mais recentes (4.x e 5.x).

Ao executar o Django sob um servidor ASGI (como Uvicorn ou Daphne), podemos liberar a thread principal para lidar com outras requisições enquanto aguardamos I/O (como a resposta da API do LLM) e, mais importante, podemos transmitir a resposta em pedaços (chunks) assim que eles chegam.

Primeiro, precisamos de um cliente LLM que suporte streaming assíncrono. Abaixo está um exemplo genérico de como esse cliente se pareceria usando aiohttp ou a biblioteca assíncrona oficial de um provedor de IA:

# meu_app/services/llm_client.py
import asyncio

class AsyncLLMClient:
    async def stream_response(self, prompt: str):
        """
        Simula um gerador assíncrono que faz streaming de tokens de um LLM.
        Na prática, isso seria uma chamada a uma API externa.
        """
        tokens_simulados = ["Olá", ", ", "como ", "posso ", "ajudar ", "hoje", "?"]

        for token in tokens_simulados:
            # Simula a latência de geração de cada token
            await asyncio.sleep(0.1)
            yield token

3. Implementando o Flush por Yield com StreamingHttpResponse

Para enviar esses tokens para o cliente assim que são gerados, utilizaremos o StreamingHttpResponse do Django em conjunto com um gerador assíncrono no Python (funções que usam yield em vez de return).

O conceito de per-yield flushing significa que cada vez que o nosso código executa um yield, o servidor ASGI imediatamente "descarrega" (flushes) esse pedaço de dado pela conexão de rede até o cliente frontal, sem esperar o término da função.

Veja a arquitetura da view:

# meu_app/views.py
import asyncio
from django.http import StreamingHttpResponse
from meu_app.services.llm_client import AsyncLLMClient

async def chat_streaming_view(request):
    user_prompt = request.GET.get('prompt', 'Diga um oi')
    llm_client = AsyncLLMClient()

    async def event_stream():
        try:
            # Itera de forma assíncrona sobre o gerador de tokens
            async for chunk in llm_client.stream_response(user_prompt):
                # O yield passa o chunk para o StreamingHttpResponse
                yield chunk

                # Garante que o loop de eventos seja liberado (boa prática)
                await asyncio.sleep(0)

        except asyncio.CancelledError:
            # Trata o cenário onde o cliente fecha a aba/conexão no meio da geração
            print("Conexão com o cliente encerrada prematuramente.")
            raise

    # Retorna o StreamingHttpResponse injetando o gerador assíncrono
    return StreamingHttpResponse(
        event_stream(),
        content_type='text/plain'
    )

O que acontece por baixo dos panos?

O Django não aguarda a conclusão da função event_stream(). Ele retorna os cabeçalhos HTTP imediatamente.
Assim que o llm_client gera o token "Olá", a função faz o yield.
O ASGI intercepta o yield e o envia pela conexão TCP.
O frontend recebe "Olá" quase imediatamente. O TTFT foi reduzido a frações de segundo.
O loop continua até o fim da geração.

4. Estruturando os Dados com Server-Sent Events (SSE)

Embora enviar texto puro (text/plain) funcione para testes, aplicações web reais (como um frontend em React) preferem um padrão mais robusto para consumir streams em tempo real. O padrão da indústria para isso é o Server-Sent Events (SSE).

O SSE exige um formato de texto específico e um content-type próprio. Vamos adaptar nossa view para enviar os dados formatados corretamente.

# meu_app/views.py
import json
import asyncio
from django.http import StreamingHttpResponse
from meu_app.services.llm_client import AsyncLLMClient

async def chat_sse_streaming_view(request):
    user_prompt = request.GET.get('prompt', '')
    llm_client = AsyncLLMClient()

    async def sse_event_stream():
        try:
            async for token in llm_client.stream_response(user_prompt):
                # Formatação padrão SSE: "data: {seu_dado}\n\n"
                payload = json.dumps({"token": token})
                yield f"data: {payload}\n\n"

            # Sinaliza o fim do stream
            yield f"data: [DONE]\n\n"

        except asyncio.CancelledError:
            pass

    # O content-type text/event-stream avisa o navegador para tratar como SSE
    return StreamingHttpResponse(
        sse_event_stream(),
        content_type='text/event-stream',
        headers={
            'Cache-Control': 'no-cache',
            'Connection': 'keep-alive',
            'X-Accel-Buffering': 'no' # Importante para Proxies
        }
    )

No frontend (React, por exemplo), você consumiria essa API usando a API padrão do navegador, ou usando clientes robustos como o fetch com a API ReadableStream:

// Exemplo genérico no Frontend (TypeScript/React)
async function fetchStream() {
  const response = await fetch('/api/chat/stream?prompt=teste');
  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { value, done } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    console.log("Recebido:", chunk);
    // Aqui você processa o 'data: {...}' e atualiza a UI do usuário
  }
}

5. Dicas Práticas e Melhores Práticas

Implementar streaming no Django não envolve apenas código Python; envolve infraestrutura e gerenciamento de banco de dados. Aqui estão as regras de ouro:

Cuidado com Proxies e Buffering (A armadilha do Nginx)

De nada adianta ter um backend perfeitamente configurado com per-yield flushing se o seu proxy reverso armazena a resposta em buffer. O Nginx, por padrão, tenta acumular dados para enviá-los de forma eficiente.

Para que o streaming funcione em produção, você deve desativar o proxy buffering. No Nginx, adicione a seguinte linha na sua configuração do location:

location /api/chat/stream {
    proxy_pass http://seu_backend;
    proxy_buffering off;
    proxy_read_timeout 86400s; 
}

(Dica: O cabeçalho X-Accel-Buffering: no adicionado na nossa view anterior ajuda a sinalizar o Nginx automaticamente em algumas configurações).

Banco de Dados no Ciclo Assíncrono

Se você precisar salvar as mensagens no banco de dados, lembre-se de que o ORM do Django, embora tenha ganhado suporte assíncrono, pode ser complexo dentro de geradores.

Use os métodos assíncronos oficiais (como await Message.objects.acreate(...)) ou envolva as operações síncronas pesadas utilizando o sync_to_async do módulo asgiref.sync:

from asgiref.sync import sync_to_async

@sync_to_async
def save_message(user, text):
    # Operação de I/O síncrona com o DB
    return Message.objects.create(user=user, content=text)

Atenção: Faça o salvamento no banco de dados preferencialmente após o bloco async for para não atrasar a entrega dos tokens ao cliente, mantendo o TTFT baixo.

Escolha o Servidor ASGI Correto

Você não pode rodar isso usando o gunicorn tradicional com workers síncronos. Você precisa de um servidor ASGI como o Uvicorn. Em produção, o padrão da indústria é executar o Uvicorn gerenciado pelo Gunicorn:

# Comando de execução em produção
gunicorn meu_projeto.asgi:application -k uvicorn.workers.UvicornWorker --workers 4

Conclusão

Reduzir o Time-To-First-Token não é apenas uma métrica de vaidade no monitoramento de performance; é um aspecto diretamente ligado à percepção psicológica de velocidade pelo usuário final.

Ao fazer a transição de views WSGI estáticas para views ASGI assíncronas no Django, aliadas ao poder do StreamingHttpResponse e ao padrão Server-Sent Events (SSE), você consegue extrair latências ultra baixas de sistemas que antes pareciam letárgicos.

A arquitetura de flush por yield garante que seu servidor aja como um conduite em tempo real, pegando a magia gerada pela IA e colocando-a nos olhos do usuário no exato milissegundo em que cada palavra nasce. Aplique esses padrões no seu próximo serviço de chat ou integração de LLM e sinta a diferença na experiência de uso imediato.

Architecting a Robust Django Management Command for Stripe Subscription Plan Synchronization

Alair Joao Tavares — Mon, 13 Apr 2026 01:55:15 +0000

Keeping your application's internal data consistent with a third-party service is one of the classic challenges in modern software development. This is especially true for critical systems like billing. When your subscription plans are managed by a service like Stripe, ensuring that your local database reflects the exact state of your products and prices is paramount. Relying on manual updates in both the Stripe dashboard and your application's admin panel is a recipe for inconsistency, billing errors, and frustrated customers.

So, how do we build a reliable bridge between our Django application and Stripe? The answer lies in automation. In this article, we'll design and implement a robust Django management command that acts as a single source of truth, synchronizing your subscription plans with Stripe idempotently. We'll explore the entire process, from data modeling and command structure to handling the nuances of the Stripe API and implementing best practices like dry runs. By the end, you'll have a clear blueprint for building a resilient, automated synchronization system for any critical third-party integration.

1. Data Modeling: The Local Foundation for Your Billing System

Before we can synchronize anything, our Django application needs a way to represent subscription plans locally. It's tempting to think we could just query the Stripe API whenever we need plan information, but this approach is slow, inefficient, and tightly couples our application to an external service. A much better pattern is to create local models that mirror the essential attributes of Stripe's Product and Price objects.

Our local models will serve two primary purposes:

Performance: Storing plan details locally allows for fast lookups without constant API calls.
Linking: They will hold the unique Stripe IDs (stripe_product_id, stripe_price_id), creating an unbreakable link between our local records and their counterparts in Stripe.

Let's define a simple model structure in our billing app. We'll create a SubscriptionPlan model to represent the core offering (like 'Basic', 'Pro', 'Enterprise'). This corresponds to a Stripe Product.

# billing/models.py

from django.db import models

class SubscriptionPlan(models.Model):
    """Represents a subscription plan that maps to a Stripe Product and Price."""

    class Interval(models.TextChoices):
        MONTH = "month", "Month"
        YEAR = "year", "Year"

    name = models.CharField(max_length=100, help_text="The display name of the plan.")
    # A unique code to identify the plan programmatically
    plan_code = models.CharField(max_length=50, unique=True, help_text="A unique, machine-readable code for the plan.")

    # Stripe-related fields
    stripe_product_id = models.CharField(max_length=255, blank=True, null=True, unique=True)
    stripe_price_id = models.CharField(max_length=255, blank=True, null=True, unique=True)

    # Plan details that will be synced to Stripe Price
    price = models.DecimalField(max_digits=10, decimal_places=2, help_text="Price in USD.")
    interval = models.CharField(max_length=10, choices=Interval.choices, default=Interval.MONTH)
    is_active = models.BooleanField(default=True, help_text="Whether this plan is available for new subscriptions.")

    def __str__(self):
        return f"{self.name} - ${self.price}/{self.interval}"

    class Meta:
        ordering = ["price"]

In this model:

plan_code is our internal unique identifier. This is crucial for looking up plans reliably without needing a Stripe ID first.
stripe_product_id and stripe_price_id will store the IDs generated by Stripe. Making them unique=True ensures data integrity.
price and interval are the core attributes we'll need to create a Stripe Price object.

After defining this model, you'd run python manage.py makemigrations billing and python manage.py migrate to apply the changes to your database. This gives us the foundation to store the synchronized data.

2. A Declarative Source of Truth for Your Plans

To make our synchronization command robust, we should avoid hardcoding plan details directly within the command's logic. A much cleaner approach is to define our plans in a declarative format, creating a single source of truth. This could be a YAML file, a JSON file, or, for simplicity and flexibility, a Python dictionary in a configuration file.

Let's create a plans_config.py file within our billing app:

# billing/plans_config.py

PLANS = {
    "basic_monthly": {
        "name": "Basic Plan",
        "price": 10.00,
        "interval": "month",
        "features": [
            "5 Projects",
            "Basic Analytics",
            "Email Support"
        ]
    },
    "pro_monthly": {
        "name": "Pro Plan",
        "price": 25.00,
        "interval": "month",
        "features": [
            "50 Projects",
            "Advanced Analytics",
            "Priority Email Support"
        ]
    },
    "pro_yearly": {
        "name": "Pro Plan (Yearly)",
        "price": 250.00,
        "interval": "year",
        "features": [
            "50 Projects",
            "Advanced Analytics",
            "Priority Email Support"
        ]
    },
}

This approach has several advantages:

Clarity: All available plans are defined in one easy-to-read location.
Maintainability: To add, remove, or modify a plan, you only need to change this configuration file.
Decoupling: The synchronization logic is separate from the plan data itself.

Our management command will read this configuration and ensure the state of our database and Stripe matches it perfectly.

3. Building the Idempotent Synchronization Command

Now we get to the core of the implementation: the Django management command. A management command is a script that can be run from the command line with python manage.py <command_name>. It's the perfect tool for administrative tasks like this.

Let's create billing/management/commands/configure_plans.py. The command's logic should be idempotent, meaning running it multiple times should produce the same result without creating duplicates or causing errors.

Here's the structure of our command:

# billing/management/commands/configure_plans.py

import os
import stripe
from django.core.management.base import BaseCommand
from django.db import transaction

from billing.models import SubscriptionPlan
from billing.plans_config import PLANS

stripe.api_key = os.getenv("STRIPE_API_KEY")

class Command(BaseCommand):
    help = "Synchronizes subscription plans from plans_config.py with the local DB and Stripe."

    def add_arguments(self, parser):
        parser.add_argument(
            "--dry-run",
            action="store_true",
            help="Simulates the synchronization without making any changes to the DB or Stripe.",
        )

    @transaction.atomic
    def handle(self, *args, **options):
        dry_run = options["dry_run"]
        self.stdout.write("Starting subscription plan synchronization...")

        for plan_code, config in PLANS.items():
            self.stdout.write(f"Processing plan: {plan_code}...")

            plan, created = SubscriptionPlan.objects.get_or_create(
                plan_code=plan_code,
                defaults={
                    'name': config['name'],
                    'price': config['price'],
                    'interval': config['interval'],
                }
            )

            if created:
                self.stdout.write(self.style.SUCCESS(f"  -> Created new local plan '{plan.name}'."))
            else:
                self.stdout.write(f"  -> Found existing local plan '{plan.name}'.")

            # --- Step 1: Synchronize Stripe Product ---
            product_id = self.sync_stripe_product(plan, config, dry_run)
            plan.stripe_product_id = product_id

            # --- Step 2: Synchronize Stripe Price ---
            # Prices are immutable in Stripe. If price or interval changes, we must create a new one.
            price_changed = plan.price != config['price'] or plan.interval != config['interval']
            if price_changed and not created:
                self.stdout.write(self.style.WARNING(f"  -> Price or interval for '{plan.name}' has changed. A new Stripe Price will be created."))

            price_id = self.sync_stripe_price(plan, config, price_changed, dry_run)
            plan.stripe_price_id = price_id

            # --- Step 3: Update local DB with latest details ---
            plan.name = config['name']
            plan.price = config['price']
            plan.interval = config['interval']
            plan.is_active = True # We can assume if it's in the config, it's active

            if not dry_run:
                plan.save()
                self.stdout.write(f"  -> Saved local plan with Stripe IDs.")

        self.deactivate_old_plans(dry_run)

        if dry_run:
            self.stdout.write(self.style.WARNING("\nDRY RUN COMPLETE. No changes were made."))
        else:
            self.stdout.write(self.style.SUCCESS("\nSynchronization complete."))

    def sync_stripe_product(self, plan, config, dry_run):
        # Logic to create or update a Stripe Product
        # (Implementation in next section)
        pass

    def sync_stripe_price(self, plan, config, price_changed, dry_run):
        # Logic to create a new Stripe Price if needed
        # (Implementation in next section)
        pass

    def deactivate_old_plans(self, dry_run):
        # Logic to deactivate plans not in the config file
        # (Implementation in next section)
        pass

This structure gives us a clear, step-by-step process wrapped in a database transaction. The --dry-run flag is a crucial safety feature, allowing us to preview changes before applying them.

4. Handling Stripe API Nuances: Products and Prices

Now let's implement the methods that interact with Stripe. The key here is to handle Stripe's object model correctly. Specifically, Stripe Products are mutable, but Prices are not. If you need to change a price, you must create a new Price object and attach it to the Product.

Here are the implementations for our sync_* methods.

# Add these methods to the Command class in configure_plans.py

def sync_stripe_product(self, plan, config, dry_run):
    """Creates or updates a Stripe Product based on the plan configuration."""
    if plan.stripe_product_id:
        # Product exists, update it if necessary
        try:
            product = stripe.Product.retrieve(plan.stripe_product_id)
            self.stdout.write(f"  -> Found existing Stripe Product: {product.id}")
            if product.name != config['name']:
                self.stdout.write(f"     -> Updating product name to '{config['name']}'.")
                if not dry_run:
                    stripe.Product.modify(product.id, name=config['name'])
            return product.id
        except stripe.error.InvalidRequestError:
            self.stdout.write(self.style.WARNING(f"  -> Stripe Product {plan.stripe_product_id} not found. Creating a new one."))
            # Fall through to create a new one

    self.stdout.write(f"  -> Creating new Stripe Product for '{config['name']}'.")
    if dry_run:
        return "prod_dry_run_mock_id"

    product = stripe.Product.create(
        name=config['name'],
        metadata={'plan_code': plan.plan_code}
    )
    self.stdout.write(self.style.SUCCESS(f"  -> Created Stripe Product: {product.id}"))
    return product.id

def sync_stripe_price(self, plan, config, price_changed, dry_run):
    """Creates a new Stripe Price if one doesn't exist or if details have changed."""
    # If the price hasn't changed and a price ID already exists, we're done.
    if not price_changed and plan.stripe_price_id:
        self.stdout.write(f"  -> Stripe Price {plan.stripe_price_id} is up to date.")
        return plan.stripe_price_id

    self.stdout.write(f"  -> Creating new Stripe Price for {config['name']}.")
    if dry_run:
        return "price_dry_run_mock_id"

    # Stripe requires price in cents
    unit_amount = int(config['price'] * 100)

    price = stripe.Price.create(
        product=plan.stripe_product_id,
        unit_amount=unit_amount,
        currency="usd",
        recurring={"interval": config['interval']},
        metadata={'plan_code': plan.plan_code}
    )
    self.stdout.write(self.style.SUCCESS(f"  -> Created Stripe Price: {price.id}"))
    return price.id

def deactivate_old_plans(self, dry_run):
    """Deactivates any local plans that are no longer in the config file."""
    active_plan_codes = PLANS.keys()
    stale_plans = SubscriptionPlan.objects.filter(is_active=True).exclude(plan_code__in=active_plan_codes)

    for plan in stale_plans:
        self.stdout.write(self.style.WARNING(f"Deactivating stale plan: {plan.name} ({plan.plan_code})"))
        if not dry_run:
            plan.is_active = False
            plan.save()
            # We might also want to archive the Stripe Product here
            # stripe.Product.modify(plan.stripe_product_id, active=False)

Key takeaways from this implementation:

Idempotent Product Sync: We first try to retrieve the product. If it exists, we update it. If not, we create it. We also store our internal plan_code in Stripe's metadata for easy cross-referencing.
Immutable Price Handling: We only create a new price if one doesn't exist or if the price/interval has changed. We don't try to modify existing prices.
Graceful Cleanup: The deactivate_old_plans method ensures that plans removed from our configuration file are marked as inactive in our database, preventing new signups.

Conclusion: Building with Confidence

By creating a declarative configuration and a robust, idempotent Django management command, we've transformed a potentially chaotic process into a predictable and reliable system. This architecture not only ensures data consistency between your application and Stripe but also establishes a clear, maintainable workflow for managing your subscription offerings.

The key principles we've applied are:

Single Source of Truth: A configuration file (plans_config.py) dictates the desired state.
Local Caching: Django models store plan data and Stripe IDs for performance and reliability.
Idempotent Execution: The command can be run safely multiple times, always converging on the correct state.
Safety First: A --dry-run mode allows for verification before any live data is changed.

This pattern isn't limited to Stripe. You can apply the same architectural principles to synchronize data with any third-party API, building a more resilient and maintainable application. By investing in automation for these critical integrations, you free up developer time, reduce the risk of costly human error, and build a solid foundation for your application to scale.

DEV Community: Alair Joao Tavares

Debugging Legacy Bottlenecks with AI: A Systematic Workflow for Complex Codebases

Debugging Legacy Bottlenecks with AI: A Systematic Workflow for Complex Codebases

The Problem with Legacy Debugging

Step 1: Use AI to Build a Map Before You Touch Anything

Step 2: Validate Assumptions with Targeted Tests Before Refactoring

Step 3: Constrain the AI to Your Boundaries

Step 4: Document What You Learned, Not Just What You Changed

Practical Tips for AI-Assisted Legacy Debugging

Key Takeaways

Depurando Gargalos Legados com IA: Um Workflow Sistemático para Codebases Complexas

Depurando Gargalos Legados com IA: Um Workflow Sistemático para Codebases Complexas

O Problema: Alarmes Fantasmas em um Sistema de Monitoramento

Usando IA para Mapear Território Desconhecido

1. Contexto antes de código

2. Hipóteses antes de soluções

3. Validação incremental com TypeScript

Navegando Dependências Conflitantes: O Outro Front

Boas Práticas que Consolidei

Conclusão

Decoupling External Services: Implementing the Provider Pattern for E-Signature Integration in Django

The Problem With Hardcoding Third-Party Integrations

Designing the Abstract Interface First

Implementing the DocuSign Provider

Wiring It Together: The Provider Registry

The Mock Provider: Making Tests Sane

Practical Tips From the Trenches

Conclusion

Desacoplando Serviços Externos: Implementando o Provider Pattern para Integração de Assinatura Eletrônica

O Problema que me Fez Repensar Tudo

O que é o Provider Pattern e por que ele resolve esse problema

A Estrutura de Diretórios

Definindo a Interface Abstrata

Implementando o Provedor DocuSign

O Registro e o Service Layer

Boas Práticas que Aprendi na Prática

Conclusão

26,8 Bilhões de Tokens em 46 Dias: Minha Experiência Extrema Operando o Claude Code

A Alavancagem do Prompt Cache: Trabalhando com Contextos Densos

Onde os Tokens Foram Gastos: Meus Top 3 Projetos

O Meu Ritmo: Os Dias Mais Pesados

A Escolha do Arsenal: Modelos Utilizados

IA na Prática: As Ferramentas que Invoquei

O Que Significam 46 Dias e 39 Projetos

Scaling Myself: Processing 26.8 Billion Tokens in 46 Days with Claude Code

By the Numbers: 46 Days of Uninterrupted Coding

Context Caching: The Secret to Massive AI Leverage

Where the Tokens Went: Managing 39 Projects in Parallel

Working in Bursts: My Heaviest Development Days

Model Selection: Picking the Right Tool for the Job

Execution over Autocomplete: How I Used AI Tools

Conclusion: AI as a Scope Multiplier

Arquitetando CI/CD para Monorepos Mobile: Integrando npm Workspaces, EAS Builds e GitHub Actions

Arquitetando CI/CD para Monorepos Mobile: Integrando npm Workspaces, EAS Builds e GitHub Actions

O Desafio dos Monorepos no Desenvolvimento Mobile

1. Estruturando o Monorepo com npm Workspaces

Configurando um Pacote Compartilhado (TypeScript)

2. Configurando o EAS Build para o Monorepo

3. Automatizando Releases de iOS com GitHub Actions

Entendendo o Workflow

Boas Práticas e Dicas de Ouro

1. Lidando com Credenciais da Apple

2. Versionamento e Gerenciamento de Configuração

3. Evite Subir a Pasta node_modules

Conclusão

AI-Augmented Developer: Transformando Agentes de IA em Engenheiros Disciplinados

O Problema Oculto do Desenvolvimento com IA

O que é o AI-Augmented Developer?

A Constituição: Sete Artigos Fundamentais

A Evolução Acelerada do Framework

v0.3 — Instalação Interativa (aiadev install)

v0.4 & v0.5 — Suporte Multiplataforma

v0.6 — Escopo Global de Usuário

v0.7 — Publicação no PyPI

v0.8 — Sistema Robusto de Extensões

v0.9 — Instalação Completa e Sincronização

v0.10 — Namespaces e Especificações Sequenciais

v0.11 — Integração MCP Universal

Por Que Isso Importa Para o Seu Time?

Como Começar

v0.3 — Instalação Interativa (`aiadev install`)

v0.3: Interactive `aiadev install`

v0.9: Full Pipeline Installation and `aiadev sync`