docs: add AGENTS.md for AI-agent collaboration on the binding#388
Open
phraktle wants to merge 2 commits intoSpaiR:mainfrom
Open
docs: add AGENTS.md for AI-agent collaboration on the binding#388phraktle wants to merge 2 commits intoSpaiR:mainfrom
phraktle wants to merge 2 commits intoSpaiR:mainfrom
Conversation
Guidance doc for AI coding agents (Claude Code, Cursor, etc.) working on this repo. Covers the evergreen stuff that's easy to get wrong without orientation: - The codegen-driven structure (src/main/java annotated, src/generated/java expanded by buildSrc Spoon pass, both committed) and the "never edit generated code" rule. - Project layout, build/test commands, and a fast standalone javadoc recipe for iterating on doclint errors without waiting for Gradle + CI. - The end-to-end flow for bumping Dear ImGui or an extension: orient via upstream changelog + header diff first (breaking changes / obsoleted APIs / new features worth exposing / AST implications), then the mechanical regen steps. - Gotchas: doclint rejecting C++ operator patterns in doc comments (with before/after examples), vendor patches under patches/, AST regeneration drift from differing system headers, and the regen-instead-of-hand-merge pattern when rebasing branches with codegen output. - Codegen conventions for buildSrc (bound-appropriate Spoon type args after the Kotlin 2 K2 migration, configuration-cache patterns). - PR workflow: separate commits and PRs for bumps/deps/codegen, suggested merge order when multiple are open. Intended to reduce the onboarding cost for agents bumping submodules in the future; most of the advice is drawn from the recent 1.92.7 + ImPlot v1.0 + Gradle 9 bump wave.
… dual-loader note Refinements based on real agent-session experience: - Visual smoke test flow (build.sh → copy → :example:run) — static checks miss blank atlases, runtime assertions, broken draw calls. - Native source rewrites in GenerateLibs.groovy silently no-op when imgui renames their anchor symbol between versions; flag to grep on bumps. - Dual stb_truetype + FreeType loader design wasn't documented anywhere; non-obvious to a reader touching font code. - Submodule sync after branch switch — common footgun. - Scope note that the Spoon <Nothing> section only matters when editing the generator itself, not routine source edits. - CI log fetch: prefer `gh run view --job` for focused output over the whole-run `--log-failed` dump. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
AGENTS.mdat the repo root — a short (~175 line) guidance doc for AI coding agents (Claude Code, Cursor, etc.) working on this repo.Most of this advice comes from bumping Dear ImGui 1.92.7, ImPlot v1.0, and Gradle 9 in the recent wave (#382-#385) — stuff that was easy to get wrong without orientation. Concretely:
src/main/javaannotated →src/generated/javaexpanded by the Spoon pass inbuildSrc/, both committed), and the "never edit generated code directly" rule.javadoc -Xdoclint:allrecipe for iterating on doclint errors without waiting for Gradle + CI.&,<,>,->) in copied doc comments; vendor patches underpatches/; AST regeneration drift from differing system headers; regen-instead-of-hand-merge when rebasing branches with codegen output.buildSrc/: the bound-appropriate Spoon type-arg table that replaced<Nothing>in the Kotlin 2 K2 migration (build(deps): bump Gradle wrapper to 9.4.1 and LWJGL to 3.4.1 #383), and the Gradle 9 configuration-cache pattern.The doc is intended as a living reference — amend as the project evolves.
Test plan