- name
- expectations
- description
- WHEN setting working agreements/TDD rules for this codebase; clarifies boundaries and documentation expectations.
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 >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
#### 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