xav-portfolio/AGENTS.md

AGENTS.md

Project Overview

This repository is a foundational Dockerized Django portfolio website. Local development currently uses SQLite and a single Docker Compose web service. Do not assume a frontend stack, deployment platform, or CI provider unless the repository explicitly defines one.

Working Principles

• Prefer small, reviewable changes with a clear purpose.
• Inspect the repository before making changes. Follow existing patterns once they exist instead of introducing parallel conventions.
• Keep local development Docker-first. Add and document Docker Compose commands when the Compose configuration is introduced.
• Do not hard-code credentials, secret keys, hostnames, or environment-specific configuration.
• Update README.md, this file, and SECURITY.md when implementation changes make their instructions inaccurate.

Django Conventions

• Keep environment-specific settings outside committed source code. Load sensitive values from environment variables or a deployment secret store.
• Organize Django apps by domain responsibility. Avoid creating apps solely to mirror technical layers.
• Use Django migrations for schema changes. Commit generated migration files with the code that requires them.
• Review migrations before committing them. Avoid destructive schema changes without an explicit data migration or rollout plan.
• Keep views, forms, serializers, templates, and models focused. Extract shared behavior only when there is a concrete reuse case.
• Use Django's built-in security protections unless there is a documented reason to override them.

Docker Workflow

Docker Compose is the preferred local interface:

docker compose up --build -d
docker compose exec web python manage.py check
docker compose exec web python manage.py migrate
docker compose exec web python manage.py test
docker compose run --rm frontend npm run test
docker compose run --rm frontend npm run build
docker compose down

Keep containers reproducible:

• Pin runtime versions and dependency versions using the chosen package manager's lock mechanism.
• Run application processes as a non-root user where practical.
• Do not bake secrets or local environment files into images.
• Add a .dockerignore when Docker files are introduced.
• Use a .env.example to record environment variables, and do not touch the production .env.
• The Web Container should be entirely self contained, without splitting the functionality into multiple containers. It should include both backend, frontend, integrated database, webserver, etc.

Frontend Conventions

• Keep Django responsible for page rendering and use React only for focused interactive islands unless the architecture is intentionally changed.
• Build frontend assets with the one-shot Docker Compose frontend service.
• Keep npm dependencies pinned and commit frontend/package-lock.json.
• Keep generated frontend bundles out of version control. The Docker image builds its own production bundle.
• Treat committed TopoJSON map files as generated assets derived from Natural Earth data. Regenerate them deliberately rather than editing them by hand.

Validation

Before considering a change complete, run the checks supported by the current repository. Once available, this should include:

• Django system checks.
• The automated test suite.
• Migration consistency checks.
• Formatting, linting, and type checks selected by the project.
• A Docker image build and a basic container startup check for infrastructure changes.

If a check is not yet configured or cannot be run, state that clearly in the change summary. Do not invent placeholder commands that appear executable.

Change Hygiene

• Never commit .env files, secret values, local databases, uploaded media, caches, or generated build output.
• Add tests for behavior changes and regression fixes once the test harness exists.
• Keep documentation aligned with actual repository behavior.
• Avoid unrelated refactors in focused feature or bug-fix changes.