[ZEPPELIN-6405] Add AGENTS.md for AI coding agent guidance#5187
[ZEPPELIN-6405] Add AGENTS.md for AI coding agent guidance#5187jongyoul merged 7 commits intoapache:masterfrom
Conversation
Add comprehensive AGENTS.md following the open standard to help AI coding agents understand and work effectively with the Zeppelin codebase. Includes module architecture, server-interpreter Thrift IPC communication details, plugin system with custom classloading, reflection patterns, interpreter lifecycle, and contributing guide. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
… exclusion Add the standard ASF license header to AGENTS.md instead of excluding it from the RAT license check. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…s, and config map; add AI agent dirs to .gitignore AGENTS.md additions: - Build Gotchas: shaded JAR rebuild chain, module build order - Configuration Files: conf/ file roles and template relationship - Module Boundaries: where new code should go - Thrift Code Generation: genthrift.sh workflow, generated files in git - REST API Pattern: AbstractRestApi, JsonResponse, @ZeppelinApi conventions .gitignore additions: - AI coding agent personal config directories (CLAUDE.md, GEMINI.md, .claude/, .gemini/, .codex/, .cursor/, .windsurf/, .cline/, .continue/, .aider*, .augment/, .amazonq/, .junie/, .goose/, .roo/) - AGENTS.md remains shared and tracked in git Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds an AGENTS.md guide (per the agents-md standard) to document Apache Zeppelin’s architecture and contributor workflows for AI coding agents, plus updates .gitignore to exclude agent-specific local config files.
Changes:
- Introduces
AGENTS.mdwith build/test commands and deep architectural context (modules, Thrift IPC, plugin/classloading, interpreter lifecycle). - Adds
.gitignoreentries for various AI-agent local config files/directories to keep them untracked.
Reviewed changes
Copilot reviewed 1 out of 2 changed files in this pull request and generated 8 comments.
| File | Description |
|---|---|
| AGENTS.md | New AI-agent guidance doc covering build/test workflow and Zeppelin architecture details. |
| .gitignore | Ignores common AI-agent local configuration files/directories. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Add --am flag to module-scoped Maven commands for clean checkout support - Fix JUnit version: JUnit 4 → JUnit 5 (Jupiter) with legacy note - Add git worktree recommendation in Development Workflow section Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
tbonelee
left a comment
tbonelee
left a comment
There was a problem hiding this comment.
My impression is that keeping AGENTS.md as the canonical shared guide makes sense.
That said, if that is the goal, I wonder whether it might be worth considering symlinks for vendor-specific files like CLAUDE.md instead of simply adding them to .gitignore. Some Apache repositories, such as Superset, SeaTunnel, Camel Quarkus, and OpenDAL, appear to take that approach, with AGENTS.md as the main source of truth and CLAUDE.md as a symlink.
It seems like that would keep the actual content in a single place while still helping with tool-specific discovery. I was just curious what you think about that approach.
|
@tbonelee Thank you for the review. The reason why I just ignored some vendor-spcific files is that I thought users might want to use vendor-specific structure like using skills, subagents. I also made a converter like https://github.com/jongyoul/claude-plugins-zeppelin I'm not sure we can satisfy all AI agents by AGENTS.md. |
…file - Fix AGENTS.md specification link to point to the correct repository - Add -Pweb-classic profile description in Common profiles section Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…merge Reflect the zeppelin-zengine to zeppelin-server module merge: collapse the build/dependency chain to three layers, fold the zengine module description into zeppelin-server (split into Web/API and Engine/runtime), and update PluginManager and ReflectionUtils paths to zeppelin-server. Addresses tbonelee's review reminder on PR apache#5187 (line 78).
|
@tbonelee Thanks again for the earlier review. PR #5095 (ZEPPELIN-6355) has now been merged, so I pushed Also, I see this PR as just a starting point — AGENTS.md is meant to evolve, and I'd love for any committer or contributor to feel free to extend or refine it whenever they spot something useful to add. |
|
Merged into master (bb6ed26). |
Summary
AGENTS.mdfollowing the open standard to help AI coding agents understand and work effectively with the Zeppelin codebaseTest plan
AGENTS.mdrenders correctly on GitHub./mvnw clean org.apache.rat:apache-rat-plugin:check -Prat)