| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 25 | 2 | 0% |
| Commands | 0 | 7 | 0 | 0% |
| Section tags | 0 | 8 | 1 | 0% |
What each file covers
Sections
0 shared · 25 only in A · 2 only in B- − CLAUDE.md
- − Project Overview
- − Development Commands
- − Bot Compilation
- − Testing Commands
- − or for C++ bots:
- − Tournament System
- − Architecture Overview
- − Directory Structure
- − Bot Architecture
- − Bot Implementations
- − Platform Constraints (Botzone)
- − Time Limits
- − Resource Limits
- − I/O Protocol
- − Development Workflow
- − Cline Memory Bank System
- − Development Rules (`.clinerules/`)
- − Key Development Patterns
- − Common Tasks
- − Creating a New Bot
- − Debugging TLE (Time Limit Exceeded) Issues
- − Testing Botzone Compatibility
- − Important Notes
- − Getting Started
- + Documentation Standards
- + Documentation Requirements
Commands
0 shared · 7 only in A · 0 only in B- − python -c "from scripts.tournament.utils import compile_bot; compile_bot('bot003')"
- − python scripts/test_bot_simple.py
- − python scripts/botzone_simulator.py
- − python -c "from scripts.tournament.cli import run_match; run_match('bot001', 'bot003')"
- − python scripts/run_competitions.py
- − python scripts/check_legal_moves.py
- − python scripts/debug_board.py
Section tags
0 shared · 8 only in A · 1 only in B- − setup
- − test
- − lint-format
- − code-style
- − architecture
- − performance
- − do-not
- − agent-behaviour
- + docs
Line diff
RizzoHou/amazing-amazons · CLAUDE.md
@@ −1 @@
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Project Overview
6
7This is a competitive AI bot development project for the Game of Amazons, designed to run on the Botzone platform. The project focuses on creating high-performance bots using Monte Carlo Tree Search (MCTS) with various optimization techniques.
8
9**Key Technologies**: Python 3.6+, C++11, NumPy
10**Platform**: Botzone (Ubuntu 16.04 x86-64)
11**Game**: Amazons (8×8 board, 4 amazons per player, queen movement + arrow shooting)
12
13## Development Commands
14
15### Bot Compilation
16C++ bots are compiled manually with:
17```bash
18g++ -O3 -std=c++11 -o bots/botXXX bots/botXXX.cpp
19```
20
21The tournament system provides a helper function:
22```bash
23python -c "from scripts.tournament.utils import compile_bot; compile_bot('bot003')"
24```
25
26### Testing Commands
27**Quick functionality test** (first move as BLACK):
28```bash
29echo "1
30-1 -1 -1 -1 -1 -1" | python bots/bot001.py
31# or for C++ bots:
32echo "1
33-1 -1 -1 -1 -1 -1" | ./bots/bot001_cpp
34```
35
36**Run simple bot tests**:
37```bash
38python scripts/test_bot_simple.py
39```
40
41**Run Botzone protocol simulation**:
42```bash
43python scripts/botzone_simulator.py
44```
45
46### Tournament System
47The tournament framework (`scripts/tournament/`) provides comprehensive testing:
48
49**Single match**:
50```bash
51python -c "from scripts.tournament.cli import run_match; run_match('bot001', 'bot003')"
52```
53
54**Competition automation** (10-game series):
55```bash
56python scripts/run_competitions.py
57```
58
59**Check legal moves** (debugging tool):
60```bash
61python scripts/check_legal_moves.py
62```
63
64**Debug board visualization**:
65```bash
66python scripts/debug_board.py
67```
68
69## Architecture Overview
70
71### Directory Structure
72- `core/` - Shared game logic (board representation, move generation)
73- `bots/` - Bot implementations (Python and C++ versions)
74- `scripts/` - Testing and utility scripts
75- `docs/` - Comprehensive documentation
76- `memorybank/` - Project context and technical decisions (Cline system)
77- `results/` - Tournament results (JSON format)
78- `logs/` - Match logs and output
79
80### Bot Architecture
81The primary algorithm is **Multi-Component MCTS** with these key features:
82
831. **Multi-Component Evaluation**: Five strategic factors combined:
84 - Queen Territory (BFS-based territory control)
85 - King Territory (weighted close-range control)
86 - Queen Position (exponential decay scoring)
87 - King Position (distance-weighted positioning)
88 - Mobility (available moves count)
89
902. **Phase-Aware Weighting**: Different strategies for early/mid/late game phases
91
923. **Dynamic UCB Constant**: Exploration decreases as game progresses
93
944. **Long-Running Mode**: Maintains MCTS tree state between turns for efficiency
95
96### Bot Implementations
97- `bot001.py` / `bot001.cpp` - Primary MCTS implementation (Python and C++ versions)
98- `bot002.cpp` - Optimized version with bitboard representation (has TLE issues)
99- `bot003.cpp` - Baseline MCTS bot for comparison
100- `bot004-bot008.cpp` - Optimization bots with different techniques
101- `opponent.cpp` - Latest implementation with AVX2 SIMD optimizations
102
103## Platform Constraints (Botzone)
104
105### Time Limits
106- **Python long-running bots**: 12s (first turn), 4s (subsequent turns)
107- **C++ long-running bots**: 2s (first turn), 1s (subsequent turns)
108
109### Resource Limits
110- Memory: 256 MB default
111- CPU: Single core (no multi-threading benefit)
112
113### I/O Protocol
114- Simplified interaction: Line-based stdin/stdout
115- Long-running mode: Must flush stdout after each turn
116- Move format: 6 integers `x0 y0 x1 y1 x2 y2`
117
118## Development Workflow
119
120### Cline Memory Bank System
121The project uses a Cline memory bank (`memorybank/`) for context:
122- `projectbrief.md` - Project overview and objectives
123- `systemPatterns.md` - Architecture and design decisions
124- `techContext.md` - Technologies and constraints
125- `activeContext.md` - Current state and next steps
126- `progress.md` - Development progress and milestones
127
128### Development Rules (`.clinerules/`)
129- `development_workflow.md` - Development processes
130- `task_completion.md` - Mandatory sequential workflow for task completion
131- `memory_bank_update.md` - How to update memory bank files
132- `readme_update.md` - README update procedures
133
134### Key Development Patterns
1351. **Always test sequentially** - Run tests in order: simple test → protocol simulation → tournament
1362. **Update memory bank first** - Review and update memory bank files before making changes
1373. **Check Botzone compatibility** - Ensure bots work within platform constraints
1384. **Use tournament framework** - For comprehensive testing and performance comparison
139
140## Common Tasks
141
142### Creating a New Bot
1431. Copy an existing bot (e.g., `bot003.cpp`) as a starting point
1442. Implement optimization technique
1453. Compile: `g++ -O3 -std=c++11 -o bots/botXXX bots/botXXX.cpp`
1464. Test with simple test script
1475. Run competition against baseline (`bot003`)
1486. Analyze results in `results/competitions/`
149
150### Debugging TLE (Time Limit Exceeded) Issues
1511. Check time limits in bot code (conservative buffers required)
1522. Use tournament system to measure actual execution times
1533. Profile with `scripts/check_legal_moves.py` for move generation issues
1544. Review Botzone logs for specific timing patterns
155
156### Testing Botzone Compatibility
1571. Use `botzone_simulator.py` to simulate platform I/O
1582. Verify long-running mode works correctly
1593. Check memory usage stays under 256 MB
1604. Ensure move format matches Botzone expectations
161
162## Important Notes
163
164- **No automated build system** - Bots are compiled manually
165- **NumPy dependency** - Required for Python bots, not for C++ bots
166- **Tree reuse** - MCTS trees are preserved between turns in long-running mode
167- **Bitboard representation** - Used in optimized bots for faster operations
168- **AVX2 optimizations** - Latest addition in `opponent.cpp` for SIMD parallelism
169
170## Getting Started
1711. Read `README.md` for comprehensive project overview
1722. Check `memorybank/` for current project context
1733. Use tournament framework for testing: `scripts/tournament/`
1744. Follow Cline workflows in `.clinerules/` for development tasks
RizzoHou/amazing-amazons · .clinerules/documentation.md
@@ +1 @@
1# Documentation Standards
2
3Rules for maintaining project documentation.
4
5## Documentation Requirements
6
7- **Feature Documentation**: Update relevant documentation in `docs/` when modifying or adding features to ensure documentation stays synchronized with code changes.
8
9- **Memory Bank Maintenance**: Update relevant documentation in `memorybank/` throughout the development process to maintain accurate project context and enable effective future sessions.
10
11- **Document Decisions and Rationale**: Maintain thorough documentation practices. Document your decisions, changes, and rationale as you work to provide context for future development.
12
13- **README Currency**: Keep `README.md` current with project progress, setup instructions, and usage information to help new users and developers get started quickly.
14
@@ −1 +1 @@
1−# CLAUDE.md
1+# Documentation Standards
22
3−This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
3+Rules for maintaining project documentation.
44
5−## Project Overview
5+## Documentation Requirements
66
7−This is a competitive AI bot development project for the Game of Amazons, designed to run on the Botzone platform. The project focuses on creating high-performance bots using Monte Carlo Tree Search (MCTS) with various optimization techniques.
7+- **Feature Documentation**: Update relevant documentation in `docs/` when modifying or adding features to ensure documentation stays synchronized with code changes.
88
9−**Key Technologies**: Python 3.6+, C++11, NumPy
10−**Platform**: Botzone (Ubuntu 16.04 x86-64)
11−**Game**: Amazons (8×8 board, 4 amazons per player, queen movement + arrow shooting)
9+- **Memory Bank Maintenance**: Update relevant documentation in `memorybank/` throughout the development process to maintain accurate project context and enable effective future sessions.
1210
13−## Development Commands
11+- **Document Decisions and Rationale**: Maintain thorough documentation practices. Document your decisions, changes, and rationale as you work to provide context for future development.
1412
15−### Bot Compilation
16−C++ bots are compiled manually with:
17−```bash
18−g++ -O3 -std=c++11 -o bots/botXXX bots/botXXX.cpp
19−```
13+- **README Currency**: Keep `README.md` current with project progress, setup instructions, and usage information to help new users and developers get started quickly.
2014
21−The tournament system provides a helper function:
22−```bash
23−python -c "from scripts.tournament.utils import compile_bot; compile_bot('bot003')"
24−```
25−
26−### Testing Commands
27−**Quick functionality test** (first move as BLACK):
28−```bash
29−echo "1
30−-1 -1 -1 -1 -1 -1" | python bots/bot001.py
31−# or for C++ bots:
32−echo "1
33−-1 -1 -1 -1 -1 -1" | ./bots/bot001_cpp
34−```
35−
36−**Run simple bot tests**:
37−```bash
38−python scripts/test_bot_simple.py
39−```
40−
41−**Run Botzone protocol simulation**:
42−```bash
43−python scripts/botzone_simulator.py
44−```
45−
46−### Tournament System
47−The tournament framework (`scripts/tournament/`) provides comprehensive testing:
48−
49−**Single match**:
50−```bash
51−python -c "from scripts.tournament.cli import run_match; run_match('bot001', 'bot003')"
52−```
53−
54−**Competition automation** (10-game series):
55−```bash
56−python scripts/run_competitions.py
57−```
58−
59−**Check legal moves** (debugging tool):
60−```bash
61−python scripts/check_legal_moves.py
62−```
63−
64−**Debug board visualization**:
65−```bash
66−python scripts/debug_board.py
67−```
68−
69−## Architecture Overview
70−
71−### Directory Structure
72−- `core/` - Shared game logic (board representation, move generation)
73−- `bots/` - Bot implementations (Python and C++ versions)
74−- `scripts/` - Testing and utility scripts
75−- `docs/` - Comprehensive documentation
76−- `memorybank/` - Project context and technical decisions (Cline system)
77−- `results/` - Tournament results (JSON format)
78−- `logs/` - Match logs and output
79−
80−### Bot Architecture
81−The primary algorithm is **Multi-Component MCTS** with these key features:
82−
83−1. **Multi-Component Evaluation**: Five strategic factors combined:
84− - Queen Territory (BFS-based territory control)
85− - King Territory (weighted close-range control)
86− - Queen Position (exponential decay scoring)
87− - King Position (distance-weighted positioning)
88− - Mobility (available moves count)
89−
90−2. **Phase-Aware Weighting**: Different strategies for early/mid/late game phases
91−
92−3. **Dynamic UCB Constant**: Exploration decreases as game progresses
93−
94−4. **Long-Running Mode**: Maintains MCTS tree state between turns for efficiency
95−
96−### Bot Implementations
97−- `bot001.py` / `bot001.cpp` - Primary MCTS implementation (Python and C++ versions)
98−- `bot002.cpp` - Optimized version with bitboard representation (has TLE issues)
99−- `bot003.cpp` - Baseline MCTS bot for comparison
100−- `bot004-bot008.cpp` - Optimization bots with different techniques
101−- `opponent.cpp` - Latest implementation with AVX2 SIMD optimizations
102−
103−## Platform Constraints (Botzone)
104−
105−### Time Limits
106−- **Python long-running bots**: 12s (first turn), 4s (subsequent turns)
107−- **C++ long-running bots**: 2s (first turn), 1s (subsequent turns)
108−
109−### Resource Limits
110−- Memory: 256 MB default
111−- CPU: Single core (no multi-threading benefit)
112−
113−### I/O Protocol
114−- Simplified interaction: Line-based stdin/stdout
115−- Long-running mode: Must flush stdout after each turn
116−- Move format: 6 integers `x0 y0 x1 y1 x2 y2`
117−
118−## Development Workflow
119−
120−### Cline Memory Bank System
121−The project uses a Cline memory bank (`memorybank/`) for context:
122−- `projectbrief.md` - Project overview and objectives
123−- `systemPatterns.md` - Architecture and design decisions
124−- `techContext.md` - Technologies and constraints
125−- `activeContext.md` - Current state and next steps
126−- `progress.md` - Development progress and milestones
127−
128−### Development Rules (`.clinerules/`)
129−- `development_workflow.md` - Development processes
130−- `task_completion.md` - Mandatory sequential workflow for task completion
131−- `memory_bank_update.md` - How to update memory bank files
132−- `readme_update.md` - README update procedures
133−
134−### Key Development Patterns
135−1. **Always test sequentially** - Run tests in order: simple test → protocol simulation → tournament
136−2. **Update memory bank first** - Review and update memory bank files before making changes
137−3. **Check Botzone compatibility** - Ensure bots work within platform constraints
138−4. **Use tournament framework** - For comprehensive testing and performance comparison
139−
140−## Common Tasks
141−
142−### Creating a New Bot
143−1. Copy an existing bot (e.g., `bot003.cpp`) as a starting point
144−2. Implement optimization technique
145−3. Compile: `g++ -O3 -std=c++11 -o bots/botXXX bots/botXXX.cpp`
146−4. Test with simple test script
147−5. Run competition against baseline (`bot003`)
148−6. Analyze results in `results/competitions/`
149−
150−### Debugging TLE (Time Limit Exceeded) Issues
151−1. Check time limits in bot code (conservative buffers required)
152−2. Use tournament system to measure actual execution times
153−3. Profile with `scripts/check_legal_moves.py` for move generation issues
154−4. Review Botzone logs for specific timing patterns
155−
156−### Testing Botzone Compatibility
157−1. Use `botzone_simulator.py` to simulate platform I/O
158−2. Verify long-running mode works correctly
159−3. Check memory usage stays under 256 MB
160−4. Ensure move format matches Botzone expectations
161−
162−## Important Notes
163−
164−- **No automated build system** - Bots are compiled manually
165−- **NumPy dependency** - Required for Python bots, not for C++ bots
166−- **Tree reuse** - MCTS trees are preserved between turns in long-running mode
167−- **Bitboard representation** - Used in optimized bots for faster operations
168−- **AVX2 optimizations** - Latest addition in `opponent.cpp` for SIMD parallelism
169−
170−## Getting Started
171−1. Read `README.md` for comprehensive project overview
172−2. Check `memorybank/` for current project context
173−3. Use tournament framework for testing: `scripts/tournament/`
174−4. Follow Cline workflows in `.clinerules/` for development tasks
