AGENTS.md DESIGN.md + Codex
Referência de configuração: Include do DESIGN.md
Por que Codex CLI + DESIGN.md é poderoso
O Codex CLI tem três modos de operação:
- suggest — sugere e espera aprovação (como Copilot no terminal)
- auto-edit — edita arquivos mas pede OK para comandos
- full-auto — faz tudo sozinho, sem interrupção
No modo full-auto, o DESIGN.md é a única salvaguarda visual. Sem ele, o agente vai na criatividade do modelo. Com ele, cada edição respeita o design system — mesmo que você não esteja olhando.
Outras vantagens:
- AGENTS.md nativo — o Codex CLI lê esse arquivo por design. É o mecanismo oficial de instruções.
- Sandbox — executa em ambiente isolado. Você pode deixar ele gerar 10 componentes e revisar depois.
- Git-aware — faz commits granulares. Fácil reverter um componente que desviou.
- Contexto de repositório — ele vê toda a estrutura. Sabe onde ficam componentes, estilos, configs.
Passo a Passo de Configuração
1. Instalar o Codex CLI
npm install -g @openai/codexConfigure a API key:
export OPENAI_API_KEY="sk-..."Ou no arquivo de configuração ~/.codex/config.yaml:
model: o4-mini
api_key_env: OPENAI_API_KEY2. Estrutura do projeto
meu-projeto/
├── DESIGN.md ← Design tokens + rationale
├── AGENTS.md ← Instruções para o Codex CLI
├── CODEX.md ← Instruções específicas Codex (alternativa)
├── src/
│ └── components/
├── package.json
└── ...3. Criar o AGENTS.md
O AGENTS.md é o arquivo que o Codex CLI lê automaticamente em toda execução. É o equivalente do .clinerules para o Cline, mas com nome padronizado pelo ecossistema OpenAI.
# AGENTS.md
## Design System
Este projeto usa o formato DESIGN.md para definir regras visuais.
O arquivo DESIGN.md na raiz é a source of truth para todas as decisões de UI.
### Instruções obrigatórias para UI
1. ANTES de gerar qualquer componente visual, leia o DESIGN.md completo
2. Use EXCLUSIVAMENTE os tokens definidos no YAML front matter
3. Siga a escala tipográfica sem inventar tamanhos intermediários
4. Espaçamentos devem ser múltiplos do valor base
5. Todo elemento interativo precisa de: hover, focus, disabled
6. A seção "Restrições" do DESIGN.md é inviolável
### Tokens rápidos (resumo do DESIGN.md)
Para referência rápida quando o contexto é limitado:
- Primary: #1A73E8
- Secondary: #34A853
- Background: #F8F9FA
- Surface: #FFFFFF
- Text Primary: #202124
- Text Secondary: #5F6368
- Error: #D93025
- Font: Inter
- Base spacing: 8px
- Border radius: 4/8/16/9999px
### Convenções de código
- TypeScript strict
- React functional components com named exports
- Tailwind CSS utility-first
- Um componente por arquivo
- Interface de Props explícita
### Arquivos que NÃO devem ser editados
- DESIGN.md (read-only, source of truth)
- AGENTS.md (este arquivo)
- package-lock.json (gerenciado por npm)4. DESIGN.md como referência
O DESIGN.md deve estar conciso para o Codex CLI. O agente opera com budget de tokens limitado no sandbox. Priorize:
colors:
primary: "#1A73E8"
secondary: "#34A853"
surface: "#FFFFFF"
background: "#F8F9FA"
text-primary: "#202124"
text-secondary: "#5F6368"
error: "#D93025"
warning: "#F9AB00"
success: "#34A853"
typography:
font-family: "Inter, system-ui, sans-serif"
scale: [12, 14, 16, 20, 24, 32, 40, 48]
weight-regular: 400
weight-medium: 500
weight-bold: 700
line-height-body: 1.6
line-height-heading: 1.2
spacing:
base: 8
scale: [4, 8, 12, 16, 24, 32, 48, 64]
radius:
sm: 4
md: 8
lg: 16
full: 9999
shadows:
sm: "0 1px 2px rgba(0,0,0,0.05)"
md: "0 4px 6px rgba(0,0,0,0.07)"
lg: "0 10px 15px rgba(0,0,0,0.1)"
# Design System
Interface limpa e funcional. Hierarquia por tipografia. Cor reservada para ações.
## Componentes
### Botão Primary
- Background: primary, text: white, radius: md, padding: 12px 24px
- Hover: darken 10%, Focus: ring 2px primary, Disabled: opacity 50%
### Botão Secondary
- Background: transparent, border: 1px primary, text: primary
- Hover: background primary/5%, Focus: ring 2px primary
### Card
- Background: surface, radius: lg, padding: 24px, shadow: sm
- Hover: shadow md (transition 200ms)
### Input
- Border: 1px text-secondary/30%, radius: md, padding: 12px 16px
- Focus: border primary, ring 1px primary
- Error: border error, text error abaixo
## Restrições
- Sem gradientes
- Máximo 2 font-weights por componente
- Ícones: stroke only, 1.5px
- Sem text-decoration além de links
- Sem opacity para criar cores (usar tokens)5. Executar o Codex CLI
# Modo interativo (sugere e espera)
codex "Crie um componente de user profile card com avatar, nome, role e botão de follow"
# Modo auto-edit (edita arquivos, pede OK para comandos)
codex --mode auto-edit "Crie os componentes de uma landing page: Hero, Features, Testimonials, CTA"
# Modo full-auto (sandbox completo)
codex --mode full-auto "Implemente todos os componentes base do design system definido em DESIGN.md"Exemplo Concreto de Uso
codex --mode auto-edit "Crie um componente Navbar responsiva com: logo à esquerda,
links de navegação centralizados, botão de login à direita. Mobile: hamburger menu.
Seguir estritamente o DESIGN.md."O Codex CLI lê o AGENTS.md, vê a instrução de ler DESIGN.md, extrai tokens e gera:
// src/components/Navbar.tsx
import { useState } from 'react';
import { Menu, X } from 'lucide-react';
interface NavLink {
label: string;
href: string;
}
interface NavbarProps {
logo: React.ReactNode;
links: NavLink[];
onLogin: () => void;
}
export function Navbar({ logo, links, onLogin }: NavbarProps) {
const [mobileOpen, setMobileOpen] = useState(false);
return (
<nav className="bg-white border-b border-[#5F6368]/10">
<div className="max-w-7xl mx-auto px-6 h-16 flex items-center justify-between">
{/* Logo */}
<div className="flex-shrink-0">
{logo}
</div>
{/* Desktop links */}
<div className="hidden md:flex items-center gap-8">
{links.map((link) => (
<a
key={link.href}
href={link.href}
className="text-sm text-[#5F6368] hover:text-[#202124] transition-colors"
>
{link.label}
</a>
))}
</div>
{/* Login button */}
<div className="hidden md:block">
<button
onClick={onLogin}
className="
px-4 py-2 text-sm font-medium
bg-[#1A73E8] text-white rounded-lg
hover:bg-[#1557B0]
focus:ring-2 focus:ring-offset-2 focus:ring-[#1A73E8]
transition-colors
"
>
Login
</button>
</div>
{/* Mobile toggle */}
<button
className="md:hidden p-2 text-[#5F6368]"
onClick={() => setMobileOpen(!mobileOpen)}
>
{mobileOpen ? <X size={24} /> : <Menu size={24} />}
</button>
</div>
{/* Mobile menu */}
{mobileOpen && (
<div className="md:hidden border-t border-[#5F6368]/10 bg-white">
<div className="px-6 py-4 space-y-3">
{links.map((link) => (
<a
key={link.href}
href={link.href}
className="block text-sm text-[#5F6368] hover:text-[#202124]"
>
{link.label}
</a>
))}
<button
onClick={onLogin}
className="
w-full mt-4 px-4 py-3 text-sm font-medium
bg-[#1A73E8] text-white rounded-lg
hover:bg-[#1557B0] transition-colors
"
>
Login
</button>
</div>
</div>
)}
</nav>
);
}Tokens aplicados corretamente: cores da paleta, radius rounded-lg (md: 8), espaçamento em múltiplos de 4/8, ícones stroke (Lucide usa stroke por padrão), estados hover e focus no botão.
Dicas Específicas do Codex CLI
Use full-auto para batch de componentes
O modo full-auto brilha quando você quer gerar vários componentes de uma vez:
codex --mode full-auto "Crie todos os componentes atômicos do design system:
Button (primary, secondary, ghost), Input, Textarea, Select, Checkbox, Radio,
Toggle, Badge, Avatar, Tooltip. Um arquivo por componente em src/components/.
Seguir DESIGN.md rigorosamente."Ele gera todos em sequência, usando os mesmos tokens. Consistência garantida.
AGENTS.md hierárquico
O Codex CLI suporta AGENTS.md em subdiretórios. Use para regras locais:
# src/components/AGENTS.md
## Regras para componentes
- Exportar interfaces de Props separadamente (para reuse)
- Adicionar JSDoc com descrição do componente
- Incluir `className` prop para override via Tailwind merge
- Testar acessibilidade: aria-labels, roles, keyboard navigationResumo de tokens no AGENTS.md
Para projetos onde o DESIGN.md é extenso, coloque um resumo compacto direto no AGENTS.md:
### Quick reference (do DESIGN.md)
| Token | Valor |
|-------|-------|
| primary | #1A73E8 |
| text | #202124 |
| muted | #5F6368 |
| bg | #F8F9FA |
| radius | 8px |
| spacing | 8px base |O Codex lê o AGENTS.md sempre. O DESIGN.md pode ser cortado em contextos limitados. O resumo no AGENTS.md é um fallback.
Combine com CODEX.md
Se o projeto já tem um AGENTS.md genérico para múltiplos agentes, crie um CODEX.md que é específico para o Codex CLI:
# CODEX.md
Instruções específicas para OpenAI Codex CLI neste projeto.
## Prioridades
1. Ler DESIGN.md para qualquer trabalho visual
2. Commits granulares: um componente = um commit
3. Rodar lint após cada edição
4. Não instalar dependências sem aprovaçãoSandbox como proteção
O modo full-auto roda em sandbox. Isso significa que o Codex não afeta seu repo até você aceitar. Use isso a seu favor:
- Rode um batch de gerações
- Revise os arquivos gerados
- Aceite só os que seguiram o DESIGN.md
- Rejeite e re-instrua os que desviaram
Troubleshooting e Gotchas
O Codex não lê o AGENTS.md
Verifique:
- O arquivo está na raiz do repositório
- O nome é exatamente
AGENTS.md(case-sensitive) - O Codex está sendo executado na raiz do projeto
- A versão está atualizada:
npm update -g @openai/codex
Contexto limitado corta o DESIGN.md
O sandbox do Codex tem budget de tokens. Se o DESIGN.md é cortado:
- Mantenha abaixo de 2000 tokens
- Coloque os tokens mais críticos no YAML front matter (lido primeiro)
- Use o resumo no AGENTS.md como fallback
- Remova prosa extensa — o Codex precisa de dados, não de explicações
Full-auto gera componentes inconsistentes
Em batch grande, o Codex pode “esquecer” tokens ao longo da geração. Soluções:
- Divida em batches menores (3-5 componentes por execução)
- Adicione ao AGENTS.md: “Releia DESIGN.md antes de CADA componente”
- Use
--mode auto-editem vez de full-auto para revisar cada componente
O Codex instala pacotes inesperados
Em full-auto, ele pode rodar npm install para dependências que julgue necessárias. Controle via AGENTS.md:
## Dependências
Dependências permitidas para componentes visuais:
- lucide-react (ícones)
- clsx (conditional classes)
- tailwind-merge (class merge)
NÃO instalar sem aprovação:
- Component libraries (shadcn, radix, MUI, Chakra)
- CSS-in-JS (styled-components, emotion)
- Qualquer outra lib de UIDiff grande difícil de revisar
Se o Codex gera muitos arquivos de uma vez, use git para revisar:
git diff --stat # Ver quais arquivos mudaram
git diff -- src/components/Button.tsx # Revisar um por um
git add -p # Stage seletivoModelo Mental: AGENTS.md como Briefing
Pense no AGENTS.md como o briefing que você daria a um desenvolvedor novo no time:
- “Aqui está nosso design system” (→ DESIGN.md)
- “Estas são as regras que você não pode quebrar” (→ Restrições)
- “Este é o padrão de código que usamos” (→ Convenções)
- “Estes arquivos você não toca” (→ Read-only)
O Codex CLI é esse desenvolvedor. O AGENTS.md é seu onboarding. O DESIGN.md é o guia visual. Juntos, eles transformam um agente genérico num agente que gera código no padrão do seu time.
Conclusão e Próximo Passo
O Codex CLI com DESIGN.md é para quem quer automação pesada. Gerar 10, 20, 50 componentes em batch — todos seguindo o mesmo design system — sem abrir IDE. O AGENTS.md garante que o agente lê as regras antes de cada ação. O sandbox permite revisão sem risco.
A chave é manter o DESIGN.md conciso e o AGENTS.md assertivo. Menos prosa, mais dados. Menos “seria legal se”, mais “faça exatamente isso”. O Codex é obediente quando as instruções são claras.
Próximos passos:
- O que é DESIGN.md — especificação completa do formato
- Biblioteca de DESIGN.md — 450+ design systems prontos
- Guias de outros agentes: Aider · Cline · Devin · Continue.dev
Links úteis
- Biblioteca de DESIGN.md — copie um DESIGN.md pronto
- Skill design-md — gere a partir do seu codebase
- O que é DESIGN.md — referência completa do formato