Skip to content

PMM-7 - Add AI agents development guide#892

Draft
ondrejpatocka wants to merge 1 commit into
mainfrom
PMM-7---Add-AI-agents-development-guide
Draft

PMM-7 - Add AI agents development guide#892
ondrejpatocka wants to merge 1 commit into
mainfrom
PMM-7---Add-AI-agents-development-guide

Conversation

@ondrejpatocka
Copy link
Copy Markdown

@ondrejpatocka ondrejpatocka commented Apr 7, 2026

Summary

  • Add AGENTS.md — a comprehensive development guide for AI coding agents, documenting the Percona/PMM delta over upstream Grafana (architecture, directory structure, state management, API layer, conventions, configuration, dev workflow, and testing).
  • Add thin entry-point shims so each major AI assistant auto-discovers the guide through its native convention:
    • CLAUDE.md — Claude Code auto-discovery
    • .cursorrules — Cursor auto-discovery
    • .github/copilot-instructions.md — GitHub Copilot auto-discovery
  • Include a self-maintenance policy ("Keeping This Document Current") that instructs agents to update AGENTS.md whenever they add or change PMM features, routes, plugins, Redux slices, API services, CI configs, or environment variables — preventing the guide from going stale over time.

Motivation

AI agents (Claude Code, Cursor, GitHub Copilot, etc.) lack awareness of the Percona fork's conventions, integration points, and // @PERCONA tagging discipline. Without explicit guidance they tend to scatter PMM code across upstream Grafana directories, miss existing API patterns, or break rebase-friendly conventions. A single authoritative document — automatically loaded by each tool — gives every agent session the right context from the start.

What's included

File Purpose
AGENTS.md Full guide: PMM context, fork rules, architecture tables (frontend/backend/CI), directory tree, state management, API layer, do/don't conventions, configuration, dev workflow, testing, key file references
CLAUDE.md Shim — redirects Claude Code to AGENTS.md, repeats PMM context
.cursorrules Shim — redirects Cursor to AGENTS.md, repeats PMM context
.github/copilot-instructions.md Shim — redirects GitHub Copilot to AGENTS.md, repeats PMM context

@ondrejpatocka ondrejpatocka force-pushed the PMM-7---Add-AI-agents-development-guide branch from 788486f to 4555582 Compare April 8, 2026 09:23
@matejkubinec
Copy link
Copy Markdown
Collaborator

@ondrejpatocka since grafana has their own agents.md, I think it would be good to have a AGENTS.PERCONA.MD (or similar approach) to not to cause issues during pulls.

@ondrejpatocka ondrejpatocka self-assigned this Apr 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants