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 development standards and documentation practices. It streamlines codebase management by enforcing Test-Driven Development (TDD), defining clear communication protocols, and providing a structured methodology for capturing institutional knowledge, 'gotchas', and architectural decisions to ensure long-term project maintainability.
Use Cases
- Accelerating developer onboarding by providing a clear set of working expectations and documentation standards for a specific codebase.
- Enforcing high-quality engineering standards through a strict 'Test-Driven Development (TDD) first' policy for all production code changes.
- Building a searchable knowledge base of 'Gotchas' and anti-patterns to prevent recurring bugs and save future development time.
- Maintaining consistent project documentation (such as CLAUDE.md) by prompting for updates whenever significant architectural changes or decisions are made.
- Standardizing communication within technical teams regarding design trade-offs, refactoring assessments, and requirement clarifications.
| 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