weiqingy opened a new issue, #894: URL: https://github.com/apache/flink-agents/issues/894
# Follow-up improvements to AGENTS.md and code_review.md ### Background `AGENTS.md` and `code_review.md` were introduced in #878 and already iterated on in #890. Both PRs frame the guides as living documents meant to be refined continuously. This issue tracks a few concrete, self-contained follow-ups, so they can be discussed and picked up as small independent PRs. I'm happy to take these on if a committer is supportive. Splitting into the two well-scoped changes below to keep each PR small and reviewable. ### Proposed changes (high confidence, ready to implement) **1. Freshness check for the version facts in `AGENTS.md`** `AGENTS.md` hard-codes facts that can silently drift from their real source: Python `3.10 through 3.12`, Ruff line length `88`, Java `11`. This is not hypothetical — the source of truth for these already lives in `python/pyproject.toml` and the root `pom.xml`, and comparable version strings elsewhere in the repo have drifted before. Proposal: a small script under `tools/`, wired into the existing lint/CI lane, that asserts the versions quoted in `AGENTS.md` match `python/pyproject.toml` and `pom.xml`. This makes the guide un-rottable and is mechanical to review. Shape: one `[ci]` / `[infra]` PR. **2. Worked-examples appendix for `code_review.md`** #890 added the "Review Lenses" section and a dedicated design-focused pass, but the passes are still described in the abstract. A short appendix that maps a few already-merged bugs to the exact pass that would catch them would make the checklist more tangible without changing any of its policy. Candidate cases, all from merged PRs in this repo: - Durable-serde type loss where a `byte[]` value came back as a base64 `String` after replay (#846 / #865 / #874) — illustrates "does the root cause still exist through the serialization path?". - Embedding-metrics side channel where batch fan-out dropped metrics (#870) — illustrates the recovery/async path plus Java/Python parity lenses. - A null-vs-`None` default-argument divergence surfacing as an NPE (#838) — illustrates the parity lens. Each case would be 3-5 lines: the symptom, the pass/lens that catches it, and the fix pattern. Shape: one docs-only PR appended to `code_review.md`. ### Items worth discussing before implementing These are more opinionated, so raising them here first rather than opening a PR: - A change-type review matrix (e.g. `api/` contract changes, `runtime/` state or recovery changes, Python-Java bridge changes, `dist`/dependency changes, docs-only changes) mapping each PR type to the passes that matter most, as an on-ramp into the existing full checklist. - Whether module-scoped `AGENTS.md` files (e.g. under `python/`, `runtime/python/`, `dist/`) would help, given how differently those sub-domains behave. - Whether `CLAUDE.md` and `AGENTS.md` should converge toward one source of truth with a thin pointer from the other, to avoid the two guides drifting. Feedback on scope and priority welcome. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
