95 lines
4.0 KiB
Markdown
95 lines
4.0 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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.
|