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
    No fields configured for Feature.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions