Framework · IA e design · 3 min de leitura
Arquivos de contexto
Arquivos que os agentes de IA leem automaticamente (CLAUDE.md, AGENTS.md, DESIGN.md) e que guardam os seus princípios, as regras do design system e as convenções, para que cada sessão comece dos seus padrões e não de padrões genéricos.
Regras estáveis que toda sessão lê: usuários, princípios, tokens, componentes, regras do tipo "nunca".
Em geral: CLAUDE.md, AGENTS.md, DESIGN.mdO que este recurso precisa fazer: problema, usuários, fluxos, estados, regras, critérios de aceite.
Em geral: uma especificação na wiki ou no repositórioO pedido desta iteração, dentro da conversa com a ferramenta.
Em geral: "Mostre três opções"Muda raramente → muda a cada recurso → muda a cada iteração
Use quando
- Os designers repetem as mesmas instruções ("use os nossos componentes", "nada de cores soltas") em todo prompt.
- Os protótipos gerados por IA parecem genéricos ou fora do sistema, mesmo com boas especificações do recurso.
- Você está montando um repositório de protótipos ou uma configuração de agente compartilhada para o time.
Como usar
- Saiba qual arquivo as suas ferramentas leem. Os agentes leem um arquivo de instruções do projeto no início de cada sessão:
CLAUDE.mdpara o Claude Code,AGENTS.mdcomo formato aberto que muitos agentes aceitam, eDESIGN.md(um formato do Google Labs: tokens mais a justificativa por escrito) para o design system. No fim de 2026 essas convenções ainda mudam, então confira a documentação da sua ferramenta. Resultado: os nomes de arquivo que as ferramentas do seu time usam. - Escreva só as regras estáveis. Quem são os usuários, princípios de design, tokens, o inventário de componentes, o tom de voz, a base de acessibilidade. Detalhes de recurso vão na especificação do recurso, e pedidos pontuais vão no prompt. Resultado: um primeiro rascunho, de preferência com menos de uma ou duas telas.
- Escreva explicitamente as regras do tipo "nunca". "Nunca coloque cores, espaçamentos ou tamanhos de fonte fixos no código." "Nunca crie componentes parecidos com os do sistema." "Se um componente não existe, pare e liste como questão em aberto." Resultado: uma lista curta de "nunca".
- Aponte para a fonte, não copie. Faça referência aos nomes dos tokens e à biblioteca de componentes em vez de colar valores que vão ficar desatualizados. Veja Design tokens. Resultado: links e nomes em vez de valores duplicados.
- Versione e revise como código. Mantenha o arquivo no repositório, mude-o por revisão e defina um dono (muitas vezes o time do design system). Quando um agente cometer o mesmo erro duas vezes, acrescente uma regra. Resultado: um arquivo versionado, com dono e histórico de mudanças.
Exemplo prático
Uma plataforma interna de operações com 6 times de produto. Os designers fazem protótipos em código com um agente, e todo protótipo volta com botões cinza inventados e sem estados vazios. O designer do design system acrescenta um CLAUDE.md curto ao repositório de protótipos:
## Regras de design
- Os usuários são operadores experientes; prefira densidade e suporte a teclado.
- Use só componentes de @acme/design-system; nunca crie componentes parecidos.
- Use design tokens (var(--ds-*)); nunca coloque cores, espaçamentos ou tamanhos de fonte fixos.
- Toda tela de lista precisa de estados vazio, carregando, erro e muitos dados.
- Base de acessibilidade: WCAG 2.2 AA; foco visível; nenhum status só por cor.
- Se um componente necessário não existe, pare e liste como questão em aberto.
Os protótipos seguintes usam componentes da biblioteca e incluem os quatro estados de lista. Quando, mais tarde, um agente inventa um componente "chip", o time acrescenta mais uma linha em vez de corrigir à mão toda vez.
Cuidado com
- Um arquivo de contexto que tenta guardar tudo. Arquivos longos enterram as regras que importam. Deixe os detalhes de recurso nas especificações e coloque links para a documentação mais profunda.
- Regras vagas. "Siga o nosso design system" não dá ao agente nada para conferir. Diga o nome da biblioteca, o prefixo dos tokens e a regra exata.
- Valores copiados que se desatualizam. Códigos hex colados no arquivo ficam velhos quando os tokens mudam. Use os nomes dos tokens.
- Ninguém é dono. Um arquivo sem dono vai se enchendo de regras conflitantes. Revise as mudanças como código.
Modelo
Copie isto para CLAUDE.md, AGENTS.md ou DESIGN.md e preencha para o seu produto.
# Contexto de design: <nome do produto>
## Usuários
- Quem são, o que fazem o dia todo, do que precisam (ex.: densidade, uso de teclado)
## Princípios
- <princípio 1>
- <princípio 2>
## Design system
- Componentes: só de <nome da biblioteca>
- Tokens: use <prefixo dos tokens>, veja <link para a documentação dos tokens>
- Padrões: <link para os níveis de padrão / regras de uso>
## Base de acessibilidade
- WCAG 2.2 AA; foco visível; nenhum status só por cor
## Nunca
- Nunca coloque cores, espaçamentos ou tamanhos de fonte fixos
- Nunca crie componentes parecidos com os do sistema
- Nunca use dados reais de clientes ou dados pessoais nos dados de exemplo
## Na dúvida
- Pare e liste a questão em aberto em vez de inventar uma solução
Dono: Última revisão: