diff --git a/CLAUDE.md b/CLAUDE.md index 0c0a225..23ca134 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,52 +4,100 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## ๐Ÿšจ IMPORTANT: Development Workflow Guidelines -**Before starting any task, agents MUST assess if tests are needed for the work requested.** +**ALL coding agents MUST follow these mandatory guidelines for every task.** -### Test-Driven Development (TDD) Approach +### ๐Ÿ”„ Fresh Start Protocol -When working on this repository, follow these **mandatory** guidelines: +**BEFORE starting ANY new task or issue:** -1. **Assessment Phase**: Before writing any code, determine if the work requires tests: - - โœ… **Tests Required**: New features, bug fixes, API changes, tool modifications - - โŒ **Tests Optional**: Documentation updates, minor refactoring without behavior changes +1. **Always start from latest main**: + ```bash + git checkout main + git pull origin main # Ensure you have the latest changes + git checkout -b feature/your-branch-name # Create new branch + ``` -2. **TDD Workflow** (when tests are required): +2. **Verify clean state**: ```bash - # 1. Write failing tests FIRST - python -m pytest tests/test_new_feature.py -v # Should fail - - # 2. Write minimal code to make tests pass - # Edit source files... - - # 3. Run tests to verify they pass - python -m pytest tests/test_new_feature.py -v # Should pass - - # 4. Refactor and repeat + git status # Should show clean working directory ``` -3. **Pre-commit Requirements**: - - **ALWAYS run all tests locally** before committing any changes - - **ALL tests must pass** before pushing to remote - - **Format code** with Black before committing - - **Work incrementally** with small, atomic commits +3. **Never carry over unrelated changes** from previous work +4. **Each task gets its own focused branch** from latest main + +### ๐ŸŽฏ Focused Development Rules + +**ONLY make changes directly related to the specific task/issue:** + +- โœ… **DO**: Add/modify code that solves the specific issue +- โœ… **DO**: Add focused tests for the specific functionality +- โœ… **DO**: Update documentation if specifically required +- โŒ **DON'T**: Include formatting changes to unrelated files +- โŒ **DON'T**: Add comprehensive test suites unless specifically requested +- โŒ **DON'T**: Refactor unrelated code +- โŒ **DON'T**: Include previous work from other branches + +### ๐Ÿ“‹ Task Assessment Phase -4. **Incremental Development**: - - Make small, focused changes - - Commit frequently with descriptive messages - - Each commit should represent a working state - - Push regularly to avoid conflicts +Before writing any code, determine scope: -### Mandatory Test Execution +1. **Read the issue/task carefully** - understand exact requirements +2. **Identify minimal changes needed** - what files need modification? +3. **Plan focused tests** - only for the specific functionality being added +4. **Avoid scope creep** - resist urge to "improve" unrelated code + +### ๐Ÿงช Test-Driven Development (TDD) Approach + +When tests are required for the specific task: ```bash -# Before ANY commit, run: -python -m pytest tests/ -v # All tests must pass -black src/ tests/ # Format code -python -m pytest --cov=src tests/ # Verify coverage +# 1. Write failing tests FIRST (focused on the issue) +python -m pytest tests/test_specific_issue.py -v # Should fail + +# 2. Write minimal code to make tests pass +# Edit ONLY files needed for the specific issue + +# 3. Run tests to verify they pass +python -m pytest tests/test_specific_issue.py -v # Should pass + +# 4. Refactor if needed, but stay focused ``` -**โš ๏ธ Never commit or push if tests are failing or not written for new functionality.** +### ๐Ÿ“ Commit Standards + +**Each commit should be atomic and focused:** + +```bash +# Format only the files you changed +black src/specific_file.py tests/test_specific_file.py + +# Run tests to ensure no regressions +python -m pytest tests/ -v + +# Commit with descriptive message +git add src/specific_file.py tests/test_specific_file.py +git commit -m "Fix issue #X: Brief description of what was fixed" +``` + +### ๐Ÿšซ What NOT to Include in PRs + +- Formatting changes to files you didn't functionally modify +- Test files not related to your specific task +- Refactoring of unrelated code +- Documentation updates not specifically requested +- Code from previous branches or incomplete work + +### โœ… PR Quality Checklist + +Before creating PR, verify: +- [ ] Branch created from latest main +- [ ] Only files related to the specific issue are modified +- [ ] Tests pass and are focused on the issue +- [ ] Commit messages are clear and specific +- [ ] No unrelated formatting or code changes +- [ ] PR description clearly links to the issue being solved + +**โš ๏ธ PRs with unrelated changes will be rejected and must be redone.** ## Project Overview