AGENTS.md

AGENTS.md

Guidelines for AI agents working in this Advent of Code repository.

Project Overview

Gleam-based Advent of Code solutions with two parallel implementation tracks (mine/ and llm/) for comparing human vs LLM-generated solutions side-by-side with benchmarking.

Commands

$ gleam build           # Compile the project
$ gleam test            # Run all tests
$ gleam run             # Run all available days with comparison (default)
$ gleam run -- <day>    # Run specific day with comparison
$ gleam run -- -e       # Run with example input (--example)
$ gleam run -- <day> -n # Run without comparison, mine/ only (--no-compare)
$ gleam run -- 1 -en    # Flags can be combined

Code Organization

src/
├── aoc.gleam            # CLI entry point, argument parsing, day dispatch
├── compare.gleam        # Benchmarking harness for mine/ vs llm/ comparison
├── utils.gleam          # Input file reading utilities
└── internal/
    ├── mine/            # Human-written solutions
    └── llm/             # LLM-generated solutions

input/
├── dayXX.txt            # Real puzzle input
└── dayXX_example.txt    # Example input from problem description

test/
└── aoc_test.gleam       # Tests for both implementations

Documentation

When making changes that affect CLI usage, project structure, or workflows, update the relevant documentation (this file and README.md) to reflect those changes.

Adding a New Day

  1. Create src/internal/mine/dayXX.gleam with pub fn part1(input: List(String)) -> Int and pub fn part2(input: List(String)) -> Int and bodies of just todo.
  2. Create src/internal/llm/dayXX.gleam with the same interface. Make sure to include the //// Authored-by: [Model] via Crush header that you're told to use for commits.
  3. Ask the user to paste the input for input/dayXX_example.txt, then download the contents of https://adventofcode.com/2025/day/XX/input to input/dayXX.txt.
  4. Wire up dispatch in src/aoc.gleam:
    • Add import: import internal/mine/dayXX as mine_dayXX
    • Add case to run_parts
  5. Wire up comparison in src/compare.gleam:
    • Add imports for both implementations
    • Add pub fn dayXX(input: List(String)) -> Nil function
    • Add case to run_comparison in aoc.gleam
  6. Add the day number to available_days in src/aoc.gleam
  7. Add tests in test/aoc_test.gleam

Conventions

  • Naming: mine_dayXX and llm_dayXX for imports to distinguish implementations
  • Types: Define custom types for domain concepts (Movement, Rotation, etc.)
  • Constants: Use module-level const for magic numbers (e.g., const starting_position = 50)
  • Pipeline style: Heavy use of |> operator for data transformation