CLAUDE.md

Claude Code Instructions

This document contains guidelines for Claude Code to follow when working on this project.

Development Process

• Keep development agile and iterative with tight feedback loops
• Focus on small wins rather than trying to accomplish too much at once
• Maintain awareness of the current code state, desired state, and results
• Follow the Observe-Orient-Run-Reflect cycle:
  • Observe: Understand the current code state and problem
  • Orient: Write code to achieve the desired state
  • Run: Execute the code and tests
  • Reflect: Evaluate results and adjust if needed

Code Style

• Follow existing project conventions for formatting, naming, and documentation
• Assume style is enforced by a linter and formatter
• Focus comments on explaining functionality and design choices, not how code changed during the session
• Do not add descriptive comments unless requested

Docker Usage

When working with Docker:

• Use Dockerfile and docker-compose.yml files in the root directory
• Always redirect output for verbose commands:

  docker compose up --build -d --quiet-pull > docker-build.log 2>&1

• Use quiet flags when available
• Check container status with docker compose ps rather than viewing build output
• Redirect output for Nix operations

Terminal Usage

• Assume the shell is zsh
• Preserve context window by minimizing command output:
  • Redirect verbose output: command > output.log 2>&1
  • Use quiet/silent flags: --quiet, -q, --silent, etc.
  • Filter output with grep, head, tail, etc.
  • Summarize output when possible
• Execute commands incrementally and verify output at each step
• Explain commands before executing them

Testing

• Test code in Docker containers when necessary
• Reduce test output verbosity by using redirects and quiet flags
• Filter output to show only relevant information

Documentation

• Store documentation in the root /docs folder
• Keep documentation organized, structured, and easy to navigate
• Update documentation files after completing tasks
• Use TODO.md to track outstanding tasks
• Create separate TODO files in /docs for multi-task TODOs

Task Management

• Break complex tasks into manageable subtasks
• Prioritize subtasks based on dependencies
• Use the TodoWrite and TodoRead tools to track task progress
• Mark tasks as complete immediately after finishing them
• Only have one task in progress at a time
• Maintain detailed progress information

Context Preservation

• Monitor context window usage throughout the session
• When implementing solutions:
  • Focus on completing current subtask fully
  • Document progress clearly
  • Create checkpoints at logical completion points
• Include detailed information in handoffs:
  • Completed work
  • Current state
  • Next steps
  • Reference information

Shell Commands Style

• Prefer concise commands that produce minimal output
• Redirect verbose output to log files
• Use quiet/silent flags when available
• Filter output to show only relevant information
• Test commands with limited scope before running more broadly
• Break complex operations into smaller steps
• Explain commands before executing them

Important Reminders

• Focus on small wins rather than trying to accomplish too much at once
• Don't add unnecessary explanatory comments to code
• Always respond concisely with fewer than 4 lines of text unless asked for detail
• Use TodoWrite and TodoRead tools to manage tasks effectively
• Ensure all code works properly before submitting