Expectations

When Working with Code

• ALWAYS FOLLOW TDD - No production code without a failing test. Non-negotiable.

• Think deeply before making any edits

• Understand the full context of the code and requirements

• Ask clarifying questions when requirements are ambiguous

• Think from first principles - don't make assumptions

• Assess refactoring after every green - but only refactor if it adds value

• Keep project docs current - Update CLAUDE.md when introducing meaningful changes

Documentation Framework

At the end of every significant change, ask: "What do I wish I'd known at the start?"

Document if ANY of these are true:

• Would save future developers significant time

• Prevents a class of bugs or errors

• Reveals non-obvious behavior or constraints

• Captures architectural rationale or trade-offs

• Documents domain-specific knowledge

• Identifies effective patterns or anti-patterns

• Clarifies tool setup or configuration gotchas

Types of Learnings to Capture

• Gotchas: Unexpected behavior discovered (e.g., "API returns null instead of empty array")

• Patterns: Approaches that worked particularly well

• Anti-patterns: Approaches that seemed good but caused problems

• Decisions: Architectural choices with rationale and trade-offs

• Edge cases: Non-obvious scenarios that required special handling

• Tool knowledge: Setup, configuration, or usage insights

Documentation Format

Gotcha: [Descriptive Title]

Context: When this occurs Issue: What goes wrong Solution: How to handle it

// CORRECT - Solution const example = "correct approach";

// WRONG - What causes the problem const wrong = "incorrect approach";

Code Change Principles

• Start with a failing test - always. No exceptions.

• After making tests pass, always assess refactoring opportunities

• After refactoring, verify all tests and static analysis pass, then commit

• Respect the existing patterns and conventions

• Maintain test coverage for all behavior changes

• Keep changes small and incremental

• Ensure all TypeScript strict mode requirements are met

• Provide rationale for significant design decisions

If you find yourself writing production code without a failing test, STOP immediately and write the test first.

Communication

• Be explicit about trade-offs in different approaches

• Explain the reasoning behind significant design decisions

• Flag any deviations from guidelines with justification

• Suggest improvements that align with these principles

• When unsure, ask for clarification rather than assuming