O Auto Claude representa uma nova categoria de ferramentas de desenvolvimento de software: um framework autônomo de codificação multi-agente capaz de planejar, construir e validar software de forma completamente automatizada. Diferente de assistentes de código tradicionais que respondem a comandos individuais e perdem contexto entre sessões, o Auto Claude opera como um sistema completo de desenvolvimento que recebe uma descrição de tarefa e executa todo o ciclo de implementação. A arquitetura combina múltiplos agentes especializados trabalhando em paralelo, cada um com funções específicas como planejamento, codificação, revisão de qualidade e resolução de conflitos de merge. O projeto está disponível em github.com/AndyMik90/Auto-Claude sob licença AGPL-3.0.
A estrutura do Auto Claude divide-se em duas partes principais: um backend Python que contém toda a lógica de orquestração, agentes e pipelines de validação, e um frontend Electron que fornece uma interface visual em forma de Kanban para gerenciamento de tarefas. O sistema utiliza git worktrees para isolamento completo de cada tarefa, garantindo que mudanças experimentais nunca afetem a branch principal do projeto. Além disso, possui um sistema de memória persistente que permite que os agentes aprendam com sessões anteriores, acumulando conhecimento sobre padrões do código e armadilhas encontradas. Toda a comunicação com a inteligência artificial acontece através do Claude da Anthropic, utilizando o Claude Code CLI como ponte de conexão.
Arquitetura Geral do Sistema
O Auto Claude segue uma arquitetura modular organizada em duas aplicações principais dentro do diretório apps/. O backend em Python contém toda a lógica de negócio incluindo agentes autônomos, pipelines de especificação, validação de qualidade, sistema de merge e integrações externas com plataformas como Linear, GitHub e GitLab. O frontend é uma aplicação Electron que fornece a interface visual com terminais integrados, board Kanban e controles de configuração. A comunicação entre frontend e backend acontece através de processos Python iniciados pelo Electron, permitindo execução local sem dependência de servidores externos.
A estrutura do backend organiza funcionalidades em módulos especializados com responsabilidades bem definidas. O diretório agents/ contém a lógica de execução autônoma dos agentes Planner e Coder. O diretório spec/ gerencia toda a criação de especificações através de um pipeline de múltiplas fases. O diretório qa/ implementa o loop de validação de qualidade que revisa automaticamente o código gerado. O diretório merge/ resolve conflitos de código usando inteligência artificial. Cada módulo expõe uma API limpa através de arquivos de inicialização que funcionam como facades para o restante do sistema.
O sistema opera em três modos de execução distintos que atendem diferentes necessidades. O modo direto executa mudanças diretamente no repositório, sendo útil para tarefas rápidas mas arriscado para mudanças complexas. O modo worktree isolado é o padrão recomendado, criando uma cópia completa do projeto em um diretório separado onde todas as mudanças acontecem de forma segura. O modo headless via CLI permite integração com pipelines de CI/CD para automação completa. Após aprovação da QA e revisão humana, as mudanças são mescladas de volta à branch principal através do sistema de merge inteligente.
Auto-Claude/
├── apps/
│ ├── backend/ # Python - Agentes, Specs, QA, Merge
│ │ ├── agents/ # Sistema de agentes autônomos
│ │ ├── spec/ # Pipeline de criação de specs
│ │ ├── qa/ # Loop de validação de qualidade
│ │ ├── merge/ # Sistema de merge com IA
│ │ ├── memory/ # Memória persistente
│ │ ├── prompts/ # Templates de prompts para agentes
│ │ ├── core/ # Utilitários compartilhados
│ │ └── run.py # Entry point principal
│ └── frontend/ # Electron - Interface visual
│ ├── src/main/ # Processo principal Electron
│ ├── src/renderer/ # Interface React
│ └── src/preload/ # Bridge IPC seguro
├── tests/ # Suite de testes
└── guides/ # Documentação adicionalSistema de Configuração de Fases
O PhaseConfig é o coração da configuração de execução do Auto Claude, definindo qual modelo de IA usar e qual nível de pensamento aplicar em cada fase do desenvolvimento. O sistema suporta três modelos principais da família Claude: Haiku para tarefas rápidas e econômicas, Sonnet para equilíbrio entre velocidade e qualidade, e Opus para raciocínio profundo em problemas complexos. Cada fase do pipeline pode ter sua própria configuração independente, permitindo otimização de custo e qualidade conforme a necessidade específica de cada etapa.
O conceito de Thinking Level controla a profundidade de raciocínio do modelo através de um orçamento de tokens dedicados ao pensamento interno da IA. Os níveis vão de none sem pensamento estendido, passando por low com 1024 tokens, medium com 4096 tokens, high com 16384 tokens, até ultrathink com 63999 tokens máximos. Fases críticas como discovery e spec_writing usam ultrathink para análise profunda e completa do problema. Fases mais leves como requirements usam medium para manter eficiência sem sacrificar qualidade.
A configuração pode vir de três fontes com prioridades diferentes que permitem flexibilidade no uso. Argumentos passados via CLI têm precedência máxima e sobrescrevem qualquer outra configuração. Em segundo lugar vem a configuração definida no arquivo task_metadata.json dentro do diretório de spec. Por último, os valores padrão do sistema são aplicados quando nenhuma configuração específica é fornecida. Essa hierarquia permite que projetos definam padrões próprios enquanto usuários mantêm controle total via linha de comando.
# Mapeamento de modelos para IDs oficiais da Anthropic
MODEL_ID_MAP: dict[str, str] = {
"opus": "claude-opus-4-5-20251101",
"sonnet": "claude-sonnet-4-5-20250929",
"haiku": "claude-haiku-4-5-20251001",
}
# Orçamento de tokens para cada nível de pensamento
THINKING_BUDGET_MAP: dict[str, int | None] = {
"none": None, # sem pensamento estendido
"low": 1024, # pensamento básico
"medium": 4096, # pensamento moderado
"high": 16384, # pensamento profundo
"ultrathink": 63999, # pensamento máximo
}
# Configuração de thinking por fase do spec
SPEC_PHASE_THINKING_LEVELS: dict[str, str] = {
"discovery": "ultrathink", # análise inicial profunda
"spec_writing": "ultrathink", # escrita de especificação
"self_critique": "ultrathink", # auto-revisão crítica
"requirements": "medium", # coleta de requisitos
"research": "medium", # pesquisa de contexto
"planning": "medium", # criação do plano
}
def get_phase_config(
spec_dir: Path,
phase: Phase,
cli_model: str | None = None,
cli_thinking: str | None = None,
) -> tuple[str, str, int | None]:
"""Retorna configuração completa para uma fase específica."""
model_id = get_phase_model(spec_dir, phase, cli_model)
thinking_level = get_phase_thinking(spec_dir, phase, cli_thinking)
thinking_budget = get_thinking_budget(thinking_level)
return model_id, thinking_level, thinking_budgetO Agente Planner e a Criação do Plano
O Planner Agent é responsável pela primeira sessão de qualquer tarefa, tendo como missão criar o plano de implementação estruturado que guiará todo o desenvolvimento subsequente. Seu prompt extenso com mais de 900 linhas guia o agente através de múltiplas fases obrigatórias: investigação profunda do codebase existente, leitura e criação de arquivos de contexto, entendimento do tipo de workflow necessário, criação do arquivo implementation_plan.json, análise de oportunidades de paralelismo, e criação de scripts auxiliares quando necessário.
O prompt enfatiza uma distinção fundamental entre subtasks e testes que muitos sistemas confundem. Subtasks são unidades de trabalho que respeitam dependências e devem ser executadas em ordem específica. Para uma feature multi-serviço como adicionar analytics de usuário com dashboard em tempo real, testes perguntariam se o dashboard mostra dados corretamente. Subtasks, por outro lado, definem os passos concretos de implementação: primeiro construir API de eventos no backend, depois worker de agregação, depois serviço WebSocket, e finalmente o componente do dashboard.
O plano gerado segue uma estrutura hierárquica de Phases contendo Subtasks, onde cada fase tem um campo depends_on que define a ordem de execução. Cada subtask especifica o serviço afetado, arquivos a modificar, arquivos a criar, padrões de referência a seguir, e método de verificação. O sistema suporta cinco tipos de workflow: feature para funcionalidades multi-serviço, refactor para migração em estágios, investigation para caça de bugs, migration para pipelines de dados, e simple para tarefas diretas.
# Estrutura do plano de implementação gerado pelo Planner
{
"feature": "User Analytics Dashboard",
"workflow_type": "feature",
"phases": [
{
"id": "phase-1-backend",
"name": "Backend API",
"depends_on": [], # primeira fase, sem dependências
"subtasks": [
{
"id": "subtask-1-1",
"description": "Criar modelos de dados para eventos",
"service": "backend",
"files_to_modify": ["src/models/analytics.py"],
"files_to_create": ["src/models/events.py"],
"patterns_from": ["src/models/user.py"],
"verification": {
"type": "command",
"command": "python -c 'from src.models import Event'",
"expected": "OK"
},
"status": "pending"
}
]
},
{
"id": "phase-2-frontend",
"name": "Dashboard UI",
"depends_on": ["phase-1-backend"], # depende do backend
"subtasks": [
{
"id": "subtask-2-1",
"description": "Criar componente de gráficos",
"service": "frontend",
"files_to_create": ["src/components/Charts.tsx"],
"verification": {
"type": "browser",
"url": "http://localhost:3000/dashboard",
"checks": ["Gráficos renderizam", "Dados carregam"]
},
"status": "pending"
}
]
}
]
}O Agente Coder e o Loop de Implementação
O Coder Agent assume após o planner ter criado o plano, executando subtasks uma por uma em um loop autônomo contínuo. A função principal run_autonomous_agent recebe um diretório de projeto, um diretório de spec e um modelo, então itera infinitamente até que todas as subtasks estejam completas ou ocorra uma falha crítica irrecuperável. Cada iteração encontra a próxima subtask pendente respeitando dependências de fase, gera um prompt contextualizado com informações da tarefa, executa uma sessão com o Claude, e processa os resultados determinando próximos passos.
O prompt do Coder tem mais de 1100 linhas e guia o agente através de um workflow rigoroso com checkpoints obrigatórios. A fase de orientação inicial verifica o diretório atual, descobre a localização dos specs, e carrega memória de sessões anteriores. A fase de entendimento lê o plano de implementação e localiza a próxima subtask respeitando dependências. A fase de implementação executa o código seguindo padrões existentes no projeto. A fase de self-critique revisa o trabalho antes de marcar como completo. A fase de verificação executa os testes definidos na subtask. A fase de commit salva as mudanças com mensagem padronizada.
O sistema implementa recuperação robusta de erros com diferentes estratégias para cada tipo de falha identificada. Erros de tool concurrency acontecem quando o limite de ferramentas paralelas do Claude é excedido e usam backoff exponencial com contexto do erro para a próxima tentativa. Erros de rate limit pausam a execução até o tempo de reset com polling periódico para retomada antecipada quando possível. Erros de autenticação pausam indefinidamente aguardando reautenticação manual do usuário. Após cada sessão bem-sucedida, o sistema executa processamento pós-sessão que atualiza memória e registra commits para rollback seguro.
async def run_autonomous_agent(
project_dir: Path,
spec_dir: Path,
model: str,
max_iterations: int | None = None,
verbose: bool = False,
) -> None:
"""Loop principal do agente autônomo de codificação."""
# Inicializar managers de recuperação e status
recovery_manager = RecoveryManager(spec_dir, project_dir)
status_manager = StatusManager(project_dir)
status_manager.set_active(spec_dir.name, BuildState.BUILDING)
iteration = 0
while True:
iteration += 1
# Verificar se humano solicitou pausa
pause_file = spec_dir / HUMAN_INTERVENTION_FILE
if pause_file.exists():
print("PAUSADO POR INTERVENÇÃO HUMANA")
return
# Encontrar próxima subtask respeitando dependências
next_subtask = get_next_subtask(spec_dir)
if not next_subtask:
print("Nenhuma subtask pendente - build pode estar completo!")
break
# Obter configuração da fase atual
phase_model = get_phase_model(spec_dir, "coding", model)
phase_thinking = get_phase_thinking_budget(spec_dir, "coding")
# Criar cliente com configuração específica
client = create_client(
project_dir, spec_dir, phase_model,
agent_type="coder",
max_thinking_tokens=phase_thinking,
)
# Gerar prompt com contexto completo
prompt = generate_subtask_prompt(
spec_dir, project_dir, next_subtask,
attempt_count=recovery_manager.get_attempt_count(subtask_id),
recovery_hints=recovery_manager.get_recovery_hints(subtask_id),
)
# Executar sessão de agente
async with client:
status, response, error_info = await run_agent_session(
client, prompt, spec_dir, verbose
)
# Processar resultado da sessão
if status == "complete":
print_build_complete_banner(spec_dir)
break
elif status == "error":
handle_error(error_info, recovery_manager, status_manager)Sistema de Sessões e Streaming
A função run_agent_session é responsável por uma única interação completa com o Claude, gerenciando toda a comunicação em streaming e processamento de respostas. O sistema usa o Claude Agent SDK para enviar queries e receber respostas em tempo real. Durante o streaming, cada bloco de conteúdo é processado de acordo com seu tipo: TextBlock contém texto gerado que é exibido no terminal e logado para histórico, ToolUseBlock indica qual ferramenta está sendo usada pelo agente, e ToolResultBlock traz o resultado da execução de cada ferramenta.
O sistema implementa logging detalhado através do TaskLogger que persiste toda a atividade em arquivos estruturados para auditoria e debug. Cada chamada de ferramenta é registrada com seu input sanitizado para segurança, resultado da execução, e tempo decorrido. O logger mantém separação entre início e fim de cada ferramenta, permitindo medir duração e identificar gargalos de performance. Erros são classificados por tipo específico para tratamento diferenciado no loop principal.
A sessão retorna um triplo contendo status, texto da resposta e informações de erro quando aplicável. O status pode ser continue indicando que a subtask não está completa e o loop deve continuar, complete indicando que o build inteiro foi finalizado, ou error indicando falha que requer tratamento. O error_info contém detalhes estruturados do erro incluindo tipo classificado, mensagem sanitizada removendo tokens sensíveis, e nome da exceção original. Essa estrutura permite que o loop principal tome decisões informadas sobre retry ou escalação.
async def run_agent_session(
client: ClaudeSDKClient,
message: str,
spec_dir: Path,
verbose: bool = False,
phase: LogPhase = LogPhase.CODING,
) -> tuple[str, str, dict]:
"""Executa uma sessão completa de agente com streaming."""
task_logger = get_task_logger(spec_dir)
try:
# Enviar query inicial
await client.query(message)
response_text = ""
async for msg in client.receive_response():
msg_type = type(msg).__name__
if msg_type == "AssistantMessage":
for block in msg.content:
if type(block).__name__ == "TextBlock":
# Acumular texto da resposta
response_text += block.text
print(block.text, end="", flush=True)
elif type(block).__name__ == "ToolUseBlock":
# Registrar início de uso de ferramenta
tool_name = block.name
task_logger.tool_start(tool_name, phase)
elif msg_type == "UserMessage":
for block in msg.content:
if type(block).__name__ == "ToolResultBlock":
# Registrar resultado da ferramenta
is_error = getattr(block, "is_error", False)
task_logger.tool_end(tool_name, success=not is_error)
# Verificar se build está completo
if is_build_complete(spec_dir):
return "complete", response_text, {}
return "continue", response_text, {}
except Exception as e:
# Classificar e sanitizar erro
error_type = classify_error(e)
sanitized_error = sanitize_error_message(str(e))
return "error", sanitized_error, {
"type": error_type,
"message": sanitized_error,
"exception_type": type(e).__name__,
}Pipeline de Criação de Specs
O SpecOrchestrator coordena todo o processo de criação de especificações com adaptação dinâmica baseada na complexidade detectada da tarefa. Quando uma tarefa é recebida, ela passa por uma sequência de fases que podem variar significativamente dependendo da complexidade. O orquestrador cria o diretório de spec com estrutura padronizada, inicializa validadores para garantir consistência, e executa cada fase em sequência com tratamento de erros e retries automáticos quando necessário.
O fluxo padrão começa com Discovery que faz análise inicial profunda do projeto existente, seguido por Requirements que coleta requisitos de forma interativa quando habilitado. A fase de Complexity Assessment é crucial pois determina quais fases adicionais são necessárias baseado na análise da tarefa. Para tarefas simples classificadas como SIMPLE, apenas quick_spec e validation são executadas. Para tarefas complexas classificadas como COMPLEX, o pipeline completo inclui research, context, spec_writing, self_critique, planning e validation.
Após cada fase, o orquestrador executa compaction que resume a saída da fase em um formato condensado para contexto das fases seguintes. Isso evita que o contexto cresça indefinidamente consumindo tokens desnecessários. Os resumos são formatados como prior_phase_summaries que são injetados no prompt de cada agente subsequente. Ao final do pipeline, um Human Review Checkpoint apresenta a especificação completa para aprovação humana antes de prosseguir para a fase de implementação automática.
class SpecOrchestrator:
"""Orquestra criação de specs com adaptação dinâmica."""
def __init__(
self,
project_dir: Path,
task_description: str | None = None,
model: str = "sonnet",
thinking_level: str = "medium",
complexity_override: str | None = None,
):
self.project_dir = Path(project_dir)
self.task_description = task_description
self.model = model
self.thinking_level = thinking_level
self.complexity_override = complexity_override
# Criar diretório de spec com estrutura padrão
self.specs_dir = get_specs_dir(self.project_dir)
self.spec_dir = create_spec_dir(self.specs_dir)
self.validator = SpecValidator(self.spec_dir)
# Armazenar resumos para compaction
self._phase_summaries: dict[str, str] = {}
async def run(self, interactive: bool = True, auto_approve: bool = False) -> bool:
"""Executa o processo completo de criação de spec."""
task_logger = get_task_logger(self.spec_dir)
task_logger.start_phase(LogPhase.PLANNING, "Iniciando criação de spec")
# FASE 1: DISCOVERY - análise profunda do projeto
result = await self._run_phase("discovery", phase_executor.phase_discovery)
if not result.success:
return False
await self._store_phase_summary("discovery")
# FASE 2: REQUIREMENTS - coleta de requisitos
result = await self._run_phase("requirements",
lambda: phase_executor.phase_requirements(interactive))
await self._store_phase_summary("requirements")
# FASE 3: COMPLEXITY ASSESSMENT - determinar complexidade
result = await self._run_phase("complexity_assessment",
self._phase_complexity_assessment)
# Determinar fases restantes baseado na complexidade
phases_to_run = self.assessment.phases_to_run()
# Executar fases dinâmicas
for phase_name in phases_to_run:
result = await self._run_phase(phase_name, all_phases[phase_name])
if result.success:
await self._store_phase_summary(phase_name)
# CHECKPOINT: Revisão humana antes de implementar
return self._run_review_checkpoint(auto_approve)Avaliação de Complexidade
O módulo de complexity implementa avaliação de complexidade tanto heurística quanto baseada em inteligência artificial, permitindo determinar automaticamente a profundidade de análise necessária para cada tarefa. A complexidade determina quantas fases de análise são necessárias antes da implementação começar. O sistema define três níveis: SIMPLE para tarefas que afetam 1-2 arquivos em um único serviço, STANDARD para tarefas que afetam 3-10 arquivos em 1-2 serviços, e COMPLEX para tarefas que afetam mais de 10 arquivos envolvendo múltiplos serviços e integrações externas.
O ComplexityAnalyzer usa análise de palavras-chave para classificação heurística rápida como primeira linha de avaliação. Palavras-chave simples incluem termos como fix, typo, update e rename que indicam mudanças localizadas. Palavras-chave complexas incluem termos como integrate, api, database, migrate e authentication que indicam mudanças sistêmicas. O sistema também detecta automaticamente integrações externas como Stripe, Auth0 e AWS que aumentam a complexidade, além de mudanças de infraestrutura envolvendo Docker e Kubernetes.
A avaliação por inteligência artificial usa um agente especializado que analisa a descrição da tarefa, requisitos coletados, e contexto do projeto para gerar uma avaliação estruturada mais precisa. O resultado inclui nível de complexidade, pontuação de confiança de 0 a 1, raciocínio explicativo, flags indicando necessidade de research ou self_critique, e lista de fases recomendadas. Se a avaliação por IA falhar por qualquer motivo, o sistema faz fallback automático para a heurística garantindo que o processo nunca trave.
from enum import Enum
from dataclasses import dataclass, field
class Complexity(Enum):
SIMPLE = "simple" # 1-2 arquivos, serviço único
STANDARD = "standard" # 3-10 arquivos, 1-2 serviços
COMPLEX = "complex" # 10+ arquivos, múltiplos serviços
@dataclass
class ComplexityAssessment:
complexity: Complexity
confidence: float # 0.0 a 1.0
reasoning: str
estimated_files: int = 1
estimated_services: int = 1
external_integrations: list = field(default_factory=list)
infrastructure_changes: bool = False
recommended_phases: list = field(default_factory=list)
needs_research: bool = False
needs_self_critique: bool = False
def phases_to_run(self) -> list[str]:
"""Retorna lista de fases baseado na complexidade."""
if self.recommended_phases:
return self.recommended_phases
if self.complexity == Complexity.SIMPLE:
# Pipeline mínimo para tarefas simples
return ["discovery", "quick_spec", "validation"]
elif self.complexity == Complexity.STANDARD:
# Pipeline padrão com fases condicionais
phases = ["discovery", "requirements"]
if self.needs_research:
phases.append("research")
phases.extend(["context", "spec_writing", "planning", "validation"])
return phases
else: # COMPLEX
# Pipeline completo para tarefas complexas
return [
"discovery", "requirements", "research", "context",
"spec_writing", "self_critique", "planning", "validation"
]Loop de Validação QA
O QA Validation Loop é o sistema de auto-validação que garante qualidade do código gerado antes de aprovação final para merge. Após a fase de implementação completar todas as subtasks, o loop executa ciclos de revisão onde um QA Agent analisa as mudanças identificando problemas de código, testes faltantes, e violações de padrões. Se a revisão rejeitar as mudanças, um Fixer Agent aplica correções automaticamente. O ciclo repete até aprovação ou até atingir o limite máximo de 50 iterações configurável.
O sistema rastreia histórico de todas as iterações para detectar issues recorrentes que indicam problemas que o agente não consegue resolver sozinho. Problemas que aparecem em 3 ou mais iterações são automaticamente escalados para revisão humana ao invés de continuar tentando indefinidamente. Cada iteração registra status detalhado incluindo se foi aprovada ou rejeitada, lista de issues encontrados, duração da iteração, e ações tomadas. O método get_recurring_issue_summary analisa este histórico identificando padrões problemáticos.
Para projetos sem framework de testes configurado, o sistema detecta isso automaticamente durante a fase de discovery e gera um Manual Test Plan estruturado com instruções claras para verificação humana. Integrações com plataformas como Linear atualizam o status da tarefa em tempo real: quando QA inicia a tarefa move para status In Review, cada rejeição gera atualização de progresso, e ao final a tarefa move para QA Approved ou Needs Human Intervention conforme o resultado.
MAX_QA_ITERATIONS = 50
MAX_CONSECUTIVE_ERRORS = 3
async def run_qa_validation_loop(
project_dir: Path,
spec_dir: Path,
model: str,
verbose: bool = False,
) -> bool:
"""Loop completo de validação QA com auto-correção."""
# Verificar pré-condições
if not is_build_complete(spec_dir):
print("Build não está completo. QA não pode iniciar.")
return False
if is_qa_approved(spec_dir):
print("Build já foi aprovado pelo QA.")
return True
qa_iteration = get_qa_iteration_count(spec_dir)
consecutive_errors = 0
while qa_iteration < MAX_QA_ITERATIONS:
qa_iteration += 1
# Executar agente revisor de QA
qa_model = get_phase_model(spec_dir, "qa", model)
client = create_client(project_dir, spec_dir, qa_model, agent_type="qa_reviewer")
async with client:
status, response = await run_qa_agent_session(
client, project_dir, spec_dir, qa_iteration
)
if status == "approved":
print("QA APROVADO - Todos os critérios verificados.")
record_iteration(spec_dir, qa_iteration, "approved", [])
return True
elif status == "rejected":
current_issues = get_qa_signoff_status(spec_dir).get("issues_found", [])
# Verificar se há issues recorrentes
history = get_iteration_history(spec_dir)
has_recurring, recurring = has_recurring_issues(current_issues, history)
if has_recurring:
print(f"Issues recorrentes detectados - escalando para humano")
await escalate_to_human(spec_dir, recurring, qa_iteration)
return False
# Executar agente de correção
fix_client = create_client(project_dir, spec_dir, qa_model, agent_type="qa_fixer")
async with fix_client:
await run_qa_fixer_session(fix_client, spec_dir, qa_iteration)
print("Correções aplicadas. Re-executando validação QA...")
print("Máximo de iterações QA atingido sem aprovação.")
return FalseSistema de Merge Inteligente
O MergeOrchestrator coordena o pipeline completo de merge inteligente que combina mudanças de tarefas executadas em worktrees isolados de volta para a branch principal. O sistema primeiro carrega dados de evolução de arquivos incluindo baselines e mudanças por tarefa, analisa semanticamente as alterações entendendo o significado do código, detecta conflitos entre modificações paralelas, aplica merges determinísticos onde possível, e usa inteligência artificial para resolver conflitos ambíguos que requerem julgamento.
O pipeline utiliza componentes especializados que trabalham em conjunto para diferentes aspectos do merge. O SemanticAnalyzer entende o significado das mudanças de código além da comparação textual simples. O ConflictDetector identifica regiões de conflito entre diferentes tarefas que modificaram o mesmo código. O AutoMerger resolve conflitos simples automaticamente usando regras determinísticas quando possível. O AIResolver usa Claude para conflitos complexos que requerem entendimento semântico. O FileEvolutionTracker mantém histórico completo de todas as modificações para contexto.
Para cada arquivo modificado, o sistema decide entre cinco possíveis resultados de merge baseado na análise. DIRECT_COPY copia o arquivo diretamente do worktree quando não há conflitos. AUTO_MERGED indica merge determinístico bem-sucedido sem necessidade de IA. AI_MERGED indica resolução por inteligência artificial para conflitos complexos. NEEDS_HUMAN_REVIEW indica conflito que não pode ser resolvido automaticamente e requer intervenção manual. FAILED indica erro durante o processo de merge. O resultado final é um relatório detalhado com estatísticas completas.
class MergeOrchestrator:
"""Coordena pipeline completo de merge inteligente."""
def __init__(
self,
project_dir: Path,
enable_ai: bool = True,
dry_run: bool = False,
):
self.project_dir = Path(project_dir).resolve()
self.enable_ai = enable_ai
self.dry_run = dry_run
# Inicializar componentes especializados
self.analyzer = SemanticAnalyzer()
self.conflict_detector = ConflictDetector()
self.auto_merger = AutoMerger()
self.evolution_tracker = FileEvolutionTracker(
project_dir=self.project_dir,
semantic_analyzer=self.analyzer,
)
def merge_task(
self,
task_id: str,
worktree_path: Path | None = None,
target_branch: str = "main",
progress_callback: MergeProgressCallback | None = None,
) -> MergeReport:
"""Merge mudanças de uma tarefa específica."""
report = MergeReport(started_at=datetime.now(), tasks_merged=[task_id])
# Encontrar worktree se não fornecido
if worktree_path is None:
worktree_path = find_worktree(self.project_dir, task_id)
# Atualizar dados de evolução do git
self.evolution_tracker.refresh_from_git(task_id, worktree_path, target_branch)
# Obter arquivos modificados pela tarefa
modifications = self.evolution_tracker.get_task_modifications(task_id)
for file_path, snapshot in modifications:
# Processar merge de cada arquivo
result = self._merge_file(file_path, [snapshot], target_branch)
# Tratar cópia direta quando não há conflitos
if result.decision == MergeDecision.DIRECT_COPY:
content, success = self._read_worktree_file_for_direct_copy(
file_path, worktree_path
)
if success:
result.merged_content = content
else:
result.decision = MergeDecision.FAILED
report.file_results[file_path] = result
self._update_stats(report.stats, result)
report.success = report.stats.files_failed == 0
return reportResolução de Conflitos por IA
O AIResolver é o componente especializado que usa Claude para resolver conflitos de código que não podem ser mesclados automaticamente por regras determinísticas. O processo constrói contexto mínimo contendo apenas as mudanças conflitantes de cada tarefa envolvida, formata um prompt específico para operação de merge, chama a inteligência artificial, e parseia o código resultante da resposta. O design prioriza eficiência de tokens para manter custos operacionais baixos enquanto mantém qualidade de resolução.
O processo começa com build_context que extrai apenas as mudanças diretamente relevantes ao conflito de cada snapshot de tarefa, excluindo código não relacionado. O contexto construído inclui o baseline que é o código original antes das modificações, mudanças de cada tarefa envolvida no conflito, descrição textual do conflito identificado, e linguagem de programação do arquivo para formatação correta. Se o contexto exceder o limite configurado de tokens com padrão de 4000, o conflito é automaticamente marcado para revisão humana ao invés de sobrecarregar a IA.
O prompt usa um SYSTEM_PROMPT especializado em operações de merge de código e instruções específicas por linguagem de programação. A resposta da IA é parseada por extract_code_block que busca blocos de código no formato markdown usando delimitadores de código. Para múltiplos conflitos no mesmo arquivo, o sistema pode fazer batch em uma única chamada de IA para eficiência. Estatísticas detalhadas de chamadas e tokens são rastreadas para monitoramento de custos e otimização contínua do sistema.
class AIResolver:
"""Resolve conflitos usando IA com contexto mínimo."""
MAX_CONTEXT_TOKENS = 4000
def __init__(self, ai_call_fn: AICallFunction | None = None):
self.ai_call_fn = ai_call_fn
self._call_count = 0
self._total_tokens = 0
def resolve_conflict(
self,
conflict: ConflictRegion,
baseline_code: str,
task_snapshots: list[TaskSnapshot],
) -> MergeResult:
"""Resolve um conflito específico usando IA."""
if not self.ai_call_fn:
return MergeResult(
decision=MergeDecision.NEEDS_HUMAN_REVIEW,
explanation="Função de IA não configurada",
)
# Construir contexto mínimo para o conflito
context = self.build_context(conflict, baseline_code, task_snapshots)
# Verificar limite de tokens antes de chamar IA
if context.estimated_tokens > self.MAX_CONTEXT_TOKENS:
return MergeResult(
decision=MergeDecision.NEEDS_HUMAN_REVIEW,
explanation=f"Contexto muito grande ({context.estimated_tokens} tokens)",
)
# Formatar prompt específico para merge
prompt = format_merge_prompt(context.to_prompt_context(), context.language)
try:
# Chamar IA com prompt especializado
response = self.ai_call_fn(SYSTEM_PROMPT, prompt)
self._call_count += 1
self._total_tokens += context.estimated_tokens
# Parsear código da resposta
merged_code = extract_code_block(response, context.language)
if merged_code:
return MergeResult(
decision=MergeDecision.AI_MERGED,
merged_content=merged_code,
conflicts_resolved=[conflict],
ai_calls_made=1,
tokens_used=context.estimated_tokens,
)
else:
return MergeResult(
decision=MergeDecision.NEEDS_HUMAN_REVIEW,
explanation="Não foi possível parsear resposta da IA",
)
except Exception as e:
return MergeResult(decision=MergeDecision.FAILED, error=str(e))Sistema de Memória Persistente
O sistema de memória do Auto Claude usa uma abordagem de duas camadas para persistir conhecimento entre sessões, permitindo que agentes aprendam com experiências passadas. A camada primária é o Graphiti, um knowledge graph que permite busca semântica e contexto cross-session com alta precisão. A camada fallback é memória baseada em arquivos JSON que funciona sem dependências externas como bancos de dados. O sistema sempre tenta Graphiti primeiro e faz fallback automático para arquivos se Graphiti não estiver disponível ou configurado.
O MemoryManager gerencia tanto salvamento quanto recuperação de conhecimento entre sessões. Para cada sessão completada com sucesso ou falha, insights são extraídos automaticamente incluindo: subtasks que foram completadas, arquivos que o agente entendeu formando um mapa do codebase, padrões de código descobertos, armadilhas encontradas durante implementação, abordagens que funcionaram bem, abordagens que falharam, e recomendações para sessões futuras. Estes insights são salvos de forma estruturada para consumo em sessões posteriores.
A recuperação de contexto para novas subtasks usa get_graphiti_context que busca conhecimento relevante no graph semântico baseado na descrição da subtask atual. O contexto retornado inclui conhecimento geral do projeto, padrões de código aprendidos em sessões anteriores, armadilhas conhecidas que devem ser evitadas, e insights de sessões recentes relevantes. Isso permite que agentes aprendam continuamente com sessões passadas e evitem repetir erros, criando um loop de aprendizado que melhora a qualidade ao longo do tempo.
async def save_session_memory(
spec_dir: Path,
project_dir: Path,
subtask_id: str,
session_num: int,
success: bool,
subtasks_completed: list[str],
discoveries: dict | None = None,
) -> tuple[bool, str]:
"""Salva insights da sessão na memória persistente."""
# Construir estrutura de insights da sessão
insights = {
"subtasks_completed": subtasks_completed,
"discoveries": discoveries or {
"files_understood": {},
"patterns_found": [],
"gotchas_encountered": [],
},
"what_worked": [f"Implementado: {subtask_id}"] if success else [],
"what_failed": [] if success else [f"Falhou: {subtask_id}"],
"recommendations_for_next_session": [],
}
# PRIMÁRIO: Tentar salvar no Graphiti
if is_graphiti_enabled():
try:
memory = await get_graphiti_memory(spec_dir, project_dir)
if memory and memory.is_enabled:
result = await memory.save_session_insights(session_num, insights)
if result:
return True, "graphiti"
except Exception as e:
logger.warning(f"Falha ao salvar no Graphiti: {e}")
# FALLBACK: Salvar em arquivo JSON
try:
save_file_based_memory(spec_dir, session_num, insights)
return True, "file"
except Exception as e:
return False, "none"
async def get_graphiti_context(
spec_dir: Path,
project_dir: Path,
subtask: dict,
) -> str | None:
"""Recupera contexto relevante do Graphiti para a subtask."""
if not is_graphiti_enabled():
return None
memory = await get_graphiti_memory(spec_dir, project_dir)
# Buscar contexto semântico relevante
query = f"{subtask.get('description', '')} {subtask.get('id', '')}"
context_items = await memory.get_relevant_context(query, num_results=5)
# Buscar padrões e armadilhas específicos
patterns, gotchas = await memory.get_patterns_and_gotchas(query)
# Buscar histórico de sessões recentes
session_history = await memory.get_session_history(limit=3)
# Formatar para inclusão no prompt
return format_memory_context(context_items, patterns, gotchas, session_history)Modelo de Segurança em Três Camadas
O Auto Claude implementa um modelo de segurança em três camadas independentes para proteger o sistema e o ambiente do usuário contra ações maliciosas ou acidentais. A primeira camada é o OS Sandbox onde comandos bash rodam em isolamento do sistema operacional sem acesso direto a recursos críticos. A segunda camada é Filesystem Restrictions que limita operações de arquivo exclusivamente ao diretório do projeto sendo trabalhado. A terceira camada é um Dynamic Command Allowlist que só permite comandos aprovados baseado no stack tecnológico detectado do projeto.
O sistema inclui secret scanning automático que executa antes de cada commit para prevenir vazamento de credenciais. O scanner detecta padrões conhecidos de API keys, tokens de autenticação, e credenciais de banco de dados nos arquivos staged para commit. Se secrets são detectados, o commit é bloqueado imediatamente com instruções detalhadas de como mover os valores sensíveis para variáveis de ambiente. Falsos positivos podem ser configurados via arquivo .secretsignore no repositório para padrões específicos do projeto que são seguros.
Todas as releases oficiais são scaneadas com VirusTotal antes de publicação para garantir ausência de malware, incluem checksums SHA256 para verificação de integridade do download, e são code-signed onde aplicável como no macOS. Mensagens de erro são sanitizadas pela função sanitize_error_message que remove tokens, API keys, e outros dados sensíveis antes de logar ou exibir para o usuário. O sistema também previne command injection validando todos os inputs recebidos de ferramentas e usuários antes de executar comandos.
def sanitize_error_message(error_message: str, max_length: int = 500) -> str:
"""Sanitiza mensagens de erro removendo informações sensíveis."""
if not error_message:
return ""
# Redact API keys no formato sk-...
sanitized = re.sub(
r"\bsk-[a-zA-Z0-9._\-]{20,}\b",
"[CHAVE_API_REMOVIDA]",
error_message
)
# Redact Bearer tokens de autenticação
sanitized = re.sub(
r"\bBearer\s+[a-zA-Z0-9._\-]{20,}\b",
"Bearer [TOKEN_REMOVIDO]",
sanitized
)
# Redact valores de token em parâmetros
sanitized = re.sub(
r"(token[=:]\s*)[a-zA-Z0-9._\-]{20,}\b",
r"\1[TOKEN_REMOVIDO]",
sanitized,
flags=re.IGNORECASE,
)
# Redact senhas em URLs de conexão
sanitized = re.sub(
r"(://[^:]+:)[^@]+(@)",
r"\1[SENHA_REMOVIDA]\2",
sanitized
)
# Truncar ao limite máximo
if len(sanitized) > max_length:
sanitized = sanitized[:max_length] + "..."
return sanitizedIntegrações Externas
O Auto Claude oferece integrações profundas com ferramentas populares de desenvolvimento para sincronização automática de progresso. A integração com Linear sincroniza tarefas automaticamente em ambas as direções: quando um spec é criado no Auto Claude uma task correspondente é criada no Linear, quando QA inicia a task move para status In Review, quando QA aprova ou falha o status é atualizado correspondentemente. Subtasks completadas e falhas são comentadas na task Linear para visibilidade completa do time sobre o progresso.
As integrações com GitHub e GitLab permitem importar issues diretamente como specs para implementação automática, investigar issues com análise de IA para diagnóstico preliminar, criar pull requests ou merge requests automaticamente com descrições geradas, e executar review de PRs com múltiplos agentes especializados. O sistema de PR review usa orquestração paralela onde agentes de segurança, qualidade, lógica e aderência ao codebase analisam simultaneamente para eficiência máxima e cobertura completa.
O LinearTaskState persiste estado da integração no diretório do spec para rastreabilidade. Funções como linear_task_started, linear_subtask_completed, linear_qa_approved atualizam a task Linear via API de forma idempotente. Se Linear não estiver habilitado através da variável LINEAR_API_KEY, a função is_linear_enabled retorna False e todas as operações de integração são silenciosamente ignoradas, permitindo uso standalone sem configuração adicional.
# Interface de integração com Linear
from linear_updater import (
is_linear_enabled,
LinearTaskState,
create_linear_task,
linear_task_started,
linear_subtask_completed,
linear_subtask_failed,
linear_qa_started,
linear_qa_approved,
linear_qa_rejected,
linear_build_complete,
linear_task_stuck,
)
# Exemplo de uso durante o ciclo de build
async def update_linear_progress(spec_dir: Path, subtask_id: str, completed: int, total: int):
"""Atualiza progresso no Linear se habilitado."""
if not is_linear_enabled():
return # Silenciosamente ignora se não configurado
linear_task = LinearTaskState.load(spec_dir)
if not linear_task or not linear_task.task_id:
return
# Notificar início do build na primeira subtask
if completed == 1:
await linear_task_started(spec_dir)
# Atualizar progresso após cada subtask
await linear_subtask_completed(
spec_dir=spec_dir,
subtask_id=subtask_id,
completed_count=completed,
total_count=total,
)
async def handle_stuck_subtask(spec_dir: Path, subtask_id: str, attempts: int):
"""Notifica Linear quando subtask fica travada."""
if is_linear_enabled():
await linear_task_stuck(
spec_dir=spec_dir,
subtask_id=subtask_id,
attempt_count=attempts,
)Frontend Electron
O frontend do Auto Claude é uma aplicação Electron que combina três processos distintos trabalhando em conjunto para fornecer a interface visual completa. O processo principal chamado main gerencia janelas nativas, spawna processos Python do backend, e coordena toda a comunicação entre componentes. O processo renderer é uma Single Page Application React que exibe a interface do usuário com board Kanban, terminais, e painéis de configuração. O processo preload expõe APIs seguras através do contextBridge do Electron para comunicação IPC segura entre renderer e main.
O sistema de stores organiza estado por domínio funcional usando Zustand como biblioteca de gerenciamento de estado. O task-store gerencia tarefas do Kanban com estados e transições. O terminal-store gerencia múltiplos terminais de agente simultâneos. O project-store mantém configuração do projeto atual. O settings-store persiste preferências do usuário. O github-store e gitlab-store gerenciam estado das integrações. Cada store é independente e pode ser persistido via sistema de armazenamento do Electron.
O componente Terminal usa a biblioteca xterm.js para emulação de terminal real com suporte completo a cores ANSI, cursor posicionável, scroll infinito, e seleção de texto. Múltiplos terminais podem rodar em paralelo com suporte a até 12 agent terminals simultâneos para máximo paralelismo. O sistema de IPC handlers no processo main gerencia operações como spawn de agentes Python, leitura de logs em streaming, e controle de processos. Context providers no React fornecem acesso ao estado global para todos os componentes da aplicação.
// Interface do store de tarefas
interface TaskStore {
tasks: Task[];
activeTaskId: string | null;
// Ações para manipular tarefas
createTask: (description: string) => Promise<Task>;
updateTaskStatus: (taskId: string, status: TaskStatus) => void;
deleteTask: (taskId: string) => void;
// Seletores para consultar estado
getTaskById: (taskId: string) => Task | undefined;
getPendingTasks: () => Task[];
getInProgressTasks: () => Task[];
getCompletedTasks: () => Task[];
}
// Interface do store de terminais
interface TerminalStore {
terminals: Map<string, Terminal>;
activeTerminalId: string | null;
// Ações para gerenciar terminais
createTerminal: (taskId: string) => string;
closeTerminal: (terminalId: string) => void;
writeToTerminal: (terminalId: string, data: string) => void;
// Configuração de limite
maxTerminals: 12; // até 12 terminais paralelos
}
// Tipos de status de tarefa
type TaskStatus =
| "inbox" // nova, não atribuída
| "assigned" // atribuída, não iniciada
| "in_progress" // em execução
| "review" // aguardando revisão
| "done" // finalizada
| "blocked"; // travada, requer intervençãoComandos CLI
O backend do Auto Claude oferece uma CLI rica para operação headless sem interface gráfica, ideal para integração com pipelines de CI/CD ou uso via terminal. O entry point run.py aceita comandos para listar specs existentes, executar builds autônomos, revisar mudanças antes de merge, e gerenciar worktrees isolados. O comando mais utilizado é --spec 001 que inicia ou continua o build do spec especificado pelo número. Flags adicionais controlam modo de isolamento, modelo de IA, nível de verbosidade, e número de workers paralelos.
Os comandos principais cobrem todo o ciclo de vida de uma tarefa de desenvolvimento. O comando --list lista todos os specs existentes no projeto com seus status atuais. O comando --spec N --isolated executa o build em worktree isolado que é o modo padrão e seguro. O comando --spec N --direct executa diretamente no repositório para casos onde isolamento não é necessário. O comando --spec N --review mostra mudanças do build para revisão antes de merge. O comando --spec N --merge mescla build completo para a branch principal. O comando --spec N --qa executa apenas o loop de validação QA.
Variáveis de ambiente configuram comportamento global do sistema sem necessidade de modificar código. A variável AUTO_BUILD_MODEL faz override do modelo Claude padrão para todas as operações. As variáveis DEBUG=true e DEBUG_LEVEL=2 habilitam logging detalhado para diagnóstico. A variável LINEAR_API_KEY habilita integração com Linear para sincronização de tarefas. A variável GRAPHITI_ENABLED=true habilita sistema de memória semântica requerendo Neo4j disponível. Essas variáveis podem ser definidas no arquivo .env seguindo o template .env.example fornecido.
# Listar specs disponíveis no projeto
python run.py --list
# Executar spec em modo isolado (padrão, seguro)
python run.py --spec 001 --isolated
# Executar spec diretamente no repositório (usar com cuidado)
python run.py --spec 001 --direct
# Revisar mudanças do build antes de merge
python run.py --spec 001 --review
# Mesclar build completo para branch main
python run.py --spec 001 --merge
# Descartar build e limpar worktree (requer confirmação)
python run.py --spec 001 --discard
# Executar apenas validação QA
python run.py --spec 001 --qa
# Listar worktrees ativos no projeto
python run.py --list-worktrees
# Execução com configuração customizada via variáveis
AUTO_BUILD_MODEL=opus DEBUG=true python run.py --spec 001 --parallel 2Fluxo Completo de uma Tarefa
Uma tarefa no Auto Claude segue um fluxo bem definido de estados que garante qualidade e rastreabilidade em cada etapa. A tarefa começa como DRAFT quando o usuário cria uma descrição no board Kanban da interface. Ao iniciar o processamento, o sistema executa o pipeline de spec que passa por fases de Discovery, Requirements, Complexity Assessment, e fases adicionais baseadas na complexidade detectada até gerar o arquivo implementation_plan.json com o plano estruturado de implementação.
Após aprovação humana do plano de implementação, o Coder Agent assume controle e a tarefa entra em estado BUILDING. O agente itera através de todas as subtasks respeitando dependências definidas entre fases, executando para cada uma o ciclo completo de implementação, self-critique, verificação via comando ou teste, e commit das mudanças. Entre subtasks, o status manager atualiza progresso visível na interface mostrando X de Y subtasks completas para feedback em tempo real ao usuário.
Quando todas as subtasks são completadas com sucesso, a tarefa entra em estado QA_REVIEW onde o QA Loop executa ciclos automáticos de revisão e correção. Se o QA aprovar as mudanças, a tarefa passa para READY_FOR_MERGE aguardando merge com a branch principal. O merge usa o sistema inteligente de resolução de conflitos descrito anteriormente. Finalmente, após merge bem-sucedido a tarefa é marcada como COMPLETE. Em qualquer ponto do fluxo, falhas críticas ou solicitação de intervenção humana podem pausar ou falhar a tarefa movendo para estados especiais.
Fluxo de Estados de uma Tarefa
==============================
DRAFT
│
▼ [Usuário inicia processamento]
DISCOVERY → REQUIREMENTS → COMPLEXITY_ASSESSMENT → [RESEARCH] →
CONTEXT → SPEC_WRITING → [SELF_CRITIQUE] → PLANNING → VALIDATION
│
▼ [Aprovação humana do spec]
BUILDING
│
├─► Iteração 1: Subtask 1.1 → Self-Critique → Verify → Commit
├─► Iteração 2: Subtask 1.2 → Self-Critique → Verify → Commit
├─► ... (respeitando dependências entre fases)
│
▼ [Todas subtasks completas]
QA_REVIEW
│
├─► QA Iteração 1: Review → [Rejeitado] → Fix → Retry
├─► QA Iteração 2: Review → [Rejeitado] → Fix → Retry
├─► QA Iteração N: Review → [Aprovado]
│
▼ [QA aprovado]
READY_FOR_MERGE
│
▼ [Merge automático ou manual]
COMPLETE
Estados de Exceção:
- PAUSED: Intervenção humana solicitada via arquivo PAUSE
- STUCK: Subtask falhou N vezes consecutivas
- FAILED: Erro crítico irrecuperável
- RATE_LIMITED: Aguardando reset de quota de APITipos de Verificação de Subtasks
Cada subtask no arquivo implementation_plan.json deve ter um campo verification que define como provar que a implementação funciona corretamente. O sistema suporta seis tipos de verificação que cobrem diferentes cenários de teste. O tipo command executa um comando CLI e verifica a saída. O tipo api faz requisição HTTP e verifica status code. O tipo browser navega em URL e verifica elementos renderizados. O tipo e2e executa fluxo completo envolvendo múltiplos serviços. O tipo manual documenta instruções para revisão humana. O tipo none indica subtask sem verificação necessária.
A verificação command é a mais comum, executando um comando shell e comparando saída com valor esperado. Essa verificação é útil para testes unitários, verificação de imports de módulo, e validação de configurações. A verificação api faz uma requisição HTTP especificando método, URL, corpo opcional e status code esperado, sendo ideal para testar endpoints backend. A verificação browser usa puppeteer para navegar a uma URL e verificar se elementos específicos estão presentes e renderizados corretamente na página.
A verificação e2e define uma lista de steps para validar fluxo completo que atravessa múltiplos serviços, documentando cada etapa que deve ser verificada. A verificação manual é usada quando automação não é possível ou prática, documentando instruções claras para que um humano possa verificar o resultado. O tipo none é apropriado para subtasks auxiliares como criação de documentação ou configuração que não requerem verificação funcional. A escolha correta do tipo de verificação é fundamental para que o QA loop funcione efetivamente identificando problemas reais.
{
"subtasks": [
{
"id": "subtask-1",
"description": "Criar modelo de dados",
"verification": {
"type": "command",
"command": "pytest tests/unit/test_models.py -v",
"expected": "passed"
}
},
{
"id": "subtask-2",
"description": "Criar endpoint de API",
"verification": {
"type": "api",
"method": "POST",
"url": "http://localhost:8000/api/users",
"body": {"name": "Usuario Teste"},
"expected_status": 201
}
},
{
"id": "subtask-3",
"description": "Criar componente de UI",
"verification": {
"type": "browser",
"url": "http://localhost:3000/dashboard",
"checks": ["Dashboard renderiza", "Sem erros no console", "Dados carregam"]
}
},
{
"id": "subtask-4",
"description": "Integrar fluxo completo",
"verification": {
"type": "e2e",
"steps": [
"Submeter formulário no frontend",
"Verificar backend recebe requisição",
"Verificar banco de dados atualizado",
"Verificar UI mostra mensagem de sucesso"
]
}
},
{
"id": "subtask-5",
"description": "Escrever documentação",
"verification": {
"type": "manual",
"instructions": "Revisar documentação gerada para precisão técnica"
}
}
]
}Recovery Manager
O RecoveryManager é responsável por rastrear tentativas de execução de subtasks, gerenciar pontos de rollback seguro, e identificar subtasks travadas que precisam de intervenção humana para continuar. Cada tentativa de execução é registrada com timestamp preciso, número da sessão, resultado de sucesso ou falha, abordagem utilizada, e mensagem de erro quando aplicável. Este histórico detalhado permite retry inteligente com contexto completo das tentativas anteriores.
O sistema mantém uma lista de good commits que são commits que passaram verificação com sucesso e podem ser usados como ponto de rollback seguro. Quando uma subtask falha após múltiplas tentativas, o RecoveryManager pode reverter o repositório para o último commit bom antes de tentar uma abordagem completamente diferente. Isso evita acumulação de código quebrado que poderia confundir tentativas subsequentes e garante que o projeto sempre pode voltar a um estado funcional conhecido.
Após três tentativas falhas consecutivas em uma mesma subtask, ela é automaticamente marcada como stuck com uma razão descritiva do problema identificado. Subtasks stuck aparecem destacadas no resumo final do build e são notificadas via integração Linear se configurada. O método get_recovery_hints retorna dicas baseadas em tentativas anteriores que são injetadas no prompt do agente para informar a próxima tentativa sobre o que já foi tentado e falhou, evitando repetição de abordagens que não funcionaram.
class RecoveryManager:
"""Gerencia recuperação de falhas e tracking de tentativas."""
def __init__(self, spec_dir: Path, project_dir: Path):
self.spec_dir = spec_dir
self.project_dir = project_dir
self._load_state()
def record_attempt(
self,
subtask_id: str,
session: int,
success: bool,
approach: str,
error: str | None = None,
) -> None:
"""Registra uma tentativa de execução de subtask."""
attempt = {
"timestamp": datetime.now().isoformat(),
"session": session,
"success": success,
"approach": approach,
"error": error,
}
self._attempts[subtask_id].append(attempt)
self._save_state()
def get_attempt_count(self, subtask_id: str) -> int:
"""Retorna número de tentativas para uma subtask."""
return len(self._attempts.get(subtask_id, []))
def record_good_commit(self, commit_hash: str, subtask_id: str) -> None:
"""Registra commit verificado como ponto de rollback seguro."""
self._good_commits.append({
"hash": commit_hash,
"subtask_id": subtask_id,
"timestamp": datetime.now().isoformat(),
})
self._save_state()
def get_recovery_hints(self, subtask_id: str) -> list[str]:
"""Retorna dicas baseadas em tentativas anteriores."""
attempts = self._attempts.get(subtask_id, [])
hints = []
for attempt in attempts:
if not attempt["success"] and attempt.get("error"):
hints.append(f"Tentativa falhou com: {attempt['error']}")
return hints
def mark_subtask_stuck(self, subtask_id: str, reason: str) -> None:
"""Marca subtask como travada necessitando intervenção."""
self._stuck_subtasks[subtask_id] = {
"reason": reason,
"timestamp": datetime.now().isoformat(),
"attempts": self.get_attempt_count(subtask_id),
}
self._save_state()
def rollback_to_good_commit(self) -> bool:
"""Reverte para último commit bom conhecido."""
if not self._good_commits:
return False
last_good = self._good_commits[-1]
subprocess.run(["git", "reset", "--hard", last_good["hash"]], check=True)
return TrueTask Logger
O TaskLogger persiste toda a atividade de uma tarefa em arquivos estruturados para auditoria completa, debug de problemas, e replay de sessões. Cada fase de execução como PLANNING, CODING e VALIDATION tem seu próprio arquivo de log separado. Entries de log incluem timestamp preciso, tipo de entry como TEXT, TOOL_START, TOOL_END ou ERROR, fase atual de execução, número da sessão, e identificador da subtask. Esta estrutura permite reconstruir exatamente o que aconteceu em cada sessão com total fidelidade.
Para ferramentas utilizadas pelo agente, o logger registra separadamente tool_start contendo nome da ferramenta e input formatado, e tool_end contendo resultado de sucesso ou falha, output da ferramenta, e detalhes adicionais. Esta separação permite medir tempo de execução de cada ferramenta e identificar gargalos de performance. Results muito grandes acima de 50KB são truncados no log principal mas mantidos em campo detail separado para expansão manual quando necessário. Ferramentas bloqueadas por security hooks são marcadas como BLOCKED.
O formato de log suporta visualização na interface Electron que mostra progresso em tempo real com status visual de ferramentas: ícone girando enquanto executa, checkmark verde ao completar com sucesso, X vermelho ao falhar. O log completo pode ser exportado para análise externa e é extremamente útil para reportar bugs ou entender comportamento inesperado do agente. Desenvolvedores podem usar os logs para identificar padrões de falha e melhorar os prompts dos agentes continuamente.
from enum import Enum
class LogEntryType(Enum):
TEXT = "text" # texto livre
TOOL_START = "tool_start" # início de ferramenta
TOOL_END = "tool_end" # fim de ferramenta
ERROR = "error" # erro
INFO = "info" # informação
class LogPhase(Enum):
PLANNING = "planning" # fase de planejamento
CODING = "coding" # fase de codificação
VALIDATION = "validation" # fase de validação
class TaskLogger:
"""Logger persistente para atividade de tarefas."""
def __init__(self, spec_dir: Path):
self.spec_dir = spec_dir
self._current_phase = None
self._current_session = None
self._current_subtask = None
def start_phase(self, phase: LogPhase, message: str) -> None:
"""Inicia uma nova fase de logging."""
self._current_phase = phase
self._write_entry(LogEntryType.INFO, f"=== {phase.value.upper()} INICIADO: {message} ===")
def end_phase(self, phase: LogPhase, success: bool, message: str) -> None:
"""Finaliza uma fase de logging."""
status = "SUCESSO" if success else "FALHA"
self._write_entry(LogEntryType.INFO, f"=== {phase.value.upper()} {status}: {message} ===")
def tool_start(self, tool_name: str, input_display: str | None,
phase: LogPhase, print_to_console: bool = True) -> None:
"""Registra início de uso de ferramenta."""
self._write_entry(LogEntryType.TOOL_START, f"[{tool_name}] Iniciando...")
if input_display and print_to_console:
print(f" → {tool_name}: {input_display[:100]}...")
def tool_end(self, tool_name: str, success: bool,
result: str | None = None, detail: str | None = None,
phase: LogPhase | None = None) -> None:
"""Registra fim de uso de ferramenta."""
status = "OK" if success else "ERRO"
self._write_entry(LogEntryType.TOOL_END, f"[{tool_name}] {status}")
def log_error(self, message: str, phase: LogPhase) -> None:
"""Loga um erro com destaque."""
self._write_entry(LogEntryType.ERROR, f"ERRO: {message}")Git Worktrees para Isolamento
O Auto Claude utiliza git worktrees como mecanismo fundamental de isolamento para garantir que mudanças experimentais nunca afetem a branch principal do projeto. Um worktree é uma funcionalidade nativa do Git que permite ter múltiplas working directories ligadas ao mesmo repositório, cada uma em uma branch diferente. Quando uma tarefa inicia em modo isolado, o sistema cria um worktree dedicado em um diretório separado onde todas as mudanças acontecem de forma completamente independente do diretório principal.
A criação de worktree acontece automaticamente quando o build inicia, usando o comando git worktree add com uma branch nova criada especificamente para a tarefa. O nome da branch segue um padrão que inclui o identificador do spec para rastreabilidade. Todas as operações do agente como leitura de arquivos, escrita de código, e execução de comandos acontecem dentro do worktree isolado. O agente não tem acesso ao diretório principal durante a execução, prevenindo modificações acidentais.
Após o build completar e passar pelo QA loop com aprovação, as mudanças podem ser mescladas de volta para a branch principal através do sistema de merge inteligente. Se o build for descartado por qualquer razão, o worktree é simplesmente removido com git worktree remove e a branch deletada, deixando o repositório principal completamente intocado. Esta arquitetura permite experimentação segura onde builds podem falhar repetidamente sem risco algum para o código existente.
# Criar worktree isolado para uma tarefa
git worktree add ../projeto-spec-001 -b auto-claude/spec-001
# Estrutura resultante no sistema de arquivos
/home/usuario/projeto/ # repositório principal (intocado)
/home/usuario/projeto-spec-001/ # worktree isolado para a tarefa
# Listar worktrees ativos
git worktree list
# /home/usuario/projeto abc1234 [main]
# /home/usuario/projeto-spec-001 def5678 [auto-claude/spec-001]
# Após build completo e aprovado, merge das mudanças
cd /home/usuario/projeto
git merge auto-claude/spec-001
# Ou se build for descartado, remover worktree
git worktree remove ../projeto-spec-001
git branch -D auto-claude/spec-001Self-Critique Obrigatório
O prompt do Coder Agent inclui uma seção obrigatória de Self-Critique que deve ser executada antes de marcar qualquer subtask como completa. Esta auto-revisão força o agente a pausar e avaliar criticamente seu próprio trabalho usando um checklist estruturado. O objetivo é capturar problemas óbvios antes que cheguem ao QA loop, reduzindo iterações desnecessárias e melhorando qualidade geral do código gerado.
O checklist de self-critique cobre múltiplas dimensões de qualidade do código implementado. Pattern Adherence verifica se o código segue exatamente os padrões encontrados em arquivos de referência e se convenções de nomenclatura são consistentes com o codebase existente. Error Handling verifica se casos de erro são tratados apropriadamente. Code Cleanliness verifica ausência de console.log ou print statements de debug e código comentado esquecido. Requirements Met verifica se todos os requisitos da subtask foram atendidos.
O resultado do self-critique é um veredito binário de PROCEED: YES ou PROCEED: NO. Se issues forem encontrados durante a auto-revisão, o agente deve corrigi-los imediatamente antes de prosseguir, não deferindo para depois. Somente após passar por todos os itens do checklist com sucesso o agente pode marcar a subtask como completa e fazer commit. Esta disciplina estruturada melhora significativamente a taxa de aprovação no primeiro QA review.
## STEP 6.5: SELF-CRITIQUE OBRIGATÓRIO
ANTES de marcar subtask como completa, executar checklist:
**Pattern Adherence:**
- [ ] Segue padrões dos arquivos de referência exatamente
- [ ] Nomenclatura de variáveis consistente com codebase
**Error Handling:**
- [ ] Casos de erro tratados apropriadamente
- [ ] Mensagens de erro são claras e úteis
**Code Cleanliness:**
- [ ] Sem console.log/print de debug
- [ ] Sem blocos de código comentados
- [ ] Imports organizados e sem duplicatas
**Requirements:**
- [ ] Todos os requisitos da subtask atendidos
- [ ] Arquivos especificados foram criados/modificados
**Veredito:** PROCEED: [SIM/NÃO]
Se NÃO, corrigir issues IMEDIATAMENTE antes de prosseguir.
Não deferir correções para depois.Requisitos e Instalação
O Auto Claude requer alguns componentes instalados no sistema para funcionar corretamente. O requisito principal é uma assinatura Claude Pro ou Claude Max da Anthropic que fornece acesso às APIs necessárias. O Claude Code CLI deve ser instalado globalmente via npm com o comando npm install -g @anthropic-ai/claude-code pois é a ponte de comunicação entre o Auto Claude e os modelos da Anthropic. O projeto alvo deve ser inicializado como repositório git pois o sistema depende de funcionalidades git como worktrees e commits.
Para o backend Python, a versão mínima requerida é Python 3.10 ou superior devido ao uso de features modernas da linguagem como union types e match statements. Dependências Python são gerenciadas via arquivo pyproject.toml e podem ser instaladas com pip ou gerenciadores como uv. Para integrações opcionais, a variável LINEAR_API_KEY habilita sincronização com Linear, e GRAPHITI_ENABLED=true habilita memória semântica requerendo instância Neo4j disponível.
A instalação do aplicativo desktop é simples: basta baixar o instalador apropriado para a plataforma de github.com/AndyMik90/Auto-Claude/releases, executar o instalador, e seguir o wizard de configuração. No primeiro uso, o aplicativo guia através do processo de autenticação OAuth com a Anthropic. Releases incluem checksums SHA256 para verificação de integridade e scans VirusTotal para garantia de segurança. Plataformas suportadas incluem Windows, macOS Intel e Apple Silicon, e Linux via AppImage, Debian ou Flatpak.
Conclusão
O Auto Claude representa um avanço significativo na automação do desenvolvimento de software, oferecendo um sistema completo que vai muito além de simples assistentes de código. A arquitetura multi-agente com Planner, Coder e QA trabalhando em conjunto permite que tarefas complexas sejam decompostas, implementadas e validadas de forma autônoma. O sistema de fases com configuração dinâmica de modelo e thinking level otimiza custo e qualidade para cada etapa do processo. O uso de git worktrees garante segurança total durante experimentação.
A integração profunda entre componentes cria um fluxo de trabalho coeso onde specs informam agentes, agentes geram código verificável, QA valida automaticamente, e merge resolve conflitos inteligentemente. O sistema de memória persistente permite aprendizado cross-session onde padrões descobertos e armadilhas encontradas em uma sessão informam sessões futuras. Integrações com Linear, GitHub e GitLab conectam o sistema ao workflow real de equipes de desenvolvimento, mantendo visibilidade e rastreabilidade.
Para equipes e desenvolvedores individuais, o Auto Claude oferece aumento significativo de produtividade permitindo descrever o que se deseja e deixar o sistema implementar autonomamente. O modelo de execução em fases com checkpoints humanos mantém controle enquanto automatiza o trabalho tedioso de implementação e testes. Com suporte a até 12 terminais paralelos, projetos grandes podem ser construídos em fração do tempo que levaria manualmente. O Auto Claude não substitui desenvolvedores mas os amplifica, permitindo foco em decisões de alto nível enquanto a execução acontece automaticamente.