diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..0240598
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,66 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This repository tracks tooling and local plugin forks for a legacy Redmine 3.4.4
+environment. The canonical plugin sources live in `plugins/`:
+
+- `plugins/redmine_event_outbox/` - local event outbox plugin.
+- `plugins/redmine_contacts/` - patched RedmineUP Contacts fork.
+- `plugins/redmine_contacts_helpdesk/` - patched RedmineUP Helpdesk fork.
+
+Top-level Python helpers such as `redmine_outbox_worker.py` and
+`reset_helpdesk_mail_settings.py` support LAN test-instance operations. Project
+notes and design records live in `docs/`. `dist/*.MANIFEST.md` files are tracked;
+rollback tarballs are intentionally ignored. `redmine-copy/` is an ignored
+working/reference copy, not the source of truth.
+
+## Build, Test, and Development Commands
+
+Use targeted syntax checks before committing:
+
+```sh
+ruby -c plugins/redmine_contacts/lib/redmine_contacts/utils/check_mail.rb
+ruby -c plugins/redmine_contacts_helpdesk/app/models/helpdesk_mailer.rb
+ruby -c plugins/redmine_event_outbox/lib/redmine_event_outbox.rb
+python3 -m py_compile redmine_outbox_worker.py reset_helpdesk_mail_settings.py
+```
+
+Dry-run operational helpers before applying changes:
+
+```sh
+./reset_helpdesk_mail_settings.py --dry-run
+./redmine_outbox_worker.py --dry-run --batch-size 10
+```
+
+## Coding Style & Naming Conventions
+
+Follow the surrounding legacy style. Ruby plugin code uses two-space indentation
+and old Rails 4/Redmine 3 idioms. Python helpers use standard library modules,
+type hints where useful, and `snake_case` names. Keep shell-facing scripts
+executable and avoid printing secrets such as API keys or mail passwords.
+
+## Testing Guidelines
+
+Prefer focused checks over broad legacy test runs unless changing shared plugin
+behavior. For mail or database helpers, validate with dry runs first, then test
+against the LAN Redmine copy using controlled projects such as `fud-helpdesk` or
+`fud-nohelpdesk`. Record notable manual validation in `docs/` when behavior or
+deployment assumptions change.
+
+## Commit & Pull Request Guidelines
+
+The current history uses concise, imperative commit subjects, for example:
+`Initial Redmine tooling and local plugin forks`. Keep commits focused and
+describe the operational impact in the body when touching deployed plugin code.
+
+Pull requests should include a short summary, affected plugin/helper paths,
+commands run, and any LAN test result. Mention if `redmine-copy/` or the test
+host was updated outside the tracked `plugins/` source.
+
+## Security & Configuration Tips
+
+Do not commit `.env`, cache files, database exports, rollback tarballs, or the
+full `redmine-copy/` tree. Treat Redmine API keys, SSH keys, mail passwords, and
+production-derived data as sensitive. Use `plugins/` for source changes and copy
+to the test host only after review or validation.