From 32d948554fcaef7b7eec1e1d0bae16dd1453a299 Mon Sep 17 00:00:00 2001
From: Julien Neuhart <neuhart.julien@gmail.com>
Date: Sun, 8 Feb 2026 17:32:43 +0100
Subject: [PATCH] docs(ai): add AGENTS.md

---
 AGENTS.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..00087572
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,65 @@
+# Operational Guidelines for Gotenberg
+
+As an AI agent working on the Gotenberg repository, you are expected to act with the diligence and architectural foresight of a Senior Go Engineer. Gotenberg is a widely used production dependency; stability and backward compatibility are paramount.
+
+## 1. Core Philosophy & Stability
+
+* **Backward Compatibility is Law:** This project creates a public API. Never modify existing flags, configuration environment variables, or API form fields unless explicitly instructed to perform a breaking change. If a change is breaking, it must be flagged immediately in the plan.
+* **Defensive Programming:** Assume input data is malformed. Handle errors explicitly. Do not panic.
+* **Atomic Commits:** Isolate refactoring from feature additions. A Pull Request should do one thing well.
+
+## 2. Development Workflow & Tooling
+
+You must rely strictly on the project's Makefile for build and verification tasks. Do not run `go` commands directly unless debugging a specific package requires it.
+
+* **Formatting:** Run `make fmt` to format Go code before committing.
+* **Linting:**
+    * Run `make lint` to ensure Go code strictly adheres to the `.golangci.yml` configuration.
+    * Run `make lint-prettier` to verify formatting for non-Go files (Markdown, YAML, etc.).
+    * Zero linting errors are permitted.
+* **Building:** Run `make build` to verify compilation and Docker image construction.
+
+## 3. Architecture & Code Structure
+
+* **Idiomatic Go:** Follow "Effective Go" principles.
+* **Directory Separation:**
+    * `cmd/`: Application entry points only. Contains wiring and startup logic. **No business logic is permitted here.**
+    * `pkg/`: Core library code and modules. All business logic resides here.
+* **Module System:** Gotenberg is modular (e.g., Chromium, LibreOffice). When adding features, determine if they belong to an existing module or require a new strict isolation.
+
+## 4. Testing Standards
+
+Gotenberg utilizes a split testing strategy. **Integration tests are the primary and preferred method for verifying features.**
+
+* **Integration Tests (`make test-integration`):**
+    * **First Priority:** Always start here when adding features or routes.
+    * Gotenberg uses **Gherkin (Godog)** for end-to-end verification.
+    * You **must** create or update the corresponding `.feature` file in `test/integration`.
+    * These tests run within the Docker context; ensure environment consistency.
+* **Unit Tests (`make test-unit`):**
+    * Use table-driven tests for pure logic within `pkg/`.
+    * Mock external dependencies (filesystem, network) where appropriate.
+
+## 5. Documentation Requirements
+
+* **No README Updates:** Do not modify the root `README.md` unless explicitly asked.
+* **GoDoc is Mandatory:**
+    * **New Packages:** If creating a new package, you must include a `doc.go` file containing the package-level documentation.
+    * **Exported Symbols:** Every exported function, type, constant, and variable must have a proper GoDoc comment starting with its name.
+    * **Quality:** Comments must be complete sentences explaining *what* the symbol does and *how* to use it.
+    * **Example:**
+        ```go
+        // Convert transforms the input document to PDF using the Chromium engine.
+        // It returns an error if the connection to the browser instance fails.
+        func Convert(...) error
+        ```
+
+## 6. Definition of Done
+
+A task is considered complete only when:
+1.  The code compiles via `make build`.
+2.  The code is formatted via `make fmt`.
+3.  All linters pass via `make lint` and `make lint-prettier`.
+4.  Integration scenarios pass via `make test-integration`.
+5.  Unit tests pass via `make test-unit`.
+6.  All exported symbols and new packages have compliant GoDoc.
\ No newline at end of file