Expectations

When Working with Code

1. Think deeply before making any edits
2. Understand the full context of the code and requirements
3. Ask clarifying questions when requirements are ambiguous
4. Think from first principles - don't make assumptions
5. Assess refactoring after every green - but only refactor if it adds value
6. 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 >30 minutes
• 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

markdown
1#### Gotcha: [Descriptive Title]
2
3**Context**: When this occurs
4**Issue**: What goes wrong
5**Solution**: How to handle it
6
7// CORRECT - Solution
8const example = "correct approach";
9
10// WRONG - What causes the problem
11const 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