expectations
Working expectations and documentation practices. Use when capturing learnings or understanding how to work with this codebase.
When & Why to Use This Skill
This Claude skill establishes a comprehensive framework for software development excellence by enforcing Test-Driven Development (TDD) and systematic documentation practices. It optimizes the developer workflow by requiring failing tests before production code, ensuring deep contextual understanding, and capturing critical project 'learnings'—such as architectural decisions, gotchas, and patterns—to prevent technical debt and streamline long-term maintenance.
Use Cases
- Enforcing Development Standards: Automatically applying TDD principles and rigorous code quality checks during the development process to ensure high-reliability software output.
- Knowledge Capture & Documentation: Systematically identifying and documenting non-obvious behaviors, architectural trade-offs, and 'gotchas' to build a robust, searchable knowledge base for the codebase.
- Onboarding & Team Alignment: Providing a clear set of working expectations and communication protocols that ensure consistency when multiple agents or developers interact with the same project.
- Continuous Code Improvement: Implementing a structured 'Refactor after Green' workflow that encourages code cleanup only when it adds measurable value, maintaining a balance between speed and quality.
| name | expectations |
|---|---|
| description | Working expectations and documentation practices. Use when capturing learnings or understanding how to work with this codebase. |
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