docs: add AGENTS.md guidance for AI agents#1117
Conversation
Add AGENTS.md documenting the conventions, tooling, and cross-SDK impact analysis that changes to this specification repository require, plus a CLAUDE.md that imports it so Claude Code loads the guidance automatically. The guidance covers: the pixi-based build/test/lint tasks, which generated code is committed vs. gitignored, the conventional-commit and breaking-change CI checks that gate every PR, and PR-description conventions.
| Because this is a spec, changes here ripple into the downstream SDKs. Treat a | ||
| change as an API change to an ecosystem, not a local edit. | ||
|
|
||
| ## The downstream SDKs (critical context) |
There was a problem hiding this comment.
I think deprecation preference or guidance may be useful here? Also, it would be nice if we can include the usage survey -- like blast radius analysis for a change in other open source projects like... data fusion?
There was a problem hiding this comment.
Good call — rather than inventing new guidance, I've grounded this in the existing policy docs. It now links the breaking-change policy, versioning policy, and governance (PMC votes for spec deprecations), and reorders the workflow to match the policy's rule that the migration must land in all active libraries before the breaking change. For the library list, it now points to active_libraries.md as the source of truth instead of hardcoding it. And on blast radius: added external consumers (Apache DataFusion, DuckDB's substrait extension) as non-blocking usage signal, with the active libraries as the actual gate. (c241d19)
| 3. Only then propose the change, often as a **draft PR** pending community | ||
| discussion, with companion PRs to the SDKs where needed. | ||
|
|
||
| Wire-compatibility details matter and are expected in PR descriptions: reserve |
There was a problem hiding this comment.
this... I don't know whether it is worth to encode more precisely... or just link to a page in protobuf compatibility doc in protobuf official documentation.
There was a problem hiding this comment.
Agreed — no point re-deriving protobuf's rules here. Trimmed this down to the substrait-specific bit (reserve removed field numbers/names, enforced by buf breaking, so old plans carry unknown fields rather than failing to parse) and linked out to protobuf's Updating A Message Type guide for the general wire-compatibility rules. Dropped the dissolved-oneof note. (c241d19)
| companion PRs" once that's implicit in the PR being a draft. | ||
|
|
||
| Do include: the rationale, the SDK impact analysis, and wire/source/semantic | ||
| compatibility analysis for proto changes. |
There was a problem hiding this comment.
where these should go? always create issue per PR?
There was a problem hiding this comment.
Clarified this in the doc: the impact/migration/compatibility analysis goes in the PR (or draft PR) body — no requirement to open a separate issue per PR. Issues are for surfacing design discussion on larger or contentious changes before the design is settled (the URI→URN cookbook is a good example of that flow). Does that match the intended process? Happy to adjust the wording if you'd frame it differently. (c241d19)
Address review feedback on the deprecation/breaking-change guidance: reference active_libraries.md, breaking_change_policy.md, versioning.md, and governance.md instead of re-deriving them, reorder the workflow to match the breaking-change policy, add external consumers as non-blocking usage signal, trim the wire-compat prose to a protobuf link, and clarify that impact analysis goes in the PR body rather than a per-PR issue.
2 participants
Proposed change
Add an
AGENTS.mddocumenting the conventions AI agents (and new contributors) need when changing this specification repository, and aCLAUDE.mdthat imports it (@AGENTS.md) so Claude Code picks it up automatically.The guidance is distilled from recurring patterns and captures:
pixi run format/lint/test/generate, so versions match CI.gen/is gitignored; the ANTLR parsers undertests/*/antlr_parser/are committed and must be regenerated when grammars change.BREAKING CHANGE:footer requirement whenbuf breakingtrips.site/docsupdates and externally-validated examples.AGENTS.mdis the emerging cross-tool convention;CLAUDE.mdis kept to a one-line import so there is a single source of truth.🤖 Generated with AI
This change is