# AGENTS.md

## Purpose

This document contains instructions for AI coding agents working on this repository.

---

## General Principles

Prefer clean architecture over quick fixes.

Prefer readability over cleverness.

Keep modules small.

Avoid unnecessary abstractions.

Minimize dependencies.

Document architectural decisions.

---

## Development Workflow

Never work directly on main.

Implement one feature per branch.

Prefer many small commits.

Each commit should compile.

Each feature should include:

- implementation
- tests
- documentation updates

---

## Coding Style

Follow PEP8.

Use type hints.

Prefer dataclasses where appropriate.

Avoid global state.

Prefer dependency injection.

No hidden side effects.

---

## AI Behaviour

If requirements are ambiguous:

STOP.

Ask questions.

Never invent requirements.

Never silently change behaviour.

---

## Refactoring

Refactor only inside the requested scope.

Avoid unrelated changes.

Do not rename files without justification.

---

## Documentation

Update README if user-visible behaviour changes.

Update PROJECT_KNOWLEDGE.md when technical knowledge changes.

Update ROADMAP.md only for future work.

---

## Priority Order

Correctness

↓

Maintainability

↓

Readability

↓

Performance

↓

Premature optimization