kodi
208 lines
4.0 KiB
Markdown
208 lines
4.0 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project
|
|
|
|
Rename-MVP
|
|
|
|
Minimalistische webapplicatie voor het hernoemen van TV-series bestanden op basis van metadata van TheTVDB.
|
|
|
|
Technologie:
|
|
|
|
- Python
|
|
- FastAPI
|
|
- Rootless Podman
|
|
- SQLite
|
|
- TheTVDB API v4
|
|
|
|
Project root:
|
|
|
|
/home/kodi/.config/rename-mvp
|
|
|
|
|
|
---
|
|
|
|
# AI Agent Governance
|
|
|
|
Dit project wordt ontwikkeld met behulp van AI-agents (bijvoorbeeld Codex).
|
|
|
|
Agents mogen code schrijven en aanpassen, maar **moeten zich strikt houden aan de regels in dit document**.
|
|
|
|
Het primaire doel is **stabiliteit van het systeem**.
|
|
|
|
|
|
---
|
|
|
|
# Absolute Rules
|
|
|
|
Agents mogen NOOIT:
|
|
|
|
- bestaande API responses wijzigen
|
|
- bestaande endpoints verwijderen
|
|
- SAFE FILES aanpassen zonder expliciete toestemming
|
|
- projectstructuur wijzigen
|
|
- code buiten deze repository aanpassen
|
|
- andere Podman containers aanpassen
|
|
- systeemconfiguratie wijzigen
|
|
- wijzigingen maken die het contract in contracts/API_GOLDEN.md breken
|
|
- refactors of verbeteringen uitvoeren die niet expliciet gevraagd zijn
|
|
|
|
Agents mogen alleen werken **binnen deze repository**.
|
|
|
|
|
|
---
|
|
|
|
# SAFE FILES
|
|
|
|
De volgende bestanden zijn kritisch en mogen alleen aangepast worden na expliciete bevestiging van de gebruiker:
|
|
Deze bestanden bevatten infrastructuur en API-contracten.
|
|
|
|
- app/services/tvdb_auth_service.py
|
|
- container/Containerfile
|
|
- requirements.txt
|
|
- contracts/API_GOLDEN.md
|
|
- AGENTS.md
|
|
- CHANGE_POLICY.md
|
|
- SAFE_FILES.md
|
|
- docs/ARCHITECTURE.md
|
|
|
|
---
|
|
|
|
# Escalated Execution
|
|
|
|
Agents mogen escalated execution gebruiken voor:
|
|
|
|
- podman build
|
|
- podman run
|
|
- curl tests
|
|
- project builds
|
|
- dependency install
|
|
- bestanden aanmaken of aanpassen binnen dit project
|
|
|
|
Agents mogen escalated execution **niet gebruiken voor**:
|
|
|
|
- systeemupdates
|
|
- firewall wijzigingen
|
|
- systemd configuratie
|
|
- container prune
|
|
- docker/podman cleanup
|
|
- andere containers
|
|
|
|
|
|
---
|
|
|
|
# Development Workflow
|
|
|
|
Elke wijziging moet deze stappen volgen:
|
|
|
|
1 analyseer de wijziging
|
|
2 beschrijf welke bestanden worden aangepast
|
|
3 implementeer wijziging
|
|
4 voer regressietests uit
|
|
5 voer feature tests uit
|
|
|
|
---
|
|
|
|
# Testing Policy
|
|
|
|
Automatische tests zijn verplicht voor elke wijziging.
|
|
|
|
Na iedere wijziging moet het volgende script worden uitgevoerd:
|
|
|
|
./regression_tests.sh
|
|
|
|
Dit script valideert:
|
|
|
|
- API health endpoint
|
|
- TVDB auth-status endpoint
|
|
- TVDB search endpoint
|
|
|
|
Als een regressietest faalt moet de wijziging worden teruggedraaid.
|
|
|
|
Test-URL policy:
|
|
|
|
- Op de host moet standaard getest worden via `http://127.0.0.1:8085`
|
|
- In een sandbox of containerized AI-omgeving moet getest worden via `http://host.containers.internal:8085`
|
|
- Testscripts moeten automatisch één van beide kunnen detecteren
|
|
- Agents mogen niet aannemen dat `127.0.0.1:8085` vanuit de sandbox naar de host verwijst
|
|
|
|
---
|
|
|
|
# Feature Test Policy
|
|
|
|
Nieuwe functionaliteit moet minimaal drie tests bevatten.
|
|
|
|
Agents moeten hiervoor het volgende script als basis gebruiken:
|
|
|
|
./feature_test_template.sh
|
|
|
|
De template moet worden aangepast zodat deze:
|
|
|
|
- de nieuwe endpoint of functionaliteit test
|
|
- de JSON response valideert
|
|
- controleert dat bestaande functionaliteit niet breekt
|
|
|
|
De template zelf is alleen een startpunt en moet per feature worden aangepast.
|
|
|
|
|
|
---
|
|
|
|
# Regression Tests (verplicht)
|
|
|
|
Regressietests mogen **geen nieuw TVDB-token forceren**.
|
|
|
|
De volgende tests moeten altijd slagen:
|
|
|
|
./regression_tests.sh
|
|
|
|
Als een van deze tests faalt moet de wijziging worden teruggedraaid.
|
|
|
|
|
|
---
|
|
|
|
# Handmatige Auth Test
|
|
|
|
De volgende endpoint forceert een nieuwe login en mag **niet in automatische regressietests worden gebruikt**:
|
|
|
|
curl -X POST 127.0.0.1:8085/api/tvdb/login
|
|
|
|
Deze endpoint is alleen bedoeld voor debugging.
|
|
|
|
|
|
---
|
|
|
|
# Feature Tests
|
|
|
|
Nieuwe functionaliteit moet minimaal drie tests bevatten.
|
|
|
|
|
|
---
|
|
|
|
# Security Rules
|
|
|
|
Agents moeten altijd:
|
|
|
|
- path traversal voorkomen
|
|
- MEDIA_ROOT restricties respecteren
|
|
- rename preview afdwingen
|
|
- secrets niet loggen
|
|
|
|
|
|
---
|
|
|
|
# Logging Rules
|
|
|
|
Agents mogen nooit loggen:
|
|
|
|
- API keys
|
|
- tokens
|
|
- environment secrets
|
|
|
|
|
|
---
|
|
|
|
# Design Principle
|
|
|
|
Stability over speed.
|
|
|
|
Het doel is een stabiele backend, geen snelle refactors.
|