Skip to content

CLAUDE.md

Latest commit

 

History

History
120 lines (97 loc) · 5.58 KB

CLAUDE.md

File metadata and controls

120 lines (97 loc) · 5.58 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Context

This is Phase I of the Hackathon II "Evolution of Todo" project: a simple in-memory Python console Todo application.

You are Claude Code, acting as the sole implementer. No manual coding is allowed — all code must be generated by you based on refined specifications.

The project follows strict Spec-Driven Development using the Spec-Kit Plus workflow:

  • /sp.constitution → Principles and constraints
  • /sp.specify → What to build (requirements and success criteria)
  • /sp.plan → High-level architecture and technical approach
  • /sp.adr → Recorded architectural decisions
  • /sp.analysis → Latest specification analysis confirming readiness

Core Instructions for Claude Code

  1. Always start by reading the full context

    • @/sp.constitution
    • @/sp.specify
    • @/sp.plan
    • @/sp.adr
    • @/sp.analysis

  2. Never write code without an explicit task reference

    • Implementation is only allowed during the /sp.implement phase or when explicitly instructed with a task ID.
    • Reference the source: e.g., "Implementing Task T010 from /sp.tasks – add_task functionality"

  3. Project Structure You Must Create/Maintain

    hackathon-todo/
├── /src/                     # All Python source code
│   ├── main.py               # Entry point with interactive loop
│   ├── models/
│   │   └── task.py           # Task class
│   ├── services/
│   │   └── todo_service.py   # Business logic for task operations
│   └── cli/
│       └── command_handler.py # Command parsing and UI logic
├── specs/                    # Spec-Kit managed (do not edit directly)
├── history/                  # History of prompts and ADRs
├── history/prompts/          # Prompt History Records
├── history/adr/              # Architecture Decision Records
├── CLAUDE.md                 # This file
├── README.md                 # Setup and running instructions
└── .gitignore               # Git ignore patterns

  4. Key Architectural Decisions (from /sp.adr – MUST follow)

    • Interactive prompt loop with commands: add, list, update , delete , complete , exit
    • Task IDs: sequential integers starting from 1
    • Status indicators: [ ] for incomplete, [x] for complete
    • In-memory storage: list of Task objects + separate next_id counter
    • Simple space-split command parsing (no external libraries)
    • Toggle completion: "complete " switches state both ways

  5. Implementation Guidelines

    • Use only Python standard library (no external dependencies for Phase I)
    • Follow Pythonic idioms: type hints, meaningful names, small functions
    • Task model: dataclass or simple class with id: int, title: str, description: str, completed: bool
    • Clear user feedback: success messages, error messages for invalid ID/command, "No tasks yet" when empty
    • Reject empty titles with helpful message
    • Graceful handling of invalid input

  6. When Implementing

    • Generate complete, runnable files
    • Place code in /src as per structure
    • Ensure python -m src.main or python src/main.py runs the interactive app
    • After generation, suggest manual testing steps matching success criteria

  7. README.md Content to Generate Include:

    • Project title and phase
    • Setup: Python 3.13+, WSL2 note for Windows
    • Run command: python src/main.py
    • List of supported commands
    • Brief demo of usage

You are now ready to implement only when instructed with specific tasks or "/sp.implement".

Success depends on precise adherence to the specs and decisions above.

Code Architecture and Structure

The application follows a clean architecture with separation of concerns across three main layers:

  1. Models Layer (src/models/task.py): Contains the Task class with validation and string representation

    • Task class with id, title, description, and completed attributes
    • Validation for required fields and data types
    • String representation with status indicators

  2. Services Layer (src/services/todo_service.py): Business logic for task operations

    • In-memory storage using a list of Task objects
    • Sequential ID generation with separate next_id counter
    • Core operations: add, list, update, toggle complete, delete
    • Error handling for invalid operations

  3. CLI Layer (src/cli/command_handler.py): Command parsing and user interaction

    • Command parsing with support for quoted strings using regex
    • Command dispatch to appropriate service methods
    • User feedback and error messages
    • Interactive command loop integration

Development Commands

  • Initialize project: uv sync (install dependencies from pyproject.toml)
  • Run the application: uv run python src/main.py
  • Run tests: uv run python test_app.py
  • Check syntax: uv run python -m py_compile src/**/*.py
  • Manual verification: Follow examples in README.md

Key Implementation Details

  • The application uses a regex-based parsing approach for commands with quoted string support
  • Task IDs are sequential integers starting from 1 and never reused after deletion
  • Status indicators use [ ] for incomplete and [x] for complete tasks
  • The toggle_complete method handles both directions (incomplete → complete, complete → incomplete)
  • Error handling includes validation for empty titles, invalid IDs, and invalid commands
  • No external dependencies - uses only Python standard library