diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..329b289
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,28 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+`main.go` wires the Fiber application, middleware, routes, database startup, and template engine. Keep HTTP handlers in `controllers/`, persistence logic and data types in `repositories/`, database setup in `db/`, and environment parsing in `config/`. Gateway integration belongs in `gateway/`; shared helpers live in `utils/` and `files/`. Server-rendered HTML is organized under `templates/{pages,components,head}`, while browser assets live in `static/`. Add ordered PostgreSQL changes to `migrations/` using the existing `<number>-<description>.sql` pattern. Load-testing scripts belong in `tests/`.
+
+## Build, Test, and Development Commands
+
+- `cp .env.example .env` creates local configuration; adjust `POSTGRES_URL` before starting.
+- `go run .` starts the service and applies migrations against the configured PostgreSQL database.
+- `make dev` runs the app through `nodemon` for automatic restarts.
+- `go build .` produces the local `micrach` binary.
+- `GO111MODULE=on CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build .` matches the CI Linux build.
+- `go test ./...` runs all Go tests.
+- `go vet ./...` performs standard static checks.
+- `sh tests/load.sh` runs the optional Vegeta load test; review its target URL first.
+
+## Coding Style & Naming Conventions
+
+Use `gofmt` (tabs for Go indentation) and run `go fmt ./...` before submitting. Keep package names short and lowercase. Use `PascalCase` for exported identifiers, `camelCase` for unexported identifiers, and descriptive handler names such as `CreateThread`. Keep controllers thin: validation and HTTP concerns stay in handlers, while SQL and persistence behavior stay in repositories. Follow existing kebab-case names for CSS, templates, and migration descriptions.
+
+## Testing Guidelines
+
+The repository currently has no unit tests or enforced coverage threshold. Add tests beside the code as `*_test.go`, using `TestXxx` and table-driven cases where practical. Avoid shared production databases; isolate repository tests with disposable test data or a dedicated database. Run `go test ./...` and `go vet ./...` for every change. Use Vegeta only for explicit performance work.
+
+## Commit & Pull Request Guidelines
+
+History mixes terse imperative subjects with `feat:` and `fix:` prefixes. Prefer focused Conventional Commit subjects, for example `fix: reject oversized uploads`. Keep each commit buildable. Pull requests should explain behavior changes, configuration or migration impact, and verification commands. Link relevant issues and include screenshots for template or CSS changes. Never commit `.env`, uploads, generated load-test artifacts, or credentials.