This is an automated email from the ASF dual-hosted git repository.
He-Pin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pekko-projection.git
The following commit(s) were added to refs/heads/main by this push:
new 967ffcbc docs: add AGENTS.md and CLAUDE.md for AI coding agents (#522)
967ffcbc is described below
commit 967ffcbcf81560889598dd8bcb40ac6aa0a2102b
Author: He-Pin(kerr) <[email protected]>
AuthorDate: Mon Jun 15 02:04:24 2026 +0800
docs: add AGENTS.md and CLAUDE.md for AI coding agents (#522)
Motivation:
AI coding agents benefit from project-specific instructions to follow
conventions, run correct validation, and produce consistent PRs.
Modification:
Add AGENTS.md with comprehensive rules (worktree, licensing, PR,
formatting, validation, test, code, CI, commit format) and CLAUDE.md
with a pre-PR verification checklist.
Result:
AI agents working on this repository will follow established
conventions and produce higher-quality contributions.
Tests:
Not run - docs only
References:
None - AI agent configuration
---
AGENTS.md | 242 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
CLAUDE.md | 19 +++++
2 files changed, 261 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..dcb79db5
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,242 @@
+# Agent Rules for Apache Pekko Projection
+
+If this file conflicts with community conventions, update this file.
+
+## Worktree Rules
+
+- Base new work on `origin/main` unless the user or maintainer requests
another branch.
+- Keep every PR scoped to one change.
+- Do not mix behavior changes, formatting churn, dependency updates, and
unrelated cleanup.
+- Do not revert user changes or unrelated local changes.
+- Use `rg` or `rg --files` for repository searches.
+- Read neighboring code before editing.
+- Preserve existing license and copyright notices.
+- Do not add `@author` tags.
+- Follow the Licensing Rules below for every new file.
+
+## Licensing Rules
+
+- Do not hand-write or invent license headers. Let sbt manage them.
+- For new files, run `sbt headerCreateAll` to add the correct header. Do not
manually paste header text.
+- Run `sbt +headerCheckAll` to verify all files carry the expected header.
+- Existing files with copyright statements must keep those copyright
statements intact. Never delete or rewrite an existing copyright notice; only
add information.
+- New files containing new code must use the standard Apache license header.
Do not add the special Pekko header that mentions Akka unless you are copying
code from an existing Akka-derived file.
+- If you copy code from another file in this repository, preserve that file's
original headers in the new file.
+- If you copy code from an external project, do not commit it silently. Note
the source in the PR description so maintainers can verify license
compatibility and update `LICENSE` if needed.
+- `sbt headerCreateAll` does not know the origin of new code; you must still
record copied-code provenance in the PR.
+
+## PR Rules
+
+- Every non-doc-only PR must add or update a directional test.
+- Directional test: focused behavior or regression test with explicit
assertions.
+- Bug-fix tests must fail or expose the issue before the fix.
+- CI-flake tests must encode the intended ordering, scheduling, timeout, or
concurrency contract.
+- Documentation-only PRs must use `Tests: Not run - docs only`.
+- Behavior, configuration, public API, or operator changes must update docs.
+- Scala and Java DSL changes must keep API, docs, and tests in parity.
+- Public API, binary shape, serialization, or MiMa-sensitive internal changes
must preserve binary compatibility.
+- The GitHub `Check / Binary Compatibility` job must pass before merge.
+- Wire protocol changes must consider rolling upgrade compatibility.
+- Dependency changes must verify Apache-compatible licenses.
+- Projection handler changes must preserve at-least-once or exactly-once
semantics as documented.
+- Offset storage changes must consider backward compatibility with existing
offset tables.
+
+## Package Requirements
+
+### Coursier
+
+Install Coursier (`cs` command).
+
+On x86-64 (aka AMD64)
+```
+curl -fL
"https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-linux.gz"; | gzip
-d > cs
+```
+On ARM64
+```
+curl -fL
"https://github.com/VirtusLab/coursier-m1/releases/latest/download/cs-aarch64-pc-linux.gz";
| gzip -d > cs
+```
+
+### sbt
+
+```
+cs setup
+```
+
+### scalafmt
+
+```
+cs install scalafmt
+```
+
+## Formatting Rules
+
+- Prefer native scalafmt for changed Scala and SBT files when it is available.
+
+```shell
+git fetch origin main
+scalafmt --mode diff-ref=origin/main
+scalafmt --list --mode diff-ref=origin/main
+```
+
+- If native scalafmt is not installed, use the sbt scalafmt tasks or record
that scalafmt could not be run.
+
+```shell
+sbt scalafmtAll scalafmtSbt
+sbt scalafmtCheckAll scalafmtSbtCheck
+```
+
+- Use JDK 17 for Java formatter tasks.
+
+```shell
+export JAVA_HOME=$(/usr/libexec/java_home -v 17)
+export PATH="$JAVA_HOME/bin:$PATH"
+sbt javafmtAll
+```
+
+- Run header generation before PR.
+
+```shell
+sbt headerCreateAll
+```
+
+- Run checks when relevant.
+
+```shell
+sbt javafmtCheckAll
+sbt +headerCheckAll
+sbt checkCodeStyle
+```
+
+- Use `sbt sortImports` when imports change.
+- Do not rely on IDE formatting alone.
+- Do not commit unrelated formatting changes.
+
+## Validation Rules
+
+- Run the smallest focused test first.
+
+```shell
+sbt "module-name / Test / testOnly fully.qualified.SpecName"
+```
+
+- Run core tests.
+
+```shell
+sbt "core / Test / testOnly fully.qualified.SpecName"
+```
+
+- Compile examples to verify they remain valid.
+
+```shell
+sbt "examples / compile"
+```
+
+- Use JDK-specific configs when relevant.
+
+```shell
+sbt "module-name / TestJdk9 / testOnly fully.qualified.SpecName"
+```
+
+- Run PR impact validation for non-trivial code changes.
+
+```shell
+sbt validatePullRequest
+```
+
+- Set `PR_TARGET_BRANCH` only when the PR target is not `main`.
+
+```shell
+PR_TARGET_BRANCH=origin/example sbt validatePullRequest
+```
+
+- Run MiMa for public API, binary shape, serialization, or MiMa-sensitive
internal changes.
+
+```shell
+sbt +mimaReportBinaryIssues
+```
+
+- Do not mark a PR ready while the local MiMa run or the GitHub `Check /
Binary Compatibility` job is failing.
+- ALL reported MiMa issues must be fixed before creating or updating a PR. Do
not ignore or suppress MiMa warnings without explicit maintainer approval.
+- Run Paradox for documentation changes that touch project docs.
+
+```shell
+sbt docs/paradox
+```
+
+- Always run `git diff --check`.
+- Do not assume local tools such as `sbt` or `scalafmt` are installed; if a
required tool is missing, record the missing tool and skipped command in
`Tests`.
+- Skipped or environment-failed commands must be recorded in `Tests`.
+
+## Test Rules
+
+- Prefer deterministic tests over larger timeouts.
+- Avoid `Thread.sleep`.
+- Prefer probes, latches, stepped components, `within`, `remaining`, and
`remainingOrDefault`.
+- Keep `expectNoMessage` short and intentional.
+- Do not weaken assertions to hide production behavior.
+- Do not fix flakes only by increasing timeouts.
+- Projection tests must verify offset management behavior (at-least-once,
exactly-once).
+
+## Code Rules
+
+- Match existing module patterns.
+- Prefer local helpers and established abstractions.
+- Put non-public shared implementation in `internal` packages where
appropriate.
+- Mark Java-visible internals with `private[pekko]`, `@InternalApi`, and
`INTERNAL API` Scaladoc.
+- For public Java APIs, avoid Scala default parameters, lower type bounds,
deeply nested traits, and Scala-only collection types.
+- Use `scala.jdk.*` converters for Java/Scala interop.
+- For new Pekko Streams operators, update operator docs and consistency
coverage.
+- Projection handlers must be idempotent where at-least-once semantics are
used.
+- Backend-specific implementations (JDBC, R2DBC, Cassandra, Kafka) must follow
the SPI pattern.
+
+## CI and JDK Rules
+
+- Read exact GitHub Actions logs before changing code for CI failures.
+- Reproduce JDK-specific failures on the same JDK when possible.
+- For JDK 21+ nightly virtual-thread behavior, read the matching section in
`CONTRIBUTING.md`.
+- Do not treat a pass on a different JDK as proof for a JDK-specific failure.
+
+## Commit and PR Format
+
+- Use this body format for non-trivial commits.
+
+```text
+Motivation:
+Problem or requirement.
+
+Modification:
+Change summary.
+
+Result:
+New outcome.
+
+Tests:
+- command/result or Not run - docs only
+
+References:
+Fixes #1234, Refs #1234, or None - <short context>
+```
+
+- Use this PR body format.
+
+```markdown
+### Motivation
+Problem or requirement.
+
+### Modification
+Change summary.
+
+### Result
+New outcome.
+
+### Tests
+- command/result or Not run - docs only
+
+### References
+Fixes #1234, Refs #1234, or None - <short context>
+```
+
+- Never omit `Tests`.
+- Never omit `References`.
+- Use `Refs #...`, `Fixes #...`, or `None - <short context>`.
+- Do not add `Co-authored-by` or AI-assistant trailers to commits or PR
descriptions.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..2d3da9d6
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,19 @@
+# Claude Rules for Apache Pekko Projection
+
+Follow `AGENTS.md`.
+
+Before opening or updating a PR, verify:
+
+- Non-doc-only changes have directional tests.
+- Native `scalafmt` or the sbt scalafmt tasks were run for changed Scala/SBT
files, or the missing tool is recorded in `Tests`.
+- `sbt javafmtAll` was run with JDK 17 when relevant.
+- `sbt headerCreateAll` was run to add headers for new files. Never hand-write
or invent license headers; let sbt manage them, and preserve existing copyright
notices intact.
+- For copied code, the source file or external project is noted in the PR (see
Licensing Rules in `AGENTS.md`).
+- Binary compatibility is preserved, and the GitHub `Check / Binary
Compatibility` job passes before merge.
+- `sbt +mimaReportBinaryIssues` was run for public API, binary shape, or
MiMa-sensitive internal changes, and ALL reported issues were fixed before
creating or updating the PR.
+- Projection handler changes preserve at-least-once or exactly-once semantics.
+- Offset storage changes are backward compatible.
+- Commit messages follow the `AGENTS.md` format.
+- PR bodies follow the `AGENTS.md` format.
+- `Tests` and `References` are present.
+- No `Co-authored-by` or AI-assistant trailers are added to commits or PR
descriptions.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
