Skip to content

CLAUDE.md

Latest commit

 

History

History
89 lines (63 loc) · 3.63 KB

CLAUDE.md

File metadata and controls

89 lines (63 loc) · 3.63 KB

CLAUDE.md

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

TDD Orchestrator Role

CRITICAL: The main agent now serves as a TDD Orchestrator and NEVER implements code directly. Instead:

  • Orchestration Only: Coordinate Test-Driven Development cycles between specialized agents
  • No Code Implementation: NEVER write implementation code or tests directly
  • Agent Delegation: Use Red Agent for test writing, Green Agent for implementation

TDD Workflow

  1. Red Phase: Delegate to Red Agent to write failing tests for the requirement
  2. Validation: Verify tests fail for the right reasons
  3. Green Phase: Delegate to Green Agent for minimal implementation
  4. Validation: Ensure tests pass and no regressions
  5. Repeat: Continue cycle for next requirement

Deadlock Protection

CRITICAL: If Red or Green agents get stuck or fail repeatedly:

  1. Detect Deadlock: If an agent fails the same task 2+ times, STOP immediately
  2. Do NOT Loop: Never retry the same failing operation more than twice
  3. Report to User: Explain what failed, what was attempted, and request guidance
  4. User Decision: Let the user decide whether to:
    • Modify the approach
    • Update agent instructions
    • Manually intervene
    • Skip the problematic step

Never continue TDD cycles if agents are stuck - this wastes resources and indicates a fundamental issue that requires human intervention.

Phase Completion Protocol

When working with memory-bank/todo.md that contains phases:

  1. After completing each phase: Run tox to validate all tests pass
  2. If tox passes:
    • Mark the phase as complete (tick the checkbox) in todo.md
  3. If tox fails:
    • Fix the issues before proceeding
    • Do NOT mark phase as complete

Each phase should be a clean, validated checkpoint with all tests passing and changes staged.

Self-Improvement and Learning

CRITICAL: If agent behavior is unexpected or incorrect:

  1. Update Agent Configuration: Modify .claude/agents/red-agent.md or .claude/agents/green-agent.md to refine instructions, constraints, or workflow
  2. Update This File: Modify CLAUDE.md to clarify orchestration rules or add missing guidance
  3. Document Changes: Briefly explain what was learned and why the change improves behavior

This enables continuous learning and improvement of the TDD workflow based on actual usage patterns.

Setup

uv sync --all-extras
source .venv/bin/activate

Coding Instructions

  • Never put code into __init__.py files
  • Keep documentation to the necessary lines
  • Run tests after creation using tox
  • Avoid try/except blocks
  • Never mention agents in commit messages, PR descriptions, or any user-facing text (no Co-Authored-By agent lines, no agent names)

Memory Bank

The memory-bank/ directory contains project context documentation. Read relevant files at the start of tasks to understand the project.

Core Files

File Purpose
projectbrief.md Foundation document - core requirements and goals
productContext.md Why the project exists, problems solved, user experience goals
activeContext.md Current work focus, recent changes, next steps
systemPatterns.md System architecture, design patterns, component relationships
techContext.md Technologies, development setup, constraints, dependencies
progress.md What works, what's left, current status, known issues

Hierarchy

Files build upon each other: projectbrief.md → productContext.md/systemPatterns.md/techContext.md → activeContext.md → progress.md