Desenvolvimento com IA

Este starter foi desenvolvido para ser operado por agentes de codificação baseados em IA (Cursor, Claude, Copilot, Windsurf, ChatGPT, …). Ele inclui um pequeno “sistema operacional” de instruções, uma base canônica de conhecimento de design e prompts portáteis de auditoria para que um agente — ou você — faça alterações mantendo-se fiel ao sistema (on-system), sem desvios.

O que o agente lê

Cada ferramenta utiliza seu próprio arquivo de instruções, mas todos apontam para o mesmo conjunto de regras:

Arquivo	Utilizado por	Finalidade
AGENTS.md	Cursor, Codex, a maioria dos agentes	O briefing universal: camadas da arquitetura, regras estritas, comandos de verificação
.cursor/rules/*.mdc	Cursor	Regras do projeto (architecture, design-system) aplicadas automaticamente
.cursor/hooks/ + .cursor/hooks.json	Cursor	Hooks de proteção que sinalizam edições fora das convenções
.windsurfrules	Windsurf	As mesmas regras no formato do Windsurf
.github/copilot-instructions.md	GitHub Copilot	As mesmas regras para o Copilot Chat
.agents/skills/ + .agent-skills.lock.md	Agentes com suporte a skills	Skills de escopo do projeto; o lockfile fixa as skills revisadas (checadas no CI)

A base de conhecimento de design

As decisões de design são centralizadas para que o agente nunca precise adivinhar:

• system/globals/ — a fonte única da verdade para cores, tipografia, espaçamento, interação, imagens, efeitos, responsividade, acessibilidade e catálogo de componentes/padrões. Leia antes de qualquer alteração de UI.
• src/config/site.config.ts — entrada para personalização de marca. Os valores da marca são traduzidos em tokens de design, nunca inseridos inline.
• src/registry.json — catálogo legível por máquina de cada componente, seção e página.

Arquitetura (três camadas): componentes (src/components/ui/**) → seções (src/components/sections/**) → páginas (src/pages/**). Construa páginas compondo seções; construa seções a partir de componentes.

Regras estritas (o que “on-system” significa)

• Apenas tokens. Cores, espaçamentos e tipografia vêm exclusivamente dos tokens de design — sem hex/rgb hardcoded, sem utilitários crus da paleta Tailwind (bg-blue-500). Use tokens semânticos como bg-primary, text-foreground, var(--muted-foreground).
• Modo escuro sempre funcional. Estratégia de classe; nunca inverta cores manualmente.
• Monolíngue Direto na Raiz (pt-BR). Todas as páginas vivem diretamente na raiz (src/pages/*.astro) sem prefixos artificiais.
• Aderência ao Pages CMS (100% de Controle). Todo dado comercial e texto editorial reside em src/content/ com mapeamento no .pages.yml. Proibido hardcode editorial em .astro ou .ts. Consulte Gerenciamento de Conteúdo.
• Preserve integrações fundamentais. Deploy no Cloudflare Pages, SEO/OG/RSS/sitemap, busca com Pagefind e documentação técnica do Starlight.

Verificação antes de considerar “concluído”

Peça ao agente para executar estes comandos e corrigir qualquer falha:

pnpm run check:cms   # auditoria de aderência ao Pages CMS (zero dados órfãos)
pnpm run check:docs  # auditoria de integridade da documentação e ADRs
pnpm run check:kpis  # checagens de convenções de design tokens
pnpm run lint        # eslint + stylelint + astro check + i18n + segredos
pnpm test            # testes unitários vitest
pnpm build           # build estático de produção

Engenharia de Prompt

Iniciando uma tarefa

Aponte o agente para o sistema primeiro, depois declare o objetivo:

Leia AGENTS.md, CONTEXT.md e DECISIONS.md antes de editar.
Adicione um novo componente reutilizando os componentes e tokens existentes.
Garanta 100% de aderência ao Pages CMS e execute pnpm run lint e pnpm test.

Prompts de autoauditoria

system/prompts/ contém prompts portáteis que você pode colar em qualquer ferramenta de chat para auditar o projeto em relação às suas convenções. Eles fazem referência a system/globals/ e ao script check:kpis.

Prompt	Audita
system/prompts/tokens.md	Cores hardcoded / uso fora dos tokens
system/prompts/accessibility.md	WCAG AA: teclado, foco, texto alt, landmarks
system/prompts/responsive.md	Integridade do layout de 375px a 1920px
system/prompts/darkmode.md	Paridade e contraste no modo escuro
system/prompts/performance.md	Islands, assets, Lighthouse
system/prompts/seo.md	Metadados, OG, sitemap, dados estruturados

Exemplo:

Execute a auditoria de system/prompts/accessibility.md contra src/pages/contato.astro
e liste correções concretas com referências de arquivo:linha.

Mantendo skills revisadas

As skills do projeto ficam em .agents/skills/. O conjunto revisado e fixado é registrado em .agent-skills.lock.md; a rotina de CI Skills Verification valida as skills fixadas a cada execução. Adicione ou atualize uma skill e atualize o lockfile para que colaboradores (e o CI) vejam exatamente o mesmo conjunto.