kodi
4.0 KiB
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:8085vanuit 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.