Trabalhando com agentes de programação com IA

Esta página é para agentes de programação com IA que trabalham num projeto Nimbly, como Claude Code ou Codex, e para os desenvolvedores que trabalham com eles. Uma aplicação Nimbly é feita de pequenos blocos em lugares previsíveis, então uma tarefa normalmente mexe em poucos arquivos curtos.

Comece em um minuto

Trabalhar num projeto Nimbly com um agente de programação com IA não exige configuração. Crie o projeto e inicie o agente na pasta dele:

git clone https://github.com/Nimbly-Web-Systems/nimbly-core.git my-project
cd my-project
./nimbly init
claude        # or: codex

Depois, peça o que quiser em palavras simples:

Adicione uma página de contato com um formulário que guarde as mensagens. Veja em .context a documentação e o design existentes.

A partir daí o agente se vira: ele lê as instruções do projeto, olha o briefing e o design que você colocou em .context/, define um recurso para as mensagens, adiciona o formulário e a página, abre aos visitantes apenas o envio do formulário e roda as verificações.

.context/ é o lugar para o material do seu projeto: requisitos, arquivos de design, capturas de tela, anotações. Ele fica na sua máquina e não é commitado. O material que todos no projeto devem compartilhar vai em ext/.context/, que faz parte do repositório da sua aplicação.

As instruções do agente já estão lá. Todo projeto tem AGENTS.md (lido pelo Codex e pela maioria dos outros agentes) e CLAUDE.md (lido pelo Claude Code) na raiz, com o mesmo conteúdo: onde o código deve ficar, como o Nimbly funciona, como consultar a referência e como verificar o trabalho. Eles vêm com o core, então melhoram a cada atualização do core.

As regras do seu próprio projeto, como nomes, escolhas de design ou o que evitar, vão em ext/.context/AGENTS.md. Esse arquivo viaja com o repositório da sua aplicação, e o agente o lê junto com as instruções gerais.

Leia primeiro

Todo projeto tem a referência completa em NIMBLY.md, na raiz. Ela é grande; consulte o que a tarefa precisa em vez de ler tudo de uma vez:

./nimbly docs:list
./nimbly docs:search "router_accept"
./nimbly docs:section "Template Syntax > route.inc"

• docs:list mostra todos os títulos, para achar o termo certo.
• docs:search procura um termo no texto.
• docs:section mostra uma seção pelo caminho dos títulos.

O mesmo conteúdo está neste site como texto simples. /llms.txt lista todas as páginas, /llms-full.txt reúne todas as páginas num arquivo, e cada página tem uma versão em Markdown no seu próprio endereço com .md no final, por exemplo /pt/docs/concepts/resources.md. /nimbly.json lista a stack, as funcionalidades incluídas e os comandos da CLI.

Onde fica cada bloco

O framework fica em core/ e é o mesmo para todo projeto. O trabalho na aplicação vai em ext/.

Regras que sempre valem

• Examine o código existente antes de acrescentar algo novo. Reutilize um bloco que já existe.
• Markup fica nos templates. Bibliotecas PHP preparam dados e não imprimem HTML.
• [#if#] é uma tag única. Ele não tem forma de bloco. Markup condicional vai num template próprio, indicado com tpl=.
• [#set#] não substitui um valor já definido, a menos que overwrite seja informado.
• Uma rota estática não tem route.inc. Uma rota dinâmica verifica sua entrada e responde com router_accept() ou router_deny().
• PHP usa snake_case para funções, variáveis e nomes de arquivo.
• Use as funções e permissões existentes em vez de um segundo sistema de permissões.
• Tailwind CSS, DaisyUI e Alpine.js são o padrão do projeto. Use outra biblioteca ou framework quando o projeto pedir.

Verifique seu trabalho

./nimbly build
./nimbly test:architecture --strict
./nimbly test:run

Rode a menor verificação que cubra a mudança. Código e conteúdo versionados podem ser revisados como diffs do Git. Registros de runtime, mídia e credenciais podem ficar fora do controle de versão; verifique essas mudanças pelas telas correspondentes e pela rotina de backup.