# Trabalhando com agentes de programação com IA

Começar com Claude Code ou Codex, onde um agente lê, onde fica cada bloco e quais regras sempre valem.

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:

```bash
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:

```bash
./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`](/llms.txt) lista todas as páginas, [`/llms-full.txt`](/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`](/nimbly.json) lista a stack, as funcionalidades incluídas e os comandos da CLI.

## Onde fica cada bloco

| Bloco | Lugar | O que contém |
|---|---|---|
| Rota | `ext/uri/<path>/index.tpl` | Um endereço. O caminho da pasta é a URL. |
| Template | `ext/tpl/<name>/index.tpl` | Um bloco reutilizável de markup, chamado como `[#name#]`. |
| Recurso | `ext/data/<resource>/.meta` | Os campos, a validação, os índices e as permissões de um tipo de registro. |
| Biblioteca | `ext/lib/<name>.php` | Lógica em PHP, chamada como `[#name#]`. Prepara dados; o markup fica nos templates. |
| Módulo | `ext/modules/<name>/` | Uma funcionalidade com rotas e dados próprios. |

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

```bash
./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.