153 lines
4.0 KiB
Markdown
153 lines
4.0 KiB
Markdown
# Development Guidelines
|
|
|
|
## Philosophy
|
|
|
|
### Core Beliefs
|
|
|
|
- **Incremental progress over big bangs** - Small changes that compile and pass tests
|
|
- **Learning from existing code** - Study and plan before implementing
|
|
- **Pragmatic over dogmatic** - Adapt to project reality
|
|
- **Clear intent over clever code** - Be boring and obvious
|
|
|
|
### Simplicity Means
|
|
|
|
- Single responsibility per function/class
|
|
- Avoid premature abstractions
|
|
- No clever tricks - choose the boring solution
|
|
- If you need to explain it, it's too complex
|
|
|
|
## Process
|
|
|
|
### 1. Planning & Staging
|
|
|
|
Break complex work into 3-5 stages. Document in `IMPLEMENTATION_PLAN.md`:
|
|
|
|
```markdown
|
|
## Stage N: [Name]
|
|
**Goal**: [Specific deliverable]
|
|
**Success Criteria**: [Testable outcomes]
|
|
**Tests**: [Specific test cases]
|
|
**Status**: [Not Started|In Progress|Complete]
|
|
```
|
|
- Update status as you progress
|
|
- Remove file when all stages are done
|
|
|
|
### 2. Implementation Flow
|
|
|
|
1. **Understand** - Study existing patterns in codebase
|
|
2. **Test** - Write test first (red)
|
|
3. **Implement** - Minimal code to pass (green)
|
|
4. **Refactor** - Clean up with tests passing
|
|
5. **Commit** - With clear message linking to plan
|
|
|
|
### 3. When Stuck (After 3 Attempts)
|
|
|
|
**CRITICAL**: Maximum 3 attempts per issue, then STOP.
|
|
|
|
1. **Document what failed**:
|
|
- What you tried
|
|
- Specific error messages
|
|
- Why you think it failed
|
|
|
|
2. **Research alternatives**:
|
|
- Find 2-3 similar implementations
|
|
- Note different approaches used
|
|
|
|
3. **Question fundamentals**:
|
|
- Is this the right abstraction level?
|
|
- Can this be split into smaller problems?
|
|
- Is there a simpler approach entirely?
|
|
|
|
4. **Try different angle**:
|
|
- Different library/framework feature?
|
|
- Different architectural pattern?
|
|
- Remove abstraction instead of adding?
|
|
|
|
## Technical Standards
|
|
|
|
### Architecture Principles
|
|
|
|
- **Composition over inheritance** - Use dependency injection
|
|
- **Interfaces over singletons** - Enable testing and flexibility
|
|
- **Explicit over implicit** - Clear data flow and dependencies
|
|
- **Test-driven when possible** - Never disable tests, fix them
|
|
|
|
### Code Quality
|
|
|
|
- **Every commit must**:
|
|
- Compile successfully
|
|
- Pass all existing tests
|
|
- Include tests for new functionality
|
|
- Follow project formatting/linting
|
|
|
|
- **Before committing**:
|
|
- Run formatters/linters
|
|
- Self-review changes
|
|
- Ensure commit message explains "why"
|
|
|
|
### Error Handling
|
|
|
|
- Fail fast with descriptive messages
|
|
- Include context for debugging
|
|
- Handle errors at appropriate level
|
|
- Never silently swallow exceptions
|
|
|
|
## Decision Framework
|
|
|
|
When multiple valid approaches exist, choose based on:
|
|
|
|
1. **Testability** - Can I easily test this?
|
|
2. **Readability** - Will someone understand this in 6 months?
|
|
3. **Consistency** - Does this match project patterns?
|
|
4. **Simplicity** - Is this the simplest solution that works?
|
|
5. **Reversibility** - How hard to change later?
|
|
|
|
## Project Integration
|
|
|
|
### Learning the Codebase
|
|
|
|
- Find 3 similar features/components
|
|
- Identify common patterns and conventions
|
|
- Use same libraries/utilities when possible
|
|
- Follow existing test patterns
|
|
|
|
### Tooling
|
|
|
|
- Use project's existing build system
|
|
- Use project's test framework
|
|
- Use project's formatter/linter settings
|
|
- Don't introduce new tools without strong justification
|
|
|
|
## Quality Gates
|
|
|
|
### Definition of Done
|
|
|
|
- [ ] Tests written and passing
|
|
- [ ] Code follows project conventions
|
|
- [ ] No linter/formatter warnings
|
|
- [ ] Commit messages are clear
|
|
- [ ] Implementation matches plan
|
|
- [ ] No TODOs without issue numbers
|
|
|
|
### Test Guidelines
|
|
|
|
- Test behavior, not implementation
|
|
- One assertion per test when possible
|
|
- Clear test names describing scenario
|
|
- Use existing test utilities/helpers
|
|
- Tests should be deterministic
|
|
|
|
## Important Reminders
|
|
|
|
**NEVER**:
|
|
- Use `--no-verify` to bypass commit hooks
|
|
- Disable tests instead of fixing them
|
|
- Commit code that doesn't compile
|
|
- Make assumptions - verify with existing code
|
|
|
|
**ALWAYS**:
|
|
- Commit working code incrementally
|
|
- Update plan documentation as you go
|
|
- Learn from existing implementations
|
|
- Stop after 3 failed attempts and reassess
|