Alterar um App de Design com IA para Desktop Local-First Dentro das Suas Regras Fixas

## Siga o Guia do Agente Quando os Arquivos de Instruções Discordarem Leia este arquivo antes de fazer qualquer mudança. Outros arquivos de instruções para agentes no repositório podem estar desatualizados em relação ao plano atual; onde eles discordarem deste, este prevalece. Documentos de projeto internos, como um documento de visão, um documento de princípios ou o plano de release atual, são contexto extra útil quando existem no seu checkout. O diretório de documentos internos está no gitignore, então os mantenedores guardam planos, handoffs e pesquisas localmente, enquanto colaboradores públicos podem não ter nada disso. - Nunca bloqueie o trabalho de colaboradores públicos por causa de arquivos que só os mantenedores conseguem ver. - Nunca cite um caminho dentro do diretório de documentos ignorado pelo git em um comentário público de revisão, a menos que esse arquivo também exista no checkout público. - Quando esses documentos não estiverem disponíveis, apoie-se neste arquivo, nas issues e pull requests públicas e no README. ## Trate Cada Design como uma Sessão Longa com Seu Próprio Workspace O produto não é um gerador de prompt único. Cada unidade de trabalho é uma sessão de agente de longa duração respaldada por um workspace real na máquina do usuário, e o agente pode ler e editar arquivos, executar comandos permissionados, fazer perguntas estruturadas, pré-visualizar artefatos, expor controles de ajuste (tweaks), gerar imagens quando o modelo configurado tiver suporte e produzir documentos de design system. - Um design é dono de um workspace. Não existe divisão entre selado e aberto: o sistema de arquivos do workspace é a fonte da verdade para artefatos e assets. - O agente edita arquivos-fonte no workspace; o runtime de preview renderiza essas fontes em um documento visualizável; os exportadores transformam o documento renderizado ou de origem em saídas padronizadas, como HTML, PDF, PPTX, ZIP ou Markdown. - Mantenha um único arquivo de entrada canônico para o formato atual (por exemplo, um arquivo de componente JSX) e reserve o arquivo HTML autônomo para exportações ou arquivos legados do workspace. - Tomar emprestadas mecânicas comprovadas de agentes de programação é intencional; a fronteira do produto é que as ferramentas específicas do domínio e o modelo de workspace local-first são o que você acrescenta por cima. ## Respeite as Regras Fixas: Sem Modelos Embutidos e Só com Chave Própria Estes são compromissos do projeto, não preferências. Não abra mão deles em troca de conveniência. 1. Nenhum runtime de modelo empacotado. Não distribua motores de inferência, interpretadores de linguagem, binários de navegador ou pesos de modelo dentro do instalador. Use instalações do sistema ou download sob demanda com consentimento visível ao usuário. 2. Somente chave própria do usuário (bring-your-own-key). Nenhuma conta hospedada, API intermediada ou telemetria por padrão. As credenciais do usuário ficam em configuração local legível por humanos. 3. Armazenamento local-first. As sessões vivem como arquivos de sessão somente-acréscimo mais arquivos reais de workspace. Dados existentes no banco de dados embarcado legado podem ser migrados, mas não adicione novas tabelas ali para sessões, histórico de chat, comentários, snapshots ou arquivos de design. 4. Todo design tem um workspace. Nada de importante pode existir apenas dentro de um registro de sessão. 5. Tudo que for distribuído, empacotado, linkado, importado pelo código do aplicativo ou entregue aos usuários deve ter licença permissiva e ser compatível com a licença do projeto. Rejeite assets de terceiros com copyleft, source-available, proprietários ou de licença pouco clara nesse conjunto. Ferramentas de CI e de release usadas apenas no fluxo de trabalho podem usar licenças copyleft quando não forem vendorizadas, empacotadas, linkadas ou copiadas para dentro do produto; documente o motivo e mantenha a saída delas limitada a metadados ou manifestos comuns. 6. Carregue recursos pesados sob demanda. Exportadores, captura web, scaffolds, skills, assets de referência e geração de imagens devem carregar sob demanda, e não na inicialização do aplicativo. 7. Reutilize primeiro as primitivas do framework de agentes subjacente. Ele é dono das sessões, das ferramentas embutidas, da execução de shell, do streaming de eventos, do registro de modelos, do registro de provedores e dos dados de capacidade, a menos que uma necessidade específica do domínio prove o contrário. 8. Dados de referência são dados, não memória do modelo. Tire valores de marca e de estilo do documento de design do workspace, de arquivos do usuário, de assets oficiais ou de fontes publicadas. Nunca invente cores de marca ou especificações de memória. 9. As mudanças devem permanecer compatíveis, atualizáveis, enxutas e elegantes, e devem seguir a checklist detalhada de princípios do projeto quando ela existir. ## Ao Criar Sites, Adicione Arquivos para IA como llms.txt Ao construir ou atualizar qualquer site, página inicial de projeto, página de produto, site pessoal, site de documentação, blog ou página pública de projeto, inclua a visibilidade para IA no escopo padrão de entrega, a menos que o usuário opte explicitamente por não fazê-lo. - Adicione um arquivo `/llms.txt` com uma visão geral concisa em Markdown do site, do autor ou organização, das páginas principais, das descrições canônicas do projeto ou produto e links para recursos legíveis por máquina. - Adicione um arquivo `/llms-full.txt` quando o site tiver conteúdo público substancial o bastante para justificar um arquivo de contexto mais completo legível por IA. - Configure o `robots.txt` de forma deliberada: permita crawlers de busca e de recuperação que ajudem sistemas de IA a citar ou recuperar conteúdo público, e trate os crawlers de treinamento como uma decisão de política separada. - Mantenha o `sitemap.xml` e garanta que ele cubra as páginas públicas importantes. Mencione o envio às ferramentas para webmasters quando for relevante. - Adicione dados estruturados JSON-LD apropriados onde forem úteis, como tipos de pessoa, organização, website, artigo, aplicativo de software, FAQ ou obra criativa. - Prefira endpoints legíveis por máquina em Markdown limpo ou JSON para entidades importantes, como perfis, projetos, posts, docs, releases, FAQs e fatos sobre o produto. - Mantenha o conteúdo verdadeiro, respaldado por fontes e sem spam. O objetivo é ajudar sistemas de IA a entender e citar com precisão conteúdo real já existente, não gerar enchimento de baixa qualidade. ## Passe Todas as Chamadas de Modelo e Ferramentas pelo Framework de Agentes Compartilhado - Construa sobre o framework de agentes compartilhado e sua camada de abstração de modelos, em vez de um equivalente feito à mão. - Use as ferramentas embutidas do framework para operações de leitura, escrita, edição, shell, grep, busca e listagem, em vez de escrever versões paralelas. - Passe toda chamada de ferramenta pelo hook de chamada de ferramentas do framework e pela interface de permissões do aplicativo. - Leia as capacidades do modelo a partir dos campos de descrição de modelo do framework, como tipos de entrada aceitos, suporte a raciocínio, custo, janela de contexto e máximo de tokens de saída. Não deixe tabelas de capacidade fixas no código. - Registre provedores personalizados pela API de registro de provedores do framework. Não construa uma camada paralela de SDK de provedores. - Todas as chamadas de modelo passam pela abstração de modelos do framework. Não importe SDKs de fornecedores diretamente no código do aplicativo. ## Guarde as Sessões em Arquivos Só de Acréscimo e os Designs no Workspace - Um design é uma sessão. O histórico de sessão fica no diretório de dados do usuário do aplicativo, como arquivos de sessão somente-acréscimo. - Arquivos-fonte de design, marcação e estilos gerados, assets, exportações e os documentos de agente e de design em nível de workspace ficam no workspace do usuário, e não em um banco de dados do aplicativo. - As configurações do workspace ficam em um arquivo de configuração versionado que carrega um campo explícito de versão de schema. - O arquivo de configurações locais pessoais é por usuário e deve continuar no gitignore. - O banco de dados embarcado legado é dado a migrar, não o modelo de armazenamento atual. Não o estenda com novo estado de funcionalidades. ## Use Só as Ferramentas Embutidas e Poucas Ferramentas de Design A superfície de ferramentas é composta pelas embutidas do framework mais uma lista curta de ferramentas de domínio: - `ask(questions)` renderiza perguntas estruturadas e aguarda o usuário. - `scaffold(kind, path)` copia um starter curado para dentro do workspace. - `skill(name)` carrega sob demanda o texto de uma skill a partir de um manifesto. - `preview(path)` renderiza artefatos e retorna erros de console, erros de assets, um esboço do DOM, métricas e capturas de tela para modelos de visão. - `gen_image(prompt, path)` grava imagens geradas em disco quando a capacidade e a configuração do provedor permitirem. - `tweaks(blocks)` declara controles editáveis entre arquivos. - `todos(items)` mostra o estado das tarefas em turnos complexos. - `done(path)` encerra um turno após uma autoverificação de preview. Não reintroduza um subagente verificador, uma ferramenta de captura de trechos, uma ferramenta de shell personalizada, uma ferramenta personalizada de listagem de arquivos, nem memória de trabalho escrita pelo agente, a menos que o plano mude. ## Mantenha Separados os Quatro Tipos de Recursos de Design O documento de design segue a especificação publicada e pode ser tanto entrada quanto saída. O trabalho de múltiplas telas gerado pelo agente mantém consistência visual atualizando esse documento conforme os tokens surgem. Os sistemas de referência embutidos devem carregar atribuição, fonte, metadados de licença e uma nota de "não afiliado", e as skills embutidas usam o formato padrão de arquivo de skill. Os manifestos de skills e de scaffolds devem carregar metadados de licença e de fonte. Os quatro tipos de recurso não são intercambiáveis: - Skills em Markdown são regras de método. Elas dizem ao agente como trabalhar; não copiam arquivos para dentro de um workspace. - Design systems de referência são somente leitura, carregados por nome como uma skill. Não os edite para um projeto; traduza as escolhas que você adotar para o documento de design do workspace. - Scaffolds são starters concretos e assets de origem copiados para dentro do workspace. Podem estar em qualquer formato de texto, desde que o manifesto os descreva com precisão. - Trechos de design skills são padrões de componente copiáveis expostos pelo sistema de arquivos virtual. São trechos de código-fonte, não regras de método e não autoridade de marca. O documento de design do workspace é o bastão específico do projeto. Uma vez que ele exista, é a autoridade para o design atual, e o trabalho gerado deve preservá-lo ou repará-lo, em vez de tratá-lo como mais um preset. ## Revise os Modelos Iniciais como Código de Produto e Acerte as Extensões - Trate assets de starter e de scaffold como código de produto, não como enchimento de prompt. Revise o conteúdo real dos arquivos, além do manifesto, antes de alterar ou adicionar um preset. - Mantenha o formato de origem e a extensão do arquivo alinhados. Documentos HTML completos pertencem a arquivos `.html`, starters de componente à extensão de componente, trechos de estilo a `.css`. A ferramenta de cópia deve preservar a extensão de origem, mas o próprio asset ainda precisa estar corretamente nomeado e descrito. - Os starters HTML embutidos devem ser autocontidos e pré-visualizáveis no runtime atual. Não adicione CDN nem scripts de runtime de terceiros aos assets de scaffold. Se um starter precisar de comportamento em tempo de execução, use HTML, CSS e JavaScript simples e locais, ou uma dependência carregada sob demanda fornecida pelo aplicativo, com um caminho de licença claro. - Evite textos de espaço reservado fracos, como "Título do deck", "Conteúdo da página", "Substitua isto" ou "Ponto um". Use conteúdo de exemplo neutro e utilizável, e exponha os pontos óbvios de substituição pelos padrões de tweaks declarados do starter. - As descrições do manifesto devem dizer em qual formato um starter está e devem destacar assets sensíveis à extensão, especialmente arquivos que um agente poderia, de outro modo, copiar com a extensão errada. - Ao mexer na árvore de scaffolds, audite em busca de incompatibilidades entre extensão e conteúdo, URLs de rede externas, textos de espaço reservado obsoletos e desvio de manifesto. Adicione ou atualize testes focados de scaffold e de runtime quando a mudança afetar caminhos de cópia, classificação de preview ou comportamento de ferramentas. ## Use as Ferramentas Já Escolhidas e Leia as Versões no Lockfile - Um gerenciador de pacotes para o repositório inteiro. Nunca misture um segundo. - Use o orquestrador de build escolhido pelo repositório, a ferramenta única de lint e formatação, o executor de testes unitários e o executor de testes ponta a ponta, em vez de introduzir alternativas. - TypeScript em modo estrito, com sintaxe de módulos verbatim e resolução do tipo bundler. Nada de `any`. - Conventional Commits para as mensagens e uma ferramenta de changesets para versionamento. Não edite o changelog à mão. Fixe a versão do runtime tanto no arquivo de versão quanto no campo engines. - As versões exatas dos pacotes vivem nos manifestos e no lockfile. Leia esses arquivos em vez de confiar em documentação desatualizada. - As escolhas de frontend já estão definidas: a biblioteca de visualização e a ferramenta de build escolhidas, CSS utilitário com variáveis CSS, uma biblioteca leve de estado, primitivas headless acessíveis encapsuladas no pacote de UI compartilhado, um conjunto de ícones, formulários nativos com form data e transições CSS para animação. Não introduza bibliotecas concorrentes de estado, animação ou componentes. - O chrome do aplicativo deve usar os tokens do pacote de UI compartilhado. As fontes de design geradas e as exportações podem definir o próprio sistema visual. - O repositório separa em pacotes distintos o shell do aplicativo, o núcleo do agente, a integração com provedores, o runtime de preview, a UI compartilhada, os schemas de artefatos, os exportadores, os templates e os tipos compartilhados. Coloque o código no pacote que é dono daquela responsabilidade. ## Escreva um Plano para Tarefas Maiores e Limite o Alcance das Edições - Para trabalhos não triviais de arquitetura ou de produto, leia os documentos de visão, de princípios e do plano atual quando existirem localmente; caso contrário, apoie-se neste arquivo e na discussão pública. - Escreva um arquivo de plano local duradouro para tarefas que ultrapassem cerca de cinco chamadas de ferramenta ou mais de três arquivos. Não crie burocracia de planejamento para correções pequenas e diretas. - Use worktrees separadas para trabalhos de funcionalidades paralelas ou não relacionadas. Não misture dois branches não relacionados em um mesmo checkout. - Consulte a fila de pesquisa antes de mexer no sandbox, nos comentários inline, nos controles de tweaks, nos exportadores, nas capacidades do framework, nos scaffolds, nas skills ou nos assets de referência, quando esse arquivo existir localmente. - Mantenha as edições no escopo e evite refatorações de passagem. - Antes de adicionar uma dependência distribuída ou de runtime, verifique a licença, o tamanho de instalação, as alternativas e se ela pode ser uma dependência peer. Para ferramentas usadas apenas no fluxo de trabalho, documente por que não são empacotadas e se a saída delas afeta os artefatos distribuídos. - Adicione ou atualize a cobertura de testes unitários no trabalho de funcionalidades, e amplie os testes ao alterar migrações, permissões, hooks de ferramentas ou contratos compartilhados. - Prefira um manifesto mais lógica de switch a um registro, até que dois chamadores reais precisem de mais. - Comente apenas onde a razão surpreenderia o próximo mantenedor. ## Classifique os Comandos em Quatro Níveis de Permissão e Mostre Por que um Foi Bloqueado Existe um único modelo de permissões, com níveis crescentes: - Nível 0: leituras e escritas locais ao workspace, comandos simples de arquivo e comandos de controle de versão somente leitura podem rodar sem interrupção. - Nível 1: instalações, comandos de build, buscas de rede não locais e comandos fora do diretório de trabalho perguntam uma vez e podem, então, ser incluídos na lista de permissões. - Nível 2: publicação, push, escalonamento de privilégios e outros comandos de alto raio de impacto perguntam todas as vezes. - Nível 3: comandos destrutivos de sistema, canalizar um script baixado direto para um shell e escritas em diretórios do sistema são bloqueados sem uma sobreposição explícita. Não esconda chamadas de ferramenta bloqueadas. Mostre o comando, o caminho, o nível e o motivo do bloqueio. ## Não Importe SDKs de Fornecedores Nem Adicione Rastreamento sem Consentimento - Adicionar ao controle de versão diretórios de dependências, saídas de build, arquivos de ambiente, artefatos de release gerados ou arquivos locais privados. - Importar SDKs de fornecedores de modelos no código do aplicativo, ou escrever testes que simulem o modelo no nível do SDK do fornecedor. Em vez disso, simule na fronteira do núcleo ou do framework. - Adicionar rastreamento, analytics, fluxos de conta, sincronização em nuvem ou atualização automática sem uma experiência explícita de adesão. - Fixar caminhos de usuário no código. Respeite as convenções de diretórios da plataforma, as APIs de caminho do aplicativo e as raízes de workspace. - Adicionar novo estado de funcionalidades apoiado no banco de dados legado para dados de sessão ou de design. - Introduzir uma abstração de agrupamento mais pesada acima do workspace. Várias sessões podem compartilhar um workspace, mas a barra lateral lista sessões. - Expor ramificação de sessões, desfazer e reversão de versão, suporte a servidores de ferramentas externos ou instalação de skills da comunidade, a menos que o plano mude. - Usar chamadas cruas de console no processo principal, no núcleo, nos provedores, nos exportadores ou nos pacotes compartilhados. Use o logger do projeto.