You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
63 lines
3.0 KiB
Markdown
63 lines
3.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
AutoHero is an isometric browser-based idle/incremental combat game designed for Telegram Mini Apps. The project uses a multi-agent development workflow with 8 specialized Claude agents.
|
|
|
|
## Tech Stack
|
|
|
|
- **Backend**: Go (game server, REST + WebSocket APIs)
|
|
- **Frontend**: React + TypeScript with PixiJS for isometric rendering
|
|
- **Database**: PostgreSQL (primary), Redis (caching/sessions/pub-sub)
|
|
- **Platform**: Telegram Mini Apps (`window.Telegram.WebApp` SDK)
|
|
- **Target**: 60 FPS on mid-range mobile devices, 100k concurrent users
|
|
|
|
## Architecture
|
|
|
|
### Backend (Go)
|
|
- Standard Go project layout: `cmd/`, `internal/`, `pkg/`
|
|
- Tick-based game loop engine with configurable tick rate
|
|
- Combat system using min-heap ordered by `next_attack_at` timestamps
|
|
- Buff/debuff modifiers as middleware in the damage pipeline
|
|
- WebSocket hub pattern (register/unregister channels, per-connection read/write goroutines)
|
|
- Offline simulation via deterministic cron-based batch processing
|
|
- Structured logging (slog or zerolog), context propagation everywhere
|
|
|
|
### Frontend (React + TypeScript)
|
|
- PixiJS canvas for game world, React DOM overlay for UI
|
|
- Fixed-timestep game loop with `requestAnimationFrame`
|
|
- Folder structure: `/game` (engine/rendering), `/ui` (React components), `/network` (WS), `/shared` (types)
|
|
- WebSocket client with auto-reconnect, heartbeat, and message queuing
|
|
- TypeScript strict mode, functional React components with hooks
|
|
|
|
### Communication
|
|
- REST for CRUD/state queries
|
|
- WebSocket for real-time combat events and state pushes
|
|
- Binary protocols (MessagePack/Protobuf) for performance-critical paths
|
|
|
|
## Agent System
|
|
|
|
Eight specialized agents are defined in `.claude/agents/`:
|
|
|
|
| Agent | Role |
|
|
|-------|------|
|
|
| `system-architect` | Service design, scaling, tech selection |
|
|
| `tech-lead` | Prioritization, MVP scope, speed vs quality |
|
|
| `backend-engineer-go` | Go game server implementation |
|
|
| `frontend-game-engineer` | PixiJS rendering, UI, WebSocket client |
|
|
| `game-designer` | Mechanics, balance, progression, retention |
|
|
| `qa-game-engineer` | Test design, combat edge cases, load testing |
|
|
| `code-design-reviewer` | Code quality, overengineering detection |
|
|
| `devops-infra` | CI/CD, Docker, monitoring, cloud |
|
|
|
|
Agents maintain persistent memory in `.claude/agent-memory/{agent-name}/`.
|
|
|
|
## Key Design Decisions
|
|
|
|
- **Go concurrency**: Prefer channels over shared memory; keep mutex critical sections minimal. Always use `-race` flag in tests.
|
|
- **Idle game philosophy**: Simple under the hood; performance-first for frame budget; mobile-first for touch/small screens.
|
|
- **MVP approach**: Optimize for speed, accept tactical debt (documented), but invest in quality for auth, data model, and payments.
|
|
- **Boring technology**: Prefer proven tech unless there's a compelling reason. The best tech is the one the team knows.
|
|
- **Contract-first**: Define API contracts early to unblock parallel backend/frontend work. |