Skip to content

extend AGENTS.md based on CONTIBUTING.md #2908

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mshustov wants to merge 1 commit into
base: main
Choose a base branch
from
+44 −1
Open

extend AGENTS.md based on CONTIBUTING.md #2908

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,15 @@ Main modules:

- Minimal supported Java version is 8.
- Follow `docs/ai-review.md` for compatibility, breaking-change, and review instructions.
- Follow `AI_POLICY.MD`: take the same responsibility for generated code as hand-written code, don't
submit code you don't understand, and respect licensing when reproducing any external code.
Comment on lines +20 to +21

@mshustov mshustov Jul 5, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does, https://github.com/ClickHouse/clickhouse-java/blob/main/AI_POLICY.md


## When to pause and ask

- Before implementing a new feature, a large behavior change, or anything touching public API,
configuration, protocol handling, serialization, or JDBC/R2DBC behavior: check whether an approved
issue or proposal already covers it. If not, say so and ask before implementing instead of proceeding silently — see `CONTRIBUTING.md`.
- Do not modify CI workflow files (`.github/workflows/**`). CI changes are restricted; raise it with the user first.

## Setup and test commands

Expand All @@ -29,6 +38,11 @@ Prefer targeted Maven commands over full-repo runs.
- `mvn -pl jdbc-v2 test`
- `mvn -pl clickhouse-data test`

Also compile examples or packaging modules (e.g. `packages/clickhouse-jdbc-all`) when a change affects examples, packaging, public APIs, or other user-facing behavior — running the touched module's tests alone isn't enough.

Run benchmarks under `clickhouse-benchmark` when a change touches a performance-sensitive path (see
`docs/ai-review.md`); this is optional and only worth doing when performance is actually in question.

Avoid broad dependency, formatting, or unrelated cleanup churn unless required by the task.

## Editing expectations
Expand All @@ -37,10 +51,40 @@ Avoid broad dependency, formatting, or unrelated cleanup churn unless required b
- Read nearby code and follow existing local patterns before introducing new abstractions.
- Prefer focused tests near the affected module over repo-wide runs.

## Scope discipline

- One logical change per commit/PR: a feature, a bug fix, a refactor, or a doc update. Don't mix.
- Implement the smallest change that solves the problem. Defer polish, extra configuration, and
optimization to follow-ups rather than expanding scope.
- Flag it if a change is growing large: ~400 LOC starts to hurt reviewability, 800+ LOC needs to be
split into smaller changes.

## Testing expectations

- Add negative tests when a change affects validation, error handling, parsing, serialization, or
compatibility-sensitive behavior. The test should prove the failure path produces the correct
result/exception, not just that the original bug no longer reproduces.
- Don't pad coverage: add a test only when it covers a distinct scenario, edge case, module, type,
format, or failure mode. Avoid duplicating existing coverage.
- Favor scenario coverage (boundary values, invalid input, nullable/nested interactions) over raw
coverage percentage.
- Keep tests compact, readable, and focused on the scenario being verified. Reduce duplication in test setup and assertions so a reviewer can quickly see what behavior is being tested.

## Closeout checklist

- Run the affected module's tests locally (see "Setup and test commands") before treating a change as done. Don't hand off a change with failing or unrun tests.
- Update `CHANGELOG.md` for user-facing changes: what the problem was, how it was fixed, and a link to the issue.
- Update `docs/features.md` when a `client-v2` or `jdbc-v2` feature is added, removed, or its behavior intentionally changes.
- In the final summary: state compatibility impact explicitly, describe any user-visible behavior
change, and link the related issue (note that one should be created if it's missing).

## Review expectations

For review requests, follow `docs/ai-review.md` as the shared review standard across AI agents.

Before treating implementation work as done, self-review your own diff against `docs/ai-review.md` —
not only when a review is explicitly requested.

## Optional nested AGENTS.md

If a module develops its own conventions, add a nested `AGENTS.md` inside that module.
Expand Down
1 change: 0 additions & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,6 @@ For a new feature, implement the smallest change that solves the problem. Polish
For self and AI review use following guids:
- `docs/ai-review.md`
- `docs/changes_checklist.md`
- `docs/highlevel-changes-checklist.md`
- `docs/features.md` for changes that touch `client-v2` or `jdbc-v2`

### Testing Expectations
Expand Down