From 7fb4c8983205cc67bbf93e07b6d80c6ff21ee342 Mon Sep 17 00:00:00 2001 From: Julien Neuhart Date: Wed, 18 Mar 2026 13:57:56 +0100 Subject: [PATCH] chore(agents): better entrypoints --- AGENTS.md | 33 +++++++++++++++++++++++++++------ CLAUDE.md | 19 +------------------ GEMINI.md | 20 +------------------- 3 files changed, 29 insertions(+), 43 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e8a45fbe..678a1f1f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Operational Guidelines for Gotenberg -You are working on **Gotenberg**, a Docker-based API for converting documents to PDF. It is a widely used production dependency. Stability and backward compatibility are paramount. +You are working on **Gotenberg**, a Docker-based API for converting documents to PDF. It is a widely used production dependency. Stability and backward compatibility are paramount. When in doubt about whether a change is breaking, flag it rather than assuming it's safe. ## Core Principles @@ -22,10 +22,31 @@ build/ → Dockerfile, fonts, Chromium config. Key interfaces live in `pkg/gotenberg/` — `Module`, `Provisioner`, `Validator`, `Debuggable`. Every module implements `Descriptor()` and self-registers. When adding features, determine if they belong in an existing module or require a new one. -## Personas +## Quick Reference -Depending on the task at hand, load the relevant persona for additional context: +- Format before committing: `make fmt` (Go) and `make prettify` (non-Go) +- Lint before committing: `make lint && make lint-prettier` +- Commits must follow [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat(chromium): add screenshot endpoint`) +- Run unit tests: `make test-unit` +- Run integration tests: `make build && make test-integration TAGS=` +- Never run `go` commands directly — use the Makefile. -- **[DEVELOPER](.agents/DEVELOPER.md)** — Writing code: architecture, module system, Makefile workflow, coding patterns. -- **[TESTER](.agents/TESTER.md)** — Writing tests: Gherkin/Godog integration tests, unit tests, available step definitions, selective test runs. -- **[REVIEWER](.agents/REVIEWER.md)** — Reviewing code: linting rules, backward compatibility checks, documentation compliance, Definition of Done. +## Codebase Navigation + +- Start with `pkg/gotenberg/` for core interfaces and `pkg/modules/` for feature implementations. +- The integration test infrastructure in `test/integration/scenario/` is well-structured — read `scenario.go` and `containers.go` to understand the Gherkin step definitions before writing new tests. +- Mocks for all major interfaces are in `pkg/gotenberg/mocks.go` — use them for unit tests rather than creating new ones. +- Import ordering is enforced: standard library, third-party, then `github.com/gotenberg/gotenberg/v8` — separated by blank lines. +- When making changes, run only the relevant integration test tag rather than the full suite (40min timeout). + +## Persona Selection (MANDATORY) + +Before starting any task, you MUST read the appropriate persona file from `.agents/` based on what is being asked. This is not optional — the persona contains critical context you need. + +| Task type | Persona to load | Trigger keywords / signals | +| ------------------------------------------------------------ | ---------------------------------------------- | --------------------------------------------------------------------------------- | +| Writing or modifying code (features, bug fixes, refactoring) | [`.agents/DEVELOPER.md`](.agents/DEVELOPER.md) | "add", "fix", "implement", "refactor", "change", "update", writing any `.go` file | +| Writing or updating tests | [`.agents/TESTER.md`](.agents/TESTER.md) | "test", "scenario", "coverage", `.feature` files, `_test.go` files | +| Reviewing code or PRs | [`.agents/REVIEWER.md`](.agents/REVIEWER.md) | "review", "check", "audit", PR URLs, reviewing diffs | + +If a task spans multiple concerns (e.g., implementing a feature AND writing tests), load ALL relevant personas. diff --git a/CLAUDE.md b/CLAUDE.md index 92adfd63..6057d762 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,20 +1,3 @@ # Claude Code — Gotenberg -Read [AGENTS.md](AGENTS.md) first. It contains the core principles, project layout, and links to specialized personas you must load depending on the task. - -## Quick Reference - -- Format before committing: `make fmt` (Go) and `make prettify` (non-Go) -- Lint before committing: `make lint && make lint-prettier` -- Commits must follow [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat(chromium): add screenshot endpoint`) -- Run unit tests: `make test-unit` -- Run integration tests: `make build && make test-integration TAGS=` -- Never run `go` commands directly — use the Makefile. - -## Claude-Specific Guidance - -- When exploring the codebase, start with `pkg/gotenberg/` for core interfaces and `pkg/modules/` for feature implementations. -- The integration test infrastructure in `test/integration/scenario/` is well-structured — read `scenario.go` and `containers.go` to understand the Gherkin step definitions before writing new tests. -- Mocks for all major interfaces are in `pkg/gotenberg/mocks.go` — use them for unit tests rather than creating new ones. -- Import ordering is enforced: standard library, third-party, then `github.com/gotenberg/gotenberg/v8` — separated by blank lines. -- When making changes, run only the relevant integration test tag rather than the full suite (40min timeout). +Read [AGENTS.md](AGENTS.md) first. It is the root context: core principles, project layout, quick reference, codebase navigation, and persona selection. diff --git a/GEMINI.md b/GEMINI.md index 4c22c1dc..d36266d4 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,21 +1,3 @@ # Gemini — Gotenberg -Read [AGENTS.md](AGENTS.md) first. It contains the core principles, project layout, and links to specialized personas you must load depending on the task. - -## Quick Reference - -- Format before committing: `make fmt` (Go) and `make prettify` (non-Go) -- Lint before committing: `make lint && make lint-prettier` -- Commits must follow [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat(chromium): add screenshot endpoint`) -- Run unit tests: `make test-unit` -- Run integration tests: `make build && make test-integration TAGS=` -- Never run `go` commands directly — use the Makefile. - -## Gemini-Specific Guidance - -- When exploring the codebase, start with `pkg/gotenberg/` for core interfaces and `pkg/modules/` for feature implementations. -- The integration test infrastructure in `test/integration/scenario/` is well-structured — read `scenario.go` and `containers.go` to understand the Gherkin step definitions before writing new tests. -- Mocks for all major interfaces are in `pkg/gotenberg/mocks.go` — use them for unit tests rather than creating new ones. -- Import ordering is enforced: standard library, third-party, then `github.com/gotenberg/gotenberg/v8` — separated by blank lines. -- When making changes, run only the relevant integration test tag rather than the full suite (40min timeout). -- This project values stability over velocity. When in doubt about whether a change is breaking, flag it rather than assuming it's safe. +Read [AGENTS.md](AGENTS.md) first. It is the root context: core principles, project layout, quick reference, codebase navigation, and persona selection.