Orientação para IA
AGENTS.md, docs de agente e hot reload r/R no projeto gerado.
Cada projeto kasy new traz um pacote de orientação para IA (Cursor, Claude Code, Copilot, MCP). Não é documentação do app para o usuário final. É o contrato para quem edita o código com assistente.
Esta página faz parte da documentação em kasy.dev/docs (menu Docs do site). Não é a landing page de marketing. Os arquivos listados abaixo ficam dentro do projeto após kasy new.
O índice no repo: docs/agent-guidance.md. Contrato mestre: AGENTS.md.
Mapa de arquivos
| Arquivo | Pra quem | O que é |
|---|---|---|
AGENTS.md | IA + dev | Contrato principal (golden rules, arquitetura, Browser QA) |
CLAUDE.md | Claude Code | Aponta pro AGENTS.md |
DESIGN_SYSTEM.md | IA + dev | Tokens, tipografia, componentes, semantics |
docs/agent-guidance.md | IA + dev | Este mapa, dentro do projeto |
docs/agent-browser-qa.md | IA | Checklist ao testar no navegador |
.cursor/rules/kasy-agent-contract.mdc | Cursor | Always-on: analyze, reload r/R, terminal |
.cursor/rules/kasy-design-system.mdc | Cursor | Always-on: UI do kit |
.cursor/skills/kasy-project/SKILL.md | Cursor | Roteiro: leia AGENTS.md |
Firebase, Supabase e API recebem o mesmo pacote. O patch de backend só muda dados.
r e R (minúsculo vs maiúsculo)
Com kasy run ou kasy run --web rodando, depois que a IA termina uma edição:
| Mudança | Comando |
|---|---|
| Botão mais bonito, layout, cor, texto, estilo | r (hot reload) |
Bug, provider, rota, initState, main(), lógica | R (hot restart) |
Mandou r e o terminal deu erro ou “hot reload rejected” | R |
F5 na aba do browser não recompila Dart.
Como mandar:
- MCP (preferido):
reload_app(action=reloadUI,action=restartlógica). Só web (kasy run --web). iOS/Android: terminalr/R. - Terminal do
kasy run(digiterouRe leia a saída). - Toolbar do device preview (botões
reRna barra do preview).
A IA pode usar o terminal quando o ambiente permite. Não deve fingir que não tem terminal. Se estiver bloqueada, pede permissão ou usa a toolbar do preview.
Sessão live
Salvar um arquivo Dart não atualiza o app sozinho. Com kasy run rodando, mande r ou R no processo (terminal ou toolbar do preview). Terminal e toolbar usam o mesmo dev bridge.
O watcher do kasy run --web pinta o dot de status ao salvar (analyze). Para ver a mudança no app, ainda precisa de r ou R (você, ou a IA após terminar a tarefa com sessão ativa).
Browser QA
Quando a IA navega, preenche ou valida um fluxo no browser: checklist completo em docs/agent-browser-qa.md no projeto. Contexto técnico (semantics, ponte JS): Guia Web → Browser QA. MCP: browser_qa_guide.
Skill vs AGENTS.md
AGENTS.md já é a instrução para Claude Code e ferramentas que leem o repo.
A Skill kasy-project em .cursor/skills/ é um roteiro de entrada no Cursor (alinhada à propaganda de “skill Kasy”). Não duplica o contrato: aponta pro AGENTS.md e pro reload r/R.
Perguntas estruturadas (MCP)
Quando o assistente precisa de várias decisões (criar projeto, escolher plataforma no run_app, configurar credenciais), o MCP do Kasy instrui a IA a não mandar listas numeradas no chat.
- Formulário MCP: só clientes sem AskQuestion.
create_projectcomuseElicitationForm: truee semdirectory/backend. No Cursor, use AskQuestion e passe todos os args; nunca chame semdirectory/backend. - Quiz da IDE (Cursor): AskQuestion passo a passo (backend, região, push no Supabase/API). Google vem ligado por padrão (independente do push); não pergunte Google separado. Sem companion, credenciais depois com
configure_google_login. - Texto: último recurso. Uma pergunta por vez. Chave de licença e OAuth = texto livre, não quiz.
Relacionados
- Guia Web (porta 5555, preview, hot reload)
- MCP de Kasy (
browser_qa_guide,run_app) - Design System (tokens no app)
Atualizado em 03/11/2026