Aider .aider.conf.yml

DESIGN.md + Aider

Referência de configuração: read: DESIGN.md

Por que Aider + DESIGN.md funciona bem

O Aider tem uma filosofia diferente de outras ferramentas:

  1. Controle explícito de contexto — você decide exatamente quais arquivos o modelo vê. Nada de “workspace mágico” que pode ou não incluir seu arquivo. /add DESIGN.md = garantia de leitura.

  2. Conventions files — arquivos lidos automaticamente em toda sessão, sem precisar re-adicionar. Perfeito para regras de design system.

  3. Diff-based editing — o Aider mostra exatamente o que mudou. Você vê se ele usou a cor certa ou inventou uma nova.

  4. Git-aware — cada edição pode virar um commit. Fácil reverter se o agente desviou do design system.

Para o dev que quer precisão e controle, o Aider com DESIGN.md é a combinação que entrega ambos.

Passo a Passo de Configuração

1. Instalar o Aider

pip install aider-chat
# ou
pipx install aider-chat

Configure a API key:

export ANTHROPIC_API_KEY="sk-..."
# ou
export OPENAI_API_KEY="sk-..."

2. Colocar o DESIGN.md na raiz

meu-projeto/
├── DESIGN.md
├── .aider.conf.yml
├── CONVENTIONS.md
├── src/
└── ...

3. Configurar o .aider.conf.yml

O Aider lê configurações de .aider.conf.yml na raiz. Use-o para carregar o DESIGN.md automaticamente:

# .aider.conf.yml

# Adiciona DESIGN.md como read-only em toda sessão
read:
  - DESIGN.md
  - CONVENTIONS.md

# Modelo preferido (ajuste conforme sua API key)
model: claude-sonnet-4-20250514

# Auto-commit desativado para review manual do visual
auto-commits: false

# Não enviar automaticamente ao git
auto-lint: true

O campo read é a chave. Arquivos listados ali são adicionados ao contexto como read-only em TODA sessão do Aider. Você não precisa lembrar de dar /add — o DESIGN.md já está lá.

4. Criar o CONVENTIONS.md

O Aider suporta um arquivo de convenções que funciona como instruções persistentes. Crie na raiz:

# CONVENTIONS.md

## Design System

Este projeto usa DESIGN.md como source of truth para decisões visuais.

### Regras obrigatórias para geração de UI

1. Antes de gerar qualquer componente visual, leia o DESIGN.md
2. Use APENAS cores definidas no front matter do DESIGN.md
3. Siga a escala tipográfica exata (sem tamanhos intermediários)
4. Espaçamentos devem ser múltiplos do valor base
5. Componentes devem ter estados: default, hover, focus, disabled
6. Respeite TODAS as restrições da seção "Restrições"

### Convenções de código para componentes

- TypeScript strict para interfaces de props
- Named exports (não default exports)
- Um componente por arquivo
- Arquivo nomeado como o componente (PascalCase)
- Styles colocated no mesmo arquivo (CSS Modules ou Tailwind)

### Quando não houver definição no DESIGN.md

- Inferir a partir dos padrões existentes
- Escolher a opção mais conservadora/consistente
- Mencionar na resposta que a decisão foi inferida

5. Iniciar o Aider com o contexto correto

cd meu-projeto
aider

Se configurou o .aider.conf.yml, o DESIGN.md já está no contexto. Verifique:

/tokens

Esse comando mostra o uso de tokens da sessão. O DESIGN.md deve aparecer na lista de read-only files.

Se preferir controle manual (sem .aider.conf.yml):

aider --read DESIGN.md --read CONVENTIONS.md

Exemplo Concreto de Uso

Sessão no terminal:

$ aider

Aider v0.82.0
Model: claude-sonnet-4-20250514
Read-only files: DESIGN.md, CONVENTIONS.md
───────────────────────────────────

> Crie um componente de newsletter signup: input de email + botão submit. Versão
> desktop lado a lado, mobile empilhado. Use os tokens do DESIGN.md.

O Aider responde e edita o arquivo:

// src/components/NewsletterSignup.tsx
interface NewsletterSignupProps {
  onSubmit: (email: string) => void;
  loading?: boolean;
  placeholder?: string;
  buttonText?: string;
}

export function NewsletterSignup({
  onSubmit,
  loading = false,
  placeholder = "Seu melhor email",
  buttonText = "Inscrever-se",
}: NewsletterSignupProps) {
  const [email, setEmail] = useState("");

  const handleSubmit = (e: FormEvent) => {
    e.preventDefault();
    if (email.trim()) onSubmit(email);
  };

  return (
    <form
      onSubmit={handleSubmit}
      className="flex flex-col sm:flex-row gap-3"
    >
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder={placeholder}
        required
        className="
          flex-1 px-4 py-3
          border border-[#5F6368]/30 rounded-lg
          text-sm text-[#202124]
          placeholder:text-[#5F6368]
          focus:border-[#1A73E8] focus:ring-1 focus:ring-[#1A73E8]
          outline-none transition-colors
        "
      />
      <button
        type="submit"
        disabled={loading}
        className="
          px-6 py-3
          bg-[#1A73E8] text-white text-sm font-medium
          rounded-lg
          hover:bg-[#1557B0]
          focus:ring-2 focus:ring-offset-2 focus:ring-[#1A73E8]
          disabled:opacity-50
          transition-colors whitespace-nowrap
        "
      >
        {loading ? "Enviando..." : buttonText}
      </button>
    </form>
  );
}

O diff mostra claramente o que foi criado. Cores do DESIGN.md: #1A73E8 (primary), #202124 (text-primary), #5F6368 (text-secondary). Espaçamento em múltiplos de 4/8. Border-radius rounded-lg (medium: 8). Estados hover, focus, disabled presentes.

Para aplicar:

> /commit Adiciona componente NewsletterSignup seguindo DESIGN.md

Dicas Específicas do Aider

/add para componentes relacionados

Quando pedir para criar um componente que deve se integrar com outros, adicione os existentes ao contexto:

/add src/components/Button.tsx src/components/Card.tsx

Agora o Aider vê como os outros componentes usam os tokens e mantém consistência. Isso é mais efetivo que só o DESIGN.md — ele copia o padrão real de implementação.

/architect para planejamento visual

Use o modo architect antes de gerar código complexo:

/architect

> Preciso de uma landing page com hero, features grid, testimonials e CTA.
> Planeje a estrutura de componentes seguindo o DESIGN.md antes de implementar.

O modo architect planeja sem editar arquivos. Depois você confirma e ele implementa.

/read-only vs /add

  • /read-only DESIGN.md — o modelo lê mas não edita. Perfeito para design system.
  • /add DESIGN.md — o modelo pode ler E editar. Útil se quer que ele atualize o DESIGN.md com novos tokens.

Para design system como referência, sempre use read-only.

Lint conventions

No .aider.conf.yml, ative o lint automático:

lint-cmd: "npx eslint --fix"
auto-lint: true

Isso garante que o código gerado passa pelo linter antes do commit. Se o linter tem regras de estilo (Tailwind sort, etc.), o código já sai formatado.

Múltiplos arquivos de conventions

O Aider aceita vários arquivos read-only. Separe por responsabilidade:

read:
  - DESIGN.md           # Tokens visuais
  - CONVENTIONS.md      # Regras de código
  - ARCHITECTURE.md     # Estrutura do projeto

Cada arquivo foca em um aspecto. O DESIGN.md fica conciso, sem poluir com regras de código.

Use /diff para auditar

Depois de gerar um componente, use:

/diff

Revise se as cores hardcoded correspondem ao DESIGN.md. Se vir #3B82F6 (Tailwind default) em vez de #1A73E8 (seu primary), corrija imediatamente:

> A cor do botão está errada. Deve ser #1A73E8 (primary do DESIGN.md), não #3B82F6.

.env para API keys permanentes

Crie um .env na raiz:

ANTHROPIC_API_KEY=sk-ant-...

E no .aider.conf.yml:

env-file: .env

Nunca commite o .env. Adicione ao .gitignore.

Troubleshooting e Gotchas

O Aider não lê o .aider.conf.yml

Verifique:

  • O arquivo está na raiz do projeto (onde você roda aider)
  • O nome é exatamente .aider.conf.yml (não .yaml, não .aider.yml)
  • A indentação YAML está correta (use espaços, não tabs)
  • Teste com aider --verbose para ver quais configs foram carregadas

DESIGN.md muito grande — contexto estourado

O Aider mostra uso de tokens com /tokens. Se o DESIGN.md está consumindo muito:

  1. Encurte a prosa — tokens YAML são mais concisos que texto
  2. Remova exemplos de código do DESIGN.md (mantenha só tokens + rationale)
  3. Use um DESIGN.md “light” para o Aider e o completo para humanos:
read:
  - DESIGN-TOKENS.md   # Versão compacta só com tokens

O Aider gera CSS vanilla em vez de Tailwind

Se seu projeto usa Tailwind mas o Aider insiste em CSS puro, adicione ao CONVENTIONS.md:

## Framework CSS: Tailwind CSS

- Usar APENAS classes Tailwind (utility-first)
- Cores customizadas estão em tailwind.config.js
- Quando o token do DESIGN.md é `primary: #1A73E8`, usar a classe `text-primary` ou `bg-primary`
- Nunca usar inline styles
- Nunca usar CSS separado para componentes

O modelo não respeita as restrições

Se o modelo ignora a seção “Restrições” do DESIGN.md (usa gradientes proibidos, por exemplo):

  1. Mova as restrições para o TOPO do CONVENTIONS.md (lido primeiro)
  2. Seja mais enfático:
## PROIBIÇÕES ABSOLUTAS (violar = rejeição do código)

- ❌ NUNCA usar gradientes em backgrounds
- ❌ NUNCA usar sombras maiores que shadow-md
- ❌ NUNCA usar mais de 2 font-weights por componente
- ❌ NUNCA usar cores fora da paleta do DESIGN.md
  1. Reforce no prompt: “Lembre das restrições do design system antes de responder”

Conflito entre DESIGN.md e código existente

Se o projeto já tem componentes com cores erradas, o Aider pode copiar o padrão errado. Resolva:

> Os componentes existentes estão desatualizados. Para novos componentes, ignore os
> padrões dos arquivos existentes e siga APENAS o DESIGN.md. Use as cores e espaçamentos
> definidos lá, mesmo que difiram do código atual.

Sessão longa perde contexto

Em sessões muito longas, o Aider pode “esquecer” o DESIGN.md. Solução:

/clear

Limpa o histórico e recarrega os read-only files. O DESIGN.md volta ao topo do contexto.

Workflow de Desenvolvimento com Aider + DESIGN.md

# 1. Iniciar sessão
cd meu-projeto
aider

# 2. Verificar contexto
/tokens
# → DESIGN.md (read-only), CONVENTIONS.md (read-only)

# 3. Adicionar arquivos relevantes para edição
/add src/components/Button.tsx src/pages/Home.tsx

# 4. Pedir geração seguindo o design system
> Crie um componente Hero com headline, subtext e CTA button.
> Seguir DESIGN.md para cores e espaçamento.

# 5. Revisar o diff
/diff

# 6. Se aprovado, commitar
/commit feat: adiciona Hero component seguindo design system

# 7. Próximo componente...

Conclusão e Próximo Passo

O Aider com DESIGN.md é a abordagem minimalista que funciona. Sem plugins, sem extensões, sem configuração complexa. Um arquivo YAML de configuração, um arquivo de convenções e o DESIGN.md na raiz. Terminal, IA e design system integrados.

O ponto forte é o controle: você sabe exatamente o que o modelo está lendo. Não há mágica de “workspace indexing” que pode falhar silenciosamente. Se o DESIGN.md está no read, ele está no contexto. Ponto.

Para quem já usa Aider e quer elevar a qualidade visual do código gerado, o setup leva 5 minutos. Para quem vem de IDEs e quer experimentar, o Aider com DESIGN.md é uma porta de entrada honesta: resultado rápido com controle total.

Próximos passos:

Links úteis