Skip to content

[MINOR] Clarify module dependency boundaries for coding agents - #5614

Open
jongyoul wants to merge 1 commit into
apache:masterfrom
jongyoul:codex/minor-interpreter-dependency-policy
Open

jongyoul wants to merge 1 commit into
apache:masterfrom
jongyoul:codex/minor-interpreter-dependency-policy

Conversation

@jongyoul

Copy link
Copy Markdown
Member

What is this PR for?

Document the module dependency boundaries in AGENTS.md: shared zeppelin-* framework modules may depend on one another sparingly, while backend interpreters must remain independent, including implementation inheritance and test artifacts. Clarify that module directories determine the category, since interpreter artifact names such as zeppelin-python also use the prefix, and link the rule from the architecture reference.

Existing cross-interpreter dependencies are legacy coupling to address in separate refactoring; they do not justify adding or extending those dependencies.

What type of PR is it?

Documentation

What is the Jira issue?

N/A — MINOR documentation change.

How should this be tested?

  • git diff --check passed.
  • Local Markdown links resolve.
  • ./mvnw clean org.apache.rat:apache-rat-plugin:check -Prat -B --no-transfer-progress passed with JDK 11.
  • Unit tests are not applicable to this documentation-only change.

Questions:

  • License files need updates: no.
  • Breaking changes: no.
  • Documentation: this PR updates the agent instructions and architecture reference.

Copilot AI balanced review requested due to automatic review settings November 12, 2026 07:40

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

No open issues 🎉

What changed in this PR

Documents module dependency boundaries for coding agents and links the guidance between AGENTS.md and the architecture reference to prevent new cross-interpreter coupling.

Changes:

  • Add explicit module dependency rules to AGENTS.md distinguishing framework modules vs interpreter modules.
  • Clarify that boundaries are determined by repository directories (not Maven artifact names) and that existing cross-interpreter coupling is legacy.
  • Link the dependency rules from .agents/module-architecture.md back to AGENTS.md for a single source of truth.
File Description
AGENTS.md Adds a new “Module Dependency Rules” section defining allowed/forbidden dependency directions and linking to the architecture reference.
.agents/​module-architecture.md Adds a cross-link to the “Module Dependency Rules” section to reinforce boundary guidance in the architecture doc.

Review effort: Lite

@miinhho

miinhho commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

I compared the old and updated instructions across six synthetic coding tasks, with two runs per version.

The updated instructions helped in two cases: the agent stopped adding cross-interpreter test-jar dependencies and stopped extending existing legacy coupling. It continued to allow dependencies between submodules of the same interpreter.

Evaluation results and before/after patches.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants