Skip to content

Add AI coding assistant support files (CLAUDE.md, AGENTS.md, project skills) #315

Description

@ntung

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

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions