Create CLAUDE.md for Codebase Guidance

Summary

I'll analyze the codebase in parallel to understand its structure, build system, and architecture.

Ran sub-agentExplore codebase structure

Ran sub-agentExplore code architecture

Now let me read a few key files directly for accuracy.

ReadMakefile

Readreadme.md

Please analyze this codebase and create a CLAUDE.md file, which will be given to future instances of Claude Code to operate in this repository.

What to add:

Commands that will be commonly used, such as how to build, lint, and run tests. Include the necessary commands to develop in this codebase, such as how to run a single test.
High-level code architecture and structure so that future instances can be productive more quickly. Focus on the "big picture" architecture that requires reading multiple files to understand.

Usage notes:

If there's already a CLAUDE.md, suggest improvements to it.
When you make the initial CLAUDE.md, do not repeat yourself and do not include obvious instructions like "Provide helpful error messages to users", "Write unit tests for all new utilities", "Never include sensitive information (API keys, tokens) in code or commits".
Avoid listing every component or file structure that can be easily discovered.
Don't include generic development practices.
If there are Cursor rules (in .cursor/rules/ or .cursorrules) or Copilot rules (in .github/copilot-instructions.md), make sure to include the important parts.
If there is a README.md, make sure to include the important parts.
Do not make up information such as "Common Development Tasks", "Tips for Development", "Support and Documentation" unless this is expressly included in other files that you read.
Be sure to prefix the file with the following text:

# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Readpom.xml50 lines

Ran sub-agentExplore test and card patterns

Used TaskOutput

The agent hit an error but returned useful data. Let me read a few more key files directly.

Your account does not have access to Claude Code. Please run /login.

Searched filesMage.Tests/src/test/java/org/mage/test/cards/single/**/*Test.javain //mnt/dest-btrfs/home/jc/src/mage

Searched filesMage.Sets/src/mage/cards/a/A*.javain //mnt/dest-btrfs/home/jc/src/mage

ReadAbbeyGriffin.java

ReadPowerWordKillTest.java

ReadCardTestPlayerBase.java

Caveat: The messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to.

Caveat: Caveat: The messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to.

Now let me check the Mage.Tests pom.xml for surefire configuration and how to run a single test.

Readpom.xml

Searched filesMage/src/main/java/mage/constants/SubType.javain //mnt/dest-btrfs/home/jc/src/mage

ReadSubType.java80 lines

654-    /**
655-     * Use in test framework only, use SubType.byDescription instead for card logic
656-     */
657:    public static SubType fromString(String value) {
658-        for (SubType st : SubType.values()) {
659-            if (st.toString().equals(value)) {
660-                return st;

ReadAbruptDecay.java

Let me also look at how sets register their cards and the card file naming convention.

Searched filesMage.Sets/src/mage/sets/*.javain //mnt/dest-btrfs/home/jc/src/mage

ReadAmonkhet.java30 lines

650-    public boolean isCustomSet() {
651-        return customSet;
652-    }
653-
654-    /**
655:     * Use in test framework only, use SubType.byDescription instead for card logic
656-     */
657-    public static SubType fromString(String value) {
658-        for (SubType st : SubType.values()) {
659-            if (st.toString().equals(value)) {
660-                return st;
--
662-        }
663-
664-        throw new IllegalArgumentException("Can''t find subtype enum value: " + value);
665-    }
666-
667:    public static SubType byDescription(String subType) {
668-        for (SubType s : values()) {
669-            if (s.getDescription().equals(subType)) {
670-                return s;
671-            }
672-        }

Now I have enough information. Let me create the CLAUDE.md file.

Created CLAUDE.md with:

Build commands — make build, mvn test, single test execution with -Dtest= and -pl Mage.Tests
Module architecture — All 9 modules with their purpose and package structure
Card implementation pattern — Complete example with conventions (final class, copy constructor, singleton keyword abilities, filter patterns)
Core abstractions — Ability/Effect hierarchy, 7-layer continuous effect system, key constants
SubType gotcha — byDescription() for card code vs fromString() for tests only
Test framework — Full example test with the declarative API, all key assertion/action methods, test file organization
Event system and plugin architecture — How game variants and extensions work

a3064fb failed

Agent "Explore test and card patterns" failed: classifyHandoffIfNeeded is not defined

Full transcript available at: /tmp/claude-1000/-mnt-dest-btrfs-home-jc-src-mage/tasks/a3064fb.output

The background agent failed but I had already gathered all the information I needed from it and other sources. The CLAUDE.md file has been created successfully at the repository root.

Please analyze this codebase and create a CLAUDE.md file, which will be given to future instances of Claude Code to operate in this repository.

What to add:

Commands that will be commonly used, such as how to build, lint, and run tests. Include the necessary commands to develop in this codebase, such as how to run a single test.
High-level code architecture and structure so that future instances can be productive more quickly. Focus on the "big picture" architecture that requires reading multiple files to understand.

Usage notes:

If there's already a CLAUDE.md, suggest improvements to it.
When you make the initial CLAUDE.md, do not repeat yourself and do not include obvious instructions like "Provide helpful error messages to users", "Write unit tests for all new utilities", "Never include sensitive information (API keys, tokens) in code or commits".
Avoid listing every component or file structure that can be easily discovered.
Don't include generic development practices.
If there are Cursor rules (in .cursor/rules/ or .cursorrules) or Copilot rules (in .github/copilot-instructions.md), make sure to include the important parts.
If there is a README.md, make sure to include the important parts.
Do not make up information such as "Common Development Tasks", "Tips for Development", "Support and Documentation" unless this is expressly included in other files that you read.
Be sure to prefix the file with the following text:

# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.