Summary
This issue proposes adding support files that help AI coding assistants
(Claude Code, OpenAI Codex, GitHub Copilot Workspace, etc.) understand the
JSBML codebase and contribute effectively.
Motivation
AI-assisted development tools now look for project-specific context files at
the repository root. Without them, assistants fall back to generic heuristics
and frequently give wrong build commands, miss the Maven multi-module layout,
or misunderstand the extension framework. Adding these files is a low-effort,
high-value quality-of-life improvement for contributors who use AI tooling.
Proposed changes
1. CLAUDE.md (Claude Code — Anthropic)
Claude Code reads CLAUDE.md from the repo root automatically when launched
in the project directory. The file should document:
- Project overview and current version
- Build commands (
mvn clean compile package, per-module variants)
- Test commands (full suite, per-module, single class)
- Module architecture (
core/, extensions/, modules/, test/)
- Core abstractions (
SBMLDocument, AbstractSBase, ASTNode, TreeNodeVisitor, …)
- XML I/O backends (STAX default, XStream alternative)
- Extension framework registration pattern (SPI via
META-INF/services)
A working draft is available in the ntung/jsbml fork:
https://github.com/ntung/jsbml/blob/main/CLAUDE.md
2. AGENTS.md (OpenAI Codex / general agents)
OpenAI Codex and similar agentic tools read AGENTS.md. Content mirrors
CLAUDE.md but can emphasize:
- Canonical entry points for tests and builds
- Paths that should never be modified by automated tooling (generated sources,
lib/, binary assets)
- Coding conventions (package naming, extension plugin pattern)
3. Claude Code project skills (.claude/commands/)
Claude Code supports project-scoped slash commands stored in
.claude/commands/*.md. Suggested skills for JSBML:
| Command |
Purpose |
/test-module <name> |
Run tests for a single Maven module |
/build-core |
Compile and package core/ only |
/run-alltests |
Run the full AllTests.java integration suite |
/new-extension <name> |
Scaffold boilerplate for a new SBML package extension |
These are markdown prompt templates — no executable code, just natural-language
instructions that tell the AI what commands to run and what to check.
Impact
- Zero runtime impact — these are documentation/tooling files only
- Helps new contributors get productive faster with AI assistants
- Reduces incorrect suggestions from assistants unfamiliar with Maven
multi-module projects
Related
Summary
This issue proposes adding support files that help AI coding assistants
(Claude Code, OpenAI Codex, GitHub Copilot Workspace, etc.) understand the
JSBML codebase and contribute effectively.
Motivation
AI-assisted development tools now look for project-specific context files at
the repository root. Without them, assistants fall back to generic heuristics
and frequently give wrong build commands, miss the Maven multi-module layout,
or misunderstand the extension framework. Adding these files is a low-effort,
high-value quality-of-life improvement for contributors who use AI tooling.
Proposed changes
1.
CLAUDE.md(Claude Code — Anthropic)Claude Code reads
CLAUDE.mdfrom the repo root automatically when launchedin the project directory. The file should document:
mvn clean compile package, per-module variants)core/,extensions/,modules/,test/)SBMLDocument,AbstractSBase,ASTNode,TreeNodeVisitor, …)META-INF/services)A working draft is available in the
ntung/jsbmlfork:https://github.com/ntung/jsbml/blob/main/CLAUDE.md
2.
AGENTS.md(OpenAI Codex / general agents)OpenAI Codex and similar agentic tools read
AGENTS.md. Content mirrorsCLAUDE.mdbut can emphasize:lib/, binary assets)3. Claude Code project skills (
.claude/commands/)Claude Code supports project-scoped slash commands stored in
.claude/commands/*.md. Suggested skills for JSBML:/test-module <name>/build-corecore/only/run-alltestsAllTests.javaintegration suite/new-extension <name>These are markdown prompt templates — no executable code, just natural-language
instructions that tell the AI what commands to run and what to check.
Impact
multi-module projects
Related