Skip to content

Commit 78e9e87

Browse files
zeitlingerzeitlinger
authored
chore: rename CLAUDE.md to AGENTS.md (#1907)
## Summary - Move AI coding agent instructions from CLAUDE.md to AGENTS.md, the open standard ([Linux Foundation / Agentic AI Foundation](https://github.com/anthropics/agents-md)) supported by Cursor, Copilot, Codex, Gemini CLI, and others - CLAUDE.md now imports AGENTS.md via `@AGENTS.md` so Claude Code continues to work ## Test plan - [ ] Open repo in Claude Code and verify instructions are loaded - [ ] Verify AGENTS.md content matches the original CLAUDE.md --------- Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
1 parent e2c691e commit 78e9e87

File tree

2 files changed

+176
-132
lines changed

2 files changed

+176
-132
lines changed

‎AGENTS.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to AI coding agents when working
4+
with code in this repository.
5+
6+
## Build Commands
7+
8+
This project uses Maven with mise for task automation.
9+
The Maven wrapper (`./mvnw`) is used for all builds.
10+
11+
```bash
12+
# Full CI build (clean + install + all checks)
13+
mise run ci
14+
15+
# Quick compile without tests or checks (fastest)
16+
mise run compile
17+
18+
# Run unit tests only (skips formatting/coverage/checkstyle)
19+
mise run test
20+
21+
# Run all tests including integration tests
22+
mise run test-all
23+
24+
# Format code with Google Java Format
25+
mise run format
26+
# or directly: ./mvnw spotless:apply
27+
28+
# Run a single test class
29+
./mvnw test -Dtest=CounterTest \
30+
-Dspotless.check.skip=true \
31+
-Dcoverage.skip=true -Dcheckstyle.skip=true
32+
33+
# Run a single test method
34+
./mvnw test -Dtest=CounterTest#testIncrement \
35+
-Dspotless.check.skip=true \
36+
-Dcoverage.skip=true -Dcheckstyle.skip=true
37+
38+
# Run tests in a specific module
39+
./mvnw test -pl prometheus-metrics-core \
40+
-Dspotless.check.skip=true \
41+
-Dcoverage.skip=true -Dcheckstyle.skip=true
42+
43+
# Regenerate protobuf classes (after protobuf dep update)
44+
mise run generate
45+
```
46+
47+
## Architecture
48+
49+
The library follows a layered architecture where metrics
50+
flow from core types through a registry to exporters:
51+
52+
```text
53+
prometheus-metrics-core (user-facing API)
54+
│
55+
▼ collect()
56+
prometheus-metrics-model (immutable snapshots)
57+
│
58+
▼
59+
prometheus-metrics-exposition-formats
60+
│
61+
▼
62+
Exporters (httpserver, servlet, pushgateway, otel)
63+
```
64+
65+
### Key Modules
66+
67+
- **prometheus-metrics-core**: User-facing metric types
68+
(Counter, Gauge, Histogram, Summary, Info, StateSet).
69+
All metrics implement `Collector` with `collect()`.
70+
- **prometheus-metrics-model**: Internal read-only immutable
71+
snapshot types returned by `collect()`.
72+
Contains `PrometheusRegistry` for metric registration.
73+
- **prometheus-metrics-config**: Runtime configuration via
74+
properties files or system properties.
75+
- **prometheus-metrics-exposition-formats**: Converts
76+
snapshots to Prometheus exposition formats.
77+
- **prometheus-metrics-tracer**: Exemplar support with
78+
OpenTelemetry tracing integration.
79+
- **prometheus-metrics-simpleclient-bridge**: Allows legacy
80+
simpleclient 0.16.0 metrics to work with the new registry.
81+
82+
### Instrumentation Modules
83+
84+
Pre-built instrumentations:
85+
`prometheus-metrics-instrumentation-jvm`, `-caffeine`,
86+
`-guava`, `-dropwizard`, `-dropwizard5`.
87+
88+
## Code Style
89+
90+
- **Formatter**: Google Java Format (enforced via Spotless)
91+
- **Line length**: 100 characters
92+
(enforced for ALL files including Markdown, Java, YAML)
93+
- **Indentation**: 2 spaces
94+
- **Static analysis**: `Error Prone` with NullAway
95+
(`io.prometheus.metrics` package)
96+
- **Logger naming**: Logger fields must be named `logger`
97+
(not `log`, `LOG`, or `LOGGER`)
98+
- **Assertions in tests**: Use static imports from AssertJ
99+
(`import static ...Assertions.assertThat`)
100+
- **Empty catch blocks**: Use `ignored` as the variable name
101+
- **Markdown code blocks**: Always specify language
102+
(e.g., ` ```java`, ` ```bash`, ` ```text`)
103+
104+
## Linting and Validation
105+
106+
**CRITICAL**: These checks MUST be run before creating any
107+
commits. CI will fail if these checks fail.
108+
109+
### Java Files
110+
111+
- **ALWAYS** run `mise run build` after modifying Java files
112+
to ensure:
113+
- Code formatting (Spotless with Google Java Format)
114+
- Static analysis (`Error Prone` with NullAway)
115+
- Checkstyle validation
116+
- Build succeeds (tests are skipped;
117+
run `mise run test` or `mise run test-all` for tests)
118+
119+
### Non-Java Files (Markdown, YAML, JSON, shell scripts)
120+
121+
- **ALWAYS** run `mise run lint` after modifying non-Java
122+
files (runs super-linter + link checking + BOM check)
123+
- `mise run fix` autofixes linting issues
124+
- Super-linter will **autofix** many issues
125+
(formatting, trailing whitespace, etc.)
126+
- It only reports ERROR-level issues
127+
(configured via `LOG_LEVEL=ERROR` in
128+
`.github/super-linter.env`)
129+
- Common issues caught:
130+
- Lines exceeding 100 characters in Markdown files
131+
- Missing language tags in fenced code blocks
132+
- Table formatting issues
133+
- YAML/JSON syntax errors
134+
135+
### Running Linters
136+
137+
```bash
138+
# After modifying Java files (run BEFORE committing)
139+
mise run build
140+
141+
# After modifying non-Java files (run BEFORE committing)
142+
mise run lint
143+
# or to autofix: mise run fix
144+
```
145+
146+
## Testing
147+
148+
- JUnit 5 (Jupiter) with `@Test` annotations
149+
- AssertJ for fluent assertions
150+
- Mockito for mocking
151+
- **Test visibility**: Test classes and test methods must be
152+
package-protected (no `public` modifier)
153+
- Integration tests are in `integration-tests/` and run
154+
during `verify` phase
155+
- Acceptance tests use OATs framework:
156+
`mise run acceptance-test`
157+
158+
## Documentation
159+
160+
- Docs live under `docs/content/` and use `$version` as a
161+
placeholder for the library version
162+
- When publishing GitHub Pages,
163+
`mise run set-release-version-github-pages` replaces
164+
`$version` with the latest Git tag across all
165+
`docs/content/**/*.md` files
166+
(the published site is not versioned)
167+
- Use `$version` for the Prometheus client version and
168+
`$otelVersion-alpha` for the OTel instrumentation
169+
version — never hardcode them
170+
171+
## Java Version
172+
173+
Source compatibility: Java 8. Tests run on Java 25
174+
(configured in `mise.toml`).

‎CLAUDE.md‎

Lines changed: 2 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -1,133 +1,3 @@
1-
# CLAUDE.md
1+
<!-- markdownlint-disable-file -->
22

3-
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4-
5-
## Build Commands
6-
7-
This project uses Maven with mise for task automation. The Maven wrapper (`./mvnw`) is used for all builds.
8-
9-
```bash
10-
# Full CI build (clean + install + all checks)
11-
mise run ci
12-
13-
# Quick compile without tests or checks (fastest for development)
14-
mise run compile
15-
16-
# Run unit tests only (skips formatting/coverage/checkstyle checks)
17-
mise run test
18-
19-
# Run all tests including integration tests
20-
mise run test-all
21-
22-
# Format code with Google Java Format
23-
mise run format
24-
# or directly: ./mvnw spotless:apply
25-
26-
# Run a single test class
27-
./mvnw test -Dtest=CounterTest -Dspotless.check.skip=true -Dcoverage.skip=true -Dcheckstyle.skip=true
28-
29-
# Run a single test method
30-
./mvnw test -Dtest=CounterTest#testIncrement -Dspotless.check.skip=true -Dcoverage.skip=true -Dcheckstyle.skip=true
31-
32-
# Run tests in a specific module
33-
./mvnw test -pl prometheus-metrics-core -Dspotless.check.skip=true -Dcoverage.skip=true -Dcheckstyle.skip=true
34-
35-
# Regenerate protobuf classes (after protobuf dependency update)
36-
mise run generate
37-
```
38-
39-
## Architecture
40-
41-
The library follows a layered architecture where metrics flow from core types through a registry to exporters:
42-
43-
```
44-
prometheus-metrics-core (user-facing API)
45-
│
46-
▼ collect()
47-
prometheus-metrics-model (immutable snapshots)
48-
│
49-
▼
50-
prometheus-metrics-exposition-formats (text/protobuf/OpenMetrics)
51-
│
52-
▼
53-
Exporters (httpserver, servlet, pushgateway, opentelemetry)
54-
```
55-
56-
### Key Modules
57-
58-
- **prometheus-metrics-core**: User-facing metric types (Counter, Gauge, Histogram, Summary, Info, StateSet). All metrics implement the `Collector` interface with a `collect()` method.
59-
- **prometheus-metrics-model**: Internal read-only immutable snapshot types returned by `collect()`. Contains `PrometheusRegistry` for metric registration.
60-
- **prometheus-metrics-config**: Runtime configuration via properties files or system properties.
61-
- **prometheus-metrics-exposition-formats**: Converts snapshots to Prometheus exposition formats.
62-
- **prometheus-metrics-tracer**: Exemplar support with OpenTelemetry tracing integration.
63-
- **prometheus-metrics-simpleclient-bridge**: Allows legacy simpleclient 0.16.0 metrics to work with the new registry.
64-
65-
### Instrumentation Modules
66-
67-
Pre-built instrumentations: `prometheus-metrics-instrumentation-jvm`, `-caffeine`, `-guava`, `-dropwizard`, `-dropwizard5`.
68-
69-
## Code Style
70-
71-
- **Formatter**: Google Java Format (enforced via Spotless)
72-
- **Line length**: 100 characters (enforced for ALL files including Markdown, Java, YAML, etc.)
73-
- **Indentation**: 2 spaces
74-
- **Static analysis**: Error Prone with NullAway (`io.prometheus.metrics` package)
75-
- **Logger naming**: Logger fields must be named `logger` (not `log`, `LOG`, or `LOGGER`)
76-
- **Assertions in tests**: Use static imports from AssertJ (`import static org.assertj.core.api.Assertions.assertThat`)
77-
- **Empty catch blocks**: Use `ignored` as the exception variable name
78-
- **Markdown code blocks**: Always specify language (e.g., ` ```java`, ` ```bash`, ` ```text`)
79-
80-
## Linting and Validation
81-
82-
**CRITICAL**: These checks MUST be run before creating any commits. CI will fail if these checks fail.
83-
84-
### Java Files
85-
86-
- **ALWAYS** run `mise run build` after modifying Java files to ensure:
87-
- Code formatting (Spotless with Google Java Format)
88-
- Static analysis (Error Prone with NullAway)
89-
- Checkstyle validation
90-
- Build succeeds (tests are skipped; run `mise run test` or `mise run test-all` to execute tests)
91-
92-
### Non-Java Files (Markdown, YAML, JSON, shell scripts, etc.)
93-
94-
- **ALWAYS** run `mise run lint` after modifying non-Java files
95-
(runs super-linter + link checking + BOM check)
96-
- `mise run fix` auto-fixes lint issues
97-
- Super-linter will **auto-fix** many issues (formatting, trailing whitespace, etc.)
98-
- It only reports ERROR-level issues (configured via `LOG_LEVEL=ERROR` in `.github/super-linter.env`)
99-
- Common issues caught:
100-
- Lines exceeding 100 characters in Markdown files
101-
- Missing language tags in fenced code blocks
102-
- Table formatting issues
103-
- YAML/JSON syntax errors
104-
105-
### Running Linters
106-
107-
```bash
108-
# After modifying Java files (run BEFORE committing)
109-
mise run build
110-
111-
# After modifying non-Java files (run BEFORE committing)
112-
mise run lint
113-
# or to auto-fix: mise run fix
114-
```
115-
116-
## Testing
117-
118-
- JUnit 5 (Jupiter) with `@Test` annotations
119-
- AssertJ for fluent assertions
120-
- Mockito for mocking
121-
- **Test visibility**: Test classes and test methods must be package-protected (no `public` modifier)
122-
- Integration tests are in `integration-tests/` and run during `verify` phase
123-
- Acceptance tests use OATs framework: `mise run acceptance-test`
124-
125-
## Documentation
126-
127-
- Docs live under `docs/content/` and use `$version` as a placeholder for the library version
128-
- When publishing GitHub Pages, `mise run set-release-version-github-pages` replaces `$version` with the latest git tag across all `docs/content/**/*.md` files (the published site is not versioned)
129-
- Use `$version` for the Prometheus client version and `$otelVersion-alpha` for the OTel instrumentation version — never hardcode them
130-
131-
## Java Version
132-
133-
Source compatibility: Java 8. Tests run on Java 25 (configured in `mise.toml`).
3+
@AGENTS.md

0 commit comments

Comments
 (0)