Cougr: Instructions file for Claude Code

CLAUDE.md

Instructions for AI assistants (Claude Code and others) working in this repository. The goal is that a contribution written or assisted by an AI is indistinguishable in quality from one written by a maintainer who knows this codebase well.

Before writing code

Read the doc that governs the area you're touching, don't guess at Cougr's conventions from general Rust or general Soroban knowledge:

Soroban and contract code

• #![no_std] is load-bearing, not a formality. Don't introduce a dependency or pattern that requires std.
• Contract entrypoints stay thin: validate input, load state, call into a system or helper, persist state, return. Push actual gameplay logic into systems.rs / plugin systems, not into #[contractimpl] methods. See docs/PATTERNS.md § Default Entry Point.
• Don't panic on reachable, caller-triggerable conditions. Validate and return a clear error instead; reserve panics for genuine invariant violations.
• Every state-changing entrypoint that should be access-controlled must call require_auth (or the relevant AccessControl/Ownable check) before mutating state, not after.
• Prefer the standards layer (Ownable, AccessControl, Pausable, ExecutionGuard, BatchExecutor, ...) over hand-rolling the same guard again. Check docs/STANDARDS_LAYER.md before writing a new one.
• Choose SimpleWorld vs ArchetypeWorld, and table vs sparse storage, based on the actual query/mutation shape, not by default. See docs/PERFORMANCE.md.
• Use impl_component_observed! for state a client needs to react to without polling; plain impl_component! otherwise. Don't emit events nobody consumes.
• New examples depend on the published cougr-core from crates.io, not a path dependency, unless they exercise an API that genuinely isn't published yet, in which case follow the exception format in examples/EXAMPLE_STANDARD.md § 1.1.