# Werken met AI-codeeragents

Starten met Claude Code of Codex, waar een agent leest, waar elk blok staat en welke regels altijd gelden.

Deze pagina is voor AI-codeeragents die in een Nimbly-project werken, zoals Claude Code of Codex, en voor de developers die met ze werken. Een Nimbly-applicatie bestaat uit kleine blokken op voorspelbare plekken, dus een taak raakt meestal een paar korte bestanden.

## Begin in een minuut

Werken aan een Nimbly-project met een AI-codeeragent vraagt geen inrichting. Maak het project en start de agent in de projectmap:

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

Vraag dan in gewone woorden wat je wilt:

> Voeg een contactpagina toe met een formulier dat de berichten opslaat. Kijk in .context voor de bestaande documentatie en het ontwerp.

Vanaf daar vindt de agent zijn weg: hij leest de instructies van het project, bekijkt de briefing en het ontwerp die je in `.context/` hebt gezet, definieert een resource voor de berichten, voegt het formulier en de pagina toe, opent alleen het versturen van het formulier voor bezoekers, en draait de checks.

`.context/` is de plek voor je projectmateriaal: eisen, ontwerpbestanden, screenshots, notities. Het blijft op je eigen machine en wordt niet gecommit. Materiaal dat iedereen op het project moet delen, gaat in `ext/.context/`, dat deel is van de repository van je applicatie.

De instructies voor de agent staan er al. Elk project heeft `AGENTS.md` (gelezen door Codex en de meeste andere agents) en `CLAUDE.md` (gelezen door Claude Code) in de hoofdmap, met dezelfde inhoud: waar code hoort, hoe Nimbly werkt, hoe je dingen opzoekt en hoe je het werk controleert. Ze komen mee met core, dus ze worden beter met elke core-update.

Regels van je eigen project, zoals naamgeving, ontwerpkeuzes of wat je wilt vermijden, zet je in `ext/.context/AGENTS.md`. Dat bestand reist mee met de repository van je applicatie, en de agent leest het naast de algemene instructies.

## Eerst lezen

Elk project heeft de volledige naslag in `NIMBLY.md` in de hoofdmap. Die is groot; zoek op wat de taak nodig heeft in plaats van alles in één keer te lezen:

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

- `docs:list` toont elke kop, om de juiste term te vinden.
- `docs:search` zoekt één term in de tekst.
- `docs:section` toont één sectie via het pad van de koppen.

Dezelfde inhoud staat op deze site als platte tekst. [`/llms.txt`](/llms.txt) noemt elke pagina, [`/llms-full.txt`](/llms-full.txt) bevat alle pagina's in één bestand, en elke pagina heeft een Markdown-versie op zijn eigen adres met `.md` erachter, bijvoorbeeld `/nl/docs/concepts/resources.md`. [`/nimbly.json`](/nimbly.json) noemt de stack, de meegeleverde features en de CLI-commando's.

## Waar elk blok staat

| Blok | Plek | Wat erin staat |
|---|---|---|
| Route | `ext/uri/<path>/index.tpl` | Eén adres. Het pad van de map is de URL. |
| Template | `ext/tpl/<name>/index.tpl` | Een herbruikbaar stuk markup, aangeroepen als `[#name#]`. |
| Resource | `ext/data/<resource>/.meta` | De velden, validatie, indexen en rechten van één soort record. |
| Library | `ext/lib/<name>.php` | PHP-logica, aangeroepen als `[#name#]`. Bereidt data voor; markup blijft in templates. |
| Module | `ext/modules/<name>/` | Een feature met eigen routes en data. |

Het framework staat in `core/` en is voor elk project hetzelfde. Werk aan de applicatie gaat in `ext/`.

## Regels die altijd gelden

- Bekijk de bestaande code voordat je iets nieuws toevoegt. Hergebruik een blok dat er al is.
- Markup hoort in templates. PHP-libraries bereiden data voor en printen geen HTML.
- `[#if#]` is één tag. Het heeft geen blokvorm. Voorwaardelijke markup gaat in een eigen template, genoemd met `tpl=`.
- `[#set#]` vervangt geen waarde die al gezet is, tenzij `overwrite` erbij staat.
- Een statische route heeft geen `route.inc`. Een dynamische route controleert zijn invoer en antwoordt met `router_accept()` of `router_deny()`.
- PHP gebruikt snake_case voor functies, variabelen en bestandsnamen.
- Gebruik de bestaande rollen en rechten in plaats van een tweede rechtensysteem.
- Tailwind CSS, DaisyUI en Alpine.js zijn de standaard van het project. Gebruik een andere library of een ander framework waar het project daarom vraagt.

## Controleer je werk

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

Draai de kleinste check die de wijziging dekt. Gevolgde code en content kun je bekijken als Git-diffs. Runtime-records, media en inloggegevens vallen soms buiten versiebeheer; controleer die wijzigingen via de betreffende schermen en de back-upwerkwijze.