diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..2824b3899
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,78 @@
+# AGENTS.md
+
+Contribution rules and conventions for flixopt, for humans and AI agents alike.
+
+## AI-assisted contributions
+
+You're welcome to help author code, pull requests and issues. But the
+conversation around a change — PR and issue descriptions, comments and review
+discussions — is how maintainers and contributors understand each other, so it
+must stay human and honest. Three rules:
+
+1. **AI-generated content must be marked**, preferably with a GitHub note alert
+   at the top of the generated section. Put verbose additional context (logs, generated analysis, long
+   reproductions) in a collapsed `<details>` block so it doesn't drown the
+   discussion.
+
+   Don't silently mix hand-written and generated prose.
+
+2. **The human writes their own intent.** If a pull request or issue is more
+   than a self-documenting bug report, the author must write — or at least
+   rewrite in their own words — their personal intent and motivation by hand,
+   with everything else placed below it. Don't submit an AI-drafted description
+   as your own; the maintainers want the human's voice, concise and to the
+   point.
+
+   ```markdown
+   Thats why this is important for me (handwritten)
+
+   > [!NOTE]
+   > The following content was generated by AI.
+
+   What was implemented and how
+
+   <details>
+   <summary>Full benchmark output</summary>
+
+   ...verbose content here...
+
+   </details>
+   ```
+
+3. **Conversations are not held through an agent.** Posting bare information via
+   an agent — e.g. a log, a benchmark result, a reproduction — is fine as long
+   as it's marked (see rule 1). But discussion itself — replies, answers to
+   questions, review back-and-forth — must be written by the human. Don't let an
+   agent argue, agree or decide on your behalf.
+
+## Development workflow
+
+- Install the project with development dependencies into your environment:
+  `pip install -e ".[full,dev]"`.
+- Set up the pre-commit hooks once with `pre-commit install`; they run the
+  quality checks automatically on every commit.
+- Run the test suite with `pytest`, and lint and format with `ruff`
+  (`ruff check --fix .` and `ruff format .`).
+- For the authoritative, detailed setup and commands (docs, markers, coverage)
+  see [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Project conventions
+
+- Branch off `main` for every change and open pull requests via the GitHub CLI
+  (`gh`). Name branches `feature/…`, `fix/…` or `docs/…`.
+- Write tests for new features and bug fixes under `tests/` as `test_*.py`,
+  reusing the shared fixtures from `tests/conftest.py` (e.g. `solver_fixture`,
+  `highs_solver`) where useful. Run the tests after making changes and make sure
+  they pass.
+- Aim for full test coverage on new code, and add the `@pytest.mark.slow`
+  decorator to tests that take more than a few seconds.
+
+## Architecture in one paragraph
+
+flixopt is an energy-system optimization library built on linopy and xarray:
+components (flows, storages, converters, effects) are assembled into a
+`FlowSystem`, translated into a linopy model, and solved with an interchangeable
+solver (HiGHS by default, Gurobi optionally). Time series, periods and scenarios
+are dimension-labelled xarray structures that broadcast and align by dimension,
+and the model is only handed to the solver at solve time. Keep new features
+consistent with this component-based, xarray-backed design.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..276bc76e2
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,8 @@
+# CLAUDE.md
+
+This project's guidance for AI agents — contribution rules, development workflow
+and project conventions — lives in [`AGENTS.md`](AGENTS.md), imported below so
+it loads automatically. Read it before making changes, opening pull requests or
+issues, or writing comments.
+
+@AGENTS.md