feat: PMM-15088 ai guidelines #5409
+199
−21
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| --- | ||
| description: PMM — read AGENTS.md before any code change | ||
| alwaysApply: true | ||
| --- | ||
|
|
||
| # PMM agent entrypoint | ||
|
|
||
| Before planning, implementing, or reviewing changes in this repository, **read and follow** `AGENTS.md` at the repo root — including its component guide table and linked process docs. | ||
|
|
||
| Do **not** skip this because the task looks small (CI fix, one-file bug, etc.). State which guides you read when you start. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| Read [AGENTS.md](../AGENTS.md) at the repository root before suggesting or applying changes. | ||
|
|
||
| For each area you edit, also read the component `AGENTS.md` listed in that file's component guide table. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,8 +1,20 @@ | ||||||
| # PMM Development Guide for AI Agents | ||||||
|
|
||||||
| ## How AI tools load this document | ||||||
|
|
||||||
| This file is the **single authoritative entry point** for AI agents. Tools are wired to it as follows: | ||||||
|
|
||||||
| | Tool | Entry file | | ||||||
| |------|------------| | ||||||
| | **Cursor** | `.cursor/rules/pmm-agents-entrypoint.mdc` (`alwaysApply: true`) → read this file | | ||||||
| | **Claude Code** | [CLAUDE.md](CLAUDE.md) → read this file | | ||||||
| | **GitHub Copilot** | [.github/copilot-instructions.md](.github/copilot-instructions.md) → read this file | | ||||||
|
|
||||||
| Local-only AI skills under `.claude/` and other `.cursor/` paths remain gitignored for personal experimentation. | ||||||
|
|
||||||
| ## Maintaining This Document | ||||||
|
|
||||||
| **You are responsible for keeping this file accurate.** After completing work, check whether any of these apply: | ||||||
|
|
||||||
| - Added, removed, or renamed a top-level directory or component | ||||||
| - Added or removed a per-component `AGENTS.md` | ||||||
|
|
@@ -18,7 +30,14 @@ Do **not** update this file for routine code changes (bug fixes, minor feature i | |||||
|
|
||||||
| ## How This Documentation Is Organized | ||||||
|
|
||||||
| This guide provides the product-wide overview, architecture, domain model, conventions, and cross-links to component-specific guides. | ||||||
|
|
||||||
| | Audience | Location | | ||||||
| |----------|----------| | ||||||
| | Human contributors | [`CONTRIBUTING.md`](CONTRIBUTING.md), [`docs/process/`](docs/process/) | | ||||||
| | AI agents | This file + component `AGENTS.md` guides | | ||||||
|
|
||||||
| This file **summarizes and links** process docs; it does not replace them. Pull out operational rules here only when agents routinely get them wrong. | ||||||
|
|
||||||
| ### Component Guides | ||||||
|
|
||||||
|
|
@@ -40,6 +59,152 @@ Each PMM component has a dedicated guide with architecture, directory structure, | |||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## How AI agents should work in this repo | ||||||
|
|
||||||
| The **`AGENTS.md` hierarchy is the single source of truth** for agents. Read the matching component guide before editing. | ||||||
|
|
||||||
| Follow the sections through [Git and pull request checklist](#git-and-pull-request-checklist) every time you change code. Skim [Product Overview](#product-overview) and below when you need context. | ||||||
|
|
||||||
| ### Workflow | ||||||
|
|
||||||
| 1. Identify which component your change touches (`managed`, `ui`, `api`, `agent`, …). | ||||||
| 2. Read that component's `AGENTS.md` before planning or editing. | ||||||
| 3. Prefer minimal, focused diffs; match surrounding style and patterns. | ||||||
| 4. After `.proto` or reform model changes: run `make gen` from the repo root. | ||||||
| 5. Run the **smallest test set** that covers your change (see [Testing decision tree](#testing-decision-tree)). | ||||||
| 6. Run the **matching linter** before calling work PR-ready (see [Linting decision tree](#linting-decision-tree)). For Go/API-only changes, step 7 covers this. | ||||||
| 7. For Go/API changes: run `make prepare-pr` (gen + license check + Go lint + format + `go mod tidy` — subsumes step 6 for Go). | ||||||
| 8. Update `AGENTS.md` (and the component guide) only if you changed structure, conventions, or workflows. | ||||||
|
|
||||||
| ### Don'ts | ||||||
|
|
||||||
| - Don't edit generated files (`.pb.go`, `.pb.gw.go`, `*_reform.go`, `*.pb.validate.go`, swagger specs, `json/client/`). | ||||||
| - Don't use `gorm` in pmm-managed — **reform only**. | ||||||
| - Don't amend/squash commits locally to address review feedback; push **new commits** ([`docs/process/GIT_AND_GITHUB.md`](docs/process/GIT_AND_GITHUB.md)). | ||||||
| - Don't force-push to `main`/`v3`. | ||||||
| - Don't skip the Feature Build link in PR descriptions for user-facing changes ([`.github/pull_request_template.md`](.github/pull_request_template.md)). | ||||||
| - Don't run the full repo linter on every tiny edit; do run the **targeted linter** for what you changed, and run `make prepare-pr` before declaring Go/API work PR-ready. | ||||||
| - Don't write unit tests that call external services — use mocks or `/api-tests/` instead. | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## PMM-specific choices (agents often get wrong) | ||||||
|
|
||||||
| These differ from generic Go/React advice. Match **surrounding code** in the file you edit; when in doubt, follow the component guide. | ||||||
|
|
||||||
| - **DB (managed):** reform only — never gorm or other ORMs ([`managed/AGENTS.md`](managed/AGENTS.md)) | ||||||
| - **Unit tests (managed):** `go-sqlmock` by default — use `testdb.Open` only when migrations or fixtures are what you're testing ([`managed/AGENTS.md`](managed/AGENTS.md)) | ||||||
| - **API errors (Go):** `status.Error()` with gRPC codes — not ad-hoc HTTP errors in service layers | ||||||
| - **Logging (Go):** `logrus` with `*logrus.Entry` and structured fields — not `fmt.Printf` | ||||||
| - **Mocks (Go):** small interfaces in `deps.go` + mockery — not hand-rolled fakes for every dependency | ||||||
| - **UI server state:** TanStack Query hooks in `ui/apps/pmm/src/hooks/api/` — not `useEffect` + `fetch` in components ([`ui/AGENTS.md`](ui/AGENTS.md)) | ||||||
| - **UI client state:** React Context for auth/settings — not Redux or another global store | ||||||
| - **UI components:** MUI + `@percona/percona-ui`, theme-aware `sx` — not ad-hoc CSS | ||||||
| - **UI wire format:** camelCase in TypeScript; JSON on the wire is snake_case (`axios-case-converter` in `ui/apps/pmm/src/api/api.ts`) | ||||||
| - **Generated code:** edit `.proto` / reform models / interfaces — run `make gen`; never hand-edit `*.pb.go`, `*_reform.go`, swagger clients | ||||||
|
|
||||||
| Mechanical style (imports, formatting, ESLint rules) is enforced by `make check`, `cd ui && make lint`, and CI — see [Linting decision tree](#linting-decision-tree). | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Testing decision tree | ||||||
|
|
||||||
| PMM has three test layers ([`CONTRIBUTING.md`](CONTRIBUTING.md)): unit, API integration, and e2e (in [pmm-qa](https://github.com/percona/pmm-qa)). Use the smallest scope that validates your change: | ||||||
|
|
||||||
| | If you changed… | Run | | ||||||
| |-----------------|-----| | ||||||
| | Go unit logic in one package | `go test ./path/to/pkg/...` or `make test` in that component directory | | ||||||
| | Shared/API packages (not managed/admin/agent) | `make test-common` from repo root | | ||||||
| | `managed/models` or DB schema/migrations | Unit tests in `managed/`; use `testdb.Open` only when fixtures or migrations matter ([`managed/AGENTS.md`](managed/AGENTS.md)) | | ||||||
| | `.proto` or gRPC/REST definitions | `make gen`, then `make check`; update handlers in `managed/` and UI hooks if user-facing | | ||||||
| | REST behavior end-to-end | `make env-up`, then `make api-test` ([`api-tests/AGENTS.md`](api-tests/AGENTS.md)) | | ||||||
| | UI (`ui/apps/pmm`) | `cd ui && make lint && make test` | | ||||||
| | Grafana dashboard JSON (`dashboards/dashboards/`) | `python3 dashboards/misc/cleanup-dash.py --check-only <file>` (or run cleanup without `--check-only`); CI enforces this in `dashboards.yml` ([`dashboards/dashboards/AGENTS.md`](dashboards/dashboards/AGENTS.md)) | | ||||||
| | User-visible feature / bugfix | Create or update a Feature Build; link it in the PR ([`CONTRIBUTING.md`](CONTRIBUTING.md#feature-build)) | | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Linting decision tree | ||||||
|
|
||||||
| CI runs separate linters per area. `make prepare-pr` covers **Go only** — it does not lint UI or dashboards. | ||||||
|
|
||||||
| | If you changed… | Run | | ||||||
| |-----------------|-----| | ||||||
| | Go backend (`managed/`, `agent/`, `admin/`, `qan-api2/`, `vmproxy/`, shared packages) | `make prepare-pr` from repo root (or `make check` after `make gen` for a quicker pass) | | ||||||
| | `.proto` only | `make gen`, then `make check` (`buf lint`, `golangci-lint`, `go-sumtype`) | | ||||||
| | UI (`ui/apps/pmm`, `ui/packages/shared`) | `cd ui && make lint` (ESLint; same as CI `ui.yml`) | | ||||||
| | Grafana dashboard JSON (`dashboards/dashboards/`) | `python3 dashboards/misc/cleanup-dash.py --check-only <file>` before commit (CI `dashboards.yml`; no separate ESLint) | | ||||||
| | Grafana plugin / QAN app (`dashboards/pmm-app`) | `cd dashboards/pmm-app && yarn lint:check` (and `yarn typecheck` if TypeScript changed) | | ||||||
| | Before any PR | Run the row(s) that match **every** area you touched; fix errors, not just warnings, unless CI allows them | | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Change impact recipes | ||||||
|
|
||||||
| Recurring tasks — follow in order before opening a PR. | ||||||
|
|
||||||
| ### Adding a REST API endpoint | ||||||
|
|
||||||
| 1. Edit `api/<domain>/v1/*.proto` (HTTP annotations, validation rules). | ||||||
| 2. Run `make gen`. | ||||||
| 3. Implement handler/service logic in `managed/services/<domain>/`. | ||||||
| 4. Add or extend tests in `api-tests/<domain>/`. | ||||||
| 5. If UI-facing: add API module in `ui/apps/pmm/src/api/` and TanStack Query hooks in `ui/apps/pmm/src/hooks/api/`. | ||||||
| 6. If public API docs change: update [`docs/api/`](docs/api/) (PR template checkbox). | ||||||
|
|
||||||
| ### Adding a DB table or migration | ||||||
|
|
||||||
| 1. Add a versioned migration in `managed/models/database.go`. | ||||||
| 2. Add or update the reform model; run `//go:generate` or `make gen`. | ||||||
| 3. Add CRUD helpers in `*_helpers.go` or `*_crud.go` as surrounding code does. | ||||||
| 4. Prefer `go-sqlmock` for unit tests; use `testdb.Open` when SQL/migration behavior must be verified. | ||||||
|
|
||||||
| ### Adding a UI page or settings section | ||||||
|
|
||||||
| 1. Read [`ui/AGENTS.md`](ui/AGENTS.md). | ||||||
| 2. Add route in `ui/apps/pmm/src/router.tsx` if needed. | ||||||
| 3. API functions in `ui/apps/pmm/src/api/`; TanStack Query hooks in `ui/apps/pmm/src/hooks/api/`. | ||||||
| 4. Co-locate Vitest tests (`*.test.ts` / `*.test.tsx`). | ||||||
| 5. Run `cd ui && make lint && make test` before opening a PR. | ||||||
| 6. JSON on the wire is **snake_case** (`axios-case-converter`); TypeScript uses **camelCase**. | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Git and pull request checklist | ||||||
|
|
||||||
| Full rules: [`docs/process/GIT_AND_GITHUB.md`](docs/process/GIT_AND_GITHUB.md). For commits and PR titles, use **[Conventional Commits](https://www.conventionalcommits.org/)** (`type(scope): summary`) — not the `PMM-XXXX` title style from the process doc. When opening PRs to the upstream Percona repo, confirm with reviewers if they expect conventional titles or `PMM-XXXX` titles from the process doc. | ||||||
|
Member
There was a problem hiding this comment. We don't follow |
||||||
|
|
||||||
| | Item | Rule | | ||||||
| |------|------| | ||||||
| | Branch name | `PMM-1234-short-description` (lowercase, dashes) | | ||||||
| | Commit title | `type(scope): short imperative summary` — e.g. `feat(ui): add OTEL settings scroll`, `fix(managed): normalize log parser YAML` | | ||||||
| | PR title | Same format as commit title (squash merge uses the PR title) | | ||||||
| | Types | `feat` (feature), `fix` (bug), `chore` (deps, lint, tooling), `refactor`, `test`, `docs` | | ||||||
| | Scope | Optional but preferred: `ui`, `managed`, `api`, `agent`, `adre`, `investigations`, `dashboards`, … | | ||||||
| | Ticket | Put `PMM-XXXX` in the branch name and/or PR body — not required in the title | | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
| | Review fixes | New commit per round — do not amend and force-push | | ||||||
| | Merge | Squash and merge on GitHub | | ||||||
| | PR body | What/why, Feature Build link for features/fixes/improvements, link related PRs | | ||||||
| | API changes | Check API docs updated if endpoints changed | | ||||||
| | Before review | Tests and linters pass for every area touched (see [Linting decision tree](#linting-decision-tree); Go/API: `make prepare-pr`; UI: `cd ui && make lint`) | | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Feature areas | ||||||
|
|
||||||
| Some areas span multiple directories. When working on them, read **both** the component guide and the paths below. These paths exist on branches that land the work (e.g. ADRE, OTEL); if a directory is missing on your branch, skip it. | ||||||
|
|
||||||
| | Area | Backend | UI | Notes | | ||||||
| |------|---------|-----|-------| | ||||||
| | **ADRE / AI Assistant** | `managed/services/adre/` | `ui/apps/pmm/src/pages/adre/`, `components/adre/` | HolmesGPT integration, chat, usage | | ||||||
|
Member
There was a problem hiding this comment. What is ADRE? Where does it come from?
Contributor
Author
There was a problem hiding this comment. right I had it in my branch but not committed yet. will remove. |
||||||
| | **Investigations** | `managed/services/investigations/` | `ui/apps/pmm/src/pages/investigations/` | AI investigation workflows | | ||||||
| | **OTEL** | `managed/otel/`, `dev/otel/` | Settings → OTEL tab | Log collectors, parser presets | | ||||||
|
Member
There was a problem hiding this comment. We don't have anything called OTEL in our repo yet.
Contributor
Author
There was a problem hiding this comment. right I had it in my branch but not committed yet. will remove. |
||||||
| | **User docs** | — | — | [`documentation/`](documentation/) (MkDocs), not [`docs/process/`](docs/process/) | | ||||||
|
Member
There was a problem hiding this comment. No, the user-facing documentation is located in "documentation/docs". |
||||||
|
|
||||||
| When these areas grow large enough to need their own conventions, extend [`managed/AGENTS.md`](managed/AGENTS.md) and [`ui/AGENTS.md`](ui/AGENTS.md) — do not duplicate architecture here. | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Product Overview | ||||||
|
|
||||||
| Percona Monitoring and Management (PMM) is an open-source database monitoring solution for MySQL, MongoDB, PostgreSQL, ProxySQL, HAProxy, Valkey, and cloud databases (AWS RDS, Azure). It uses a **client-server architecture** where lightweight agents on monitored hosts collect metrics and query analytics data, sending them to a central server for storage, alerting, and visualization. | ||||||
|
|
@@ -100,21 +265,7 @@ Relationships: | |||||
|
|
||||||
| ## Repository Map | ||||||
|
|
||||||
| Core components and per-area guides: see [Component Guides](#component-guides) above. | ||||||
|
|
||||||
| ### Supporting Directories | ||||||
|
|
||||||
|
|
@@ -228,12 +379,13 @@ All long-running daemons expose on `127.0.0.1`: | |||||
| | `make env-up` | Start development container (PMM Server) | | ||||||
| | `make env-up-rebuild` | Rebuild development container from scratch | | ||||||
| | `make gen` | Generate all code (protobuf, reform, mocks, format) | | ||||||
| | `make check` | Run Go/API linters (buf, golangci-lint, go-sumtype) | | ||||||
| | `make format` | Format code (gofumpt, goimports, gci) | | ||||||
| | `make release` | Build all binaries (agent, admin, managed, qan-api2) | | ||||||
| | `make test-common` | Run common unit tests | | ||||||
| | `make api-test` | Run API integration tests | | ||||||
| | `make prepare-pr` | Go/API pre-PR pipeline: `gen` + `check-all` (license + linters) + `format` + `go mod tidy` | | ||||||
| | `cd ui && make lint` | ESLint for PMM UI (required for UI changes; not part of `prepare-pr`) | | ||||||
|
|
||||||
| ## Key Files to Reference | ||||||
|
|
||||||
|
|
||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # Claude Code — PMM | ||
|
|
||
| Before planning or editing code in this repository: | ||
|
|
||
| 1. Read [AGENTS.md](AGENTS.md) in full. | ||
| 2. Read the component `AGENTS.md` for every path you touch (see the table in `AGENTS.md`). | ||
| 3. Follow [docs/process/GIT_AND_GITHUB.md](docs/process/GIT_AND_GITHUB.md) for commits and PRs. | ||
|
|
||
| `AGENTS.md` is the single source of truth. Do not rely on memory or generic assumptions about PMM. | ||
|
|
||
| When starting work, briefly state which `AGENTS.md` files you read. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We have settled on not committing anything other than
AGENTS.mdto this repo, because it's the only file that almost every AI tool knows about and reads. We can call it an (almost) universally accepted standard.The reasons are:
AGENTS.mdTherefore, I suggest we only contribute and review our AGENTS.md, which should be good for every other AI tool.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we need pointers for these tools to start using Agents.md , because example my cursor was not using it at all without that rule.