docs(claude): add feature development quality standards
- Add comprehensive testing requirements (85% coverage minimum) - Add git workflow requirements with conventional commits - Add documentation synchronization requirements - Add feature completion checklist - Integrate with Ralph loop and @fix_plan.md workflow - Include template file updates for AGENT.md - Add Ralph-specific testing patterns and quality gates
This commit is contained in:
frankbria
parent
c0ea071b3e
commit
cc8d2b52b9
2 changed files with 231 additions and 1 deletions
118
CLAUDE.md
118
CLAUDE.md
|
|
@ -134,3 +134,121 @@ Ralph integrates with:
|
|||
- `MAX_CONSECUTIVE_DONE_SIGNALS=2` - Exit on repeated completion signals
|
||||
- `TEST_PERCENTAGE_THRESHOLD=30%` - Flag if testing dominates recent loops
|
||||
- Completion detection via @fix_plan.md checklist items
|
||||
|
||||
## Feature Development Quality Standards
|
||||
|
||||
**CRITICAL**: All new features MUST meet the following mandatory requirements before being considered complete.
|
||||
|
||||
### Testing Requirements
|
||||
|
||||
- **Minimum Coverage**: 85% code coverage ratio required for all new code
|
||||
- **Test Pass Rate**: 100% - all tests must pass, no exceptions
|
||||
- **Test Types Required**:
|
||||
- Unit tests for bash script functions (if applicable)
|
||||
- Integration tests for Ralph loop behavior
|
||||
- End-to-end tests for full development cycles
|
||||
- **Coverage Validation**: Run coverage reports before marking features complete:
|
||||
```bash
|
||||
# For projects with test suites
|
||||
./test.sh --coverage
|
||||
|
||||
# Manual testing of Ralph loop
|
||||
ralph --monitor --calls 5
|
||||
```
|
||||
- **Test Quality**: Tests must validate behavior, not just achieve coverage metrics
|
||||
- **Test Documentation**: Complex test scenarios must include comments explaining the test strategy
|
||||
|
||||
### Git Workflow Requirements
|
||||
|
||||
Before moving to the next feature, ALL changes must be:
|
||||
|
||||
1. **Committed with Clear Messages**:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat(module): descriptive message following conventional commits"
|
||||
```
|
||||
- Use conventional commit format: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, etc.
|
||||
- Include scope when applicable: `feat(loop):`, `fix(monitor):`, `test(setup):`
|
||||
- Write descriptive messages that explain WHAT changed and WHY
|
||||
|
||||
2. **Pushed to Remote Repository**:
|
||||
```bash
|
||||
git push origin <branch-name>
|
||||
```
|
||||
- Never leave completed features uncommitted
|
||||
- Push regularly to maintain backup and enable collaboration
|
||||
- Ensure CI/CD pipelines pass before considering feature complete
|
||||
|
||||
3. **Branch Hygiene**:
|
||||
- Work on feature branches, never directly on `main`
|
||||
- Branch naming convention: `feature/<feature-name>`, `fix/<issue-name>`, `docs/<doc-update>`
|
||||
- Create pull requests for all significant changes
|
||||
|
||||
4. **Ralph Integration**:
|
||||
- Update @fix_plan.md with new tasks before starting work
|
||||
- Mark items complete in @fix_plan.md upon completion
|
||||
- Update PROMPT.md if Ralph's behavior needs modification
|
||||
- Test Ralph loop with new features before completion
|
||||
|
||||
### Documentation Requirements
|
||||
|
||||
**ALL implementation documentation MUST remain synchronized with the codebase**:
|
||||
|
||||
1. **Script Documentation**:
|
||||
- Bash: Comments for all functions and complex logic
|
||||
- Update inline comments when implementation changes
|
||||
- Remove outdated comments immediately
|
||||
|
||||
2. **Implementation Documentation**:
|
||||
- Update relevant sections in this CLAUDE.md file
|
||||
- Keep template files in `templates/` current
|
||||
- Update configuration examples when defaults change
|
||||
- Document breaking changes prominently
|
||||
|
||||
3. **README Updates**:
|
||||
- Keep feature lists current
|
||||
- Update setup instructions when commands change
|
||||
- Maintain accurate command examples
|
||||
- Update version compatibility information
|
||||
|
||||
4. **Template Maintenance**:
|
||||
- Update template files when new patterns are introduced
|
||||
- Keep PROMPT.md template current with best practices
|
||||
- Update @AGENT.md template with new build patterns
|
||||
- Document new Ralph configuration options
|
||||
|
||||
5. **CLAUDE.md Maintenance**:
|
||||
- Add new commands to "Key Commands" section
|
||||
- Update "Exit Conditions and Thresholds" when logic changes
|
||||
- Keep installation instructions accurate and tested
|
||||
- Document new Ralph loop behaviors or quality gates
|
||||
|
||||
### Feature Completion Checklist
|
||||
|
||||
Before marking ANY feature as complete, verify:
|
||||
|
||||
- [ ] All tests pass (if applicable)
|
||||
- [ ] Code coverage meets 85% minimum threshold (if applicable)
|
||||
- [ ] Script functionality manually tested
|
||||
- [ ] All changes committed with conventional commit messages
|
||||
- [ ] All commits pushed to remote repository
|
||||
- [ ] @fix_plan.md task marked as complete
|
||||
- [ ] Implementation documentation updated
|
||||
- [ ] Inline code comments updated or added
|
||||
- [ ] CLAUDE.md updated (if new patterns introduced)
|
||||
- [ ] Template files updated (if applicable)
|
||||
- [ ] Breaking changes documented
|
||||
- [ ] Ralph loop tested with new features
|
||||
- [ ] Installation process verified (if applicable)
|
||||
|
||||
### Rationale
|
||||
|
||||
These standards ensure:
|
||||
- **Quality**: Thorough testing prevents regressions in Ralph's autonomous behavior
|
||||
- **Traceability**: Git commits and @fix_plan.md provide clear history of changes
|
||||
- **Maintainability**: Current documentation reduces onboarding time and prevents knowledge loss
|
||||
- **Collaboration**: Pushed changes enable team visibility and code review
|
||||
- **Reliability**: Consistent quality gates maintain Ralph loop stability
|
||||
- **Automation**: Ralph integration ensures continuous development practices
|
||||
|
||||
**Enforcement**: AI agents should automatically apply these standards to all feature development tasks without requiring explicit instruction for each task.
|
||||
|
|
|
|||
|
|
@ -44,3 +44,115 @@ cargo run
|
|||
- Update this section when you learn new build optimizations
|
||||
- Document any gotchas or special setup requirements
|
||||
- Keep track of the fastest test/build cycle
|
||||
|
||||
## Feature Development Quality Standards
|
||||
|
||||
**CRITICAL**: All new features MUST meet the following mandatory requirements before being considered complete.
|
||||
|
||||
### Testing Requirements
|
||||
|
||||
- **Minimum Coverage**: 85% code coverage ratio required for all new code
|
||||
- **Test Pass Rate**: 100% - all tests must pass, no exceptions
|
||||
- **Test Types Required**:
|
||||
- Unit tests for all business logic and services
|
||||
- Integration tests for API endpoints or main functionality
|
||||
- End-to-end tests for critical user workflows
|
||||
- **Coverage Validation**: Run coverage reports before marking features complete:
|
||||
```bash
|
||||
# Examples by language/framework
|
||||
npm run test:coverage
|
||||
pytest --cov=src tests/ --cov-report=term-missing
|
||||
cargo tarpaulin --out Html
|
||||
```
|
||||
- **Test Quality**: Tests must validate behavior, not just achieve coverage metrics
|
||||
- **Test Documentation**: Complex test scenarios must include comments explaining the test strategy
|
||||
|
||||
### Git Workflow Requirements
|
||||
|
||||
Before moving to the next feature, ALL changes must be:
|
||||
|
||||
1. **Committed with Clear Messages**:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat(module): descriptive message following conventional commits"
|
||||
```
|
||||
- Use conventional commit format: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, etc.
|
||||
- Include scope when applicable: `feat(api):`, `fix(ui):`, `test(auth):`
|
||||
- Write descriptive messages that explain WHAT changed and WHY
|
||||
|
||||
2. **Pushed to Remote Repository**:
|
||||
```bash
|
||||
git push origin <branch-name>
|
||||
```
|
||||
- Never leave completed features uncommitted
|
||||
- Push regularly to maintain backup and enable collaboration
|
||||
- Ensure CI/CD pipelines pass before considering feature complete
|
||||
|
||||
3. **Branch Hygiene**:
|
||||
- Work on feature branches, never directly on `main`
|
||||
- Branch naming convention: `feature/<feature-name>`, `fix/<issue-name>`, `docs/<doc-update>`
|
||||
- Create pull requests for all significant changes
|
||||
|
||||
4. **Ralph Integration**:
|
||||
- Update @fix_plan.md with new tasks before starting work
|
||||
- Mark items complete in @fix_plan.md upon completion
|
||||
- Update PROMPT.md if development patterns change
|
||||
- Test features work within Ralph's autonomous loop
|
||||
|
||||
### Documentation Requirements
|
||||
|
||||
**ALL implementation documentation MUST remain synchronized with the codebase**:
|
||||
|
||||
1. **Code Documentation**:
|
||||
- Language-appropriate documentation (JSDoc, docstrings, etc.)
|
||||
- Update inline comments when implementation changes
|
||||
- Remove outdated comments immediately
|
||||
|
||||
2. **Implementation Documentation**:
|
||||
- Update relevant sections in this AGENT.md file
|
||||
- Keep build and test commands current
|
||||
- Update configuration examples when defaults change
|
||||
- Document breaking changes prominently
|
||||
|
||||
3. **README Updates**:
|
||||
- Keep feature lists current
|
||||
- Update setup instructions when dependencies change
|
||||
- Maintain accurate command examples
|
||||
- Update version compatibility information
|
||||
|
||||
4. **AGENT.md Maintenance**:
|
||||
- Add new build patterns to relevant sections
|
||||
- Update "Key Learnings" with new insights
|
||||
- Keep command examples accurate and tested
|
||||
- Document new testing patterns or quality gates
|
||||
|
||||
### Feature Completion Checklist
|
||||
|
||||
Before marking ANY feature as complete, verify:
|
||||
|
||||
- [ ] All tests pass with appropriate framework command
|
||||
- [ ] Code coverage meets 85% minimum threshold
|
||||
- [ ] Coverage report reviewed for meaningful test quality
|
||||
- [ ] Code formatted according to project standards
|
||||
- [ ] Type checking passes (if applicable)
|
||||
- [ ] All changes committed with conventional commit messages
|
||||
- [ ] All commits pushed to remote repository
|
||||
- [ ] @fix_plan.md task marked as complete
|
||||
- [ ] Implementation documentation updated
|
||||
- [ ] Inline code comments updated or added
|
||||
- [ ] AGENT.md updated (if new patterns introduced)
|
||||
- [ ] Breaking changes documented
|
||||
- [ ] Features tested within Ralph loop (if applicable)
|
||||
- [ ] CI/CD pipeline passes
|
||||
|
||||
### Rationale
|
||||
|
||||
These standards ensure:
|
||||
- **Quality**: High test coverage and pass rates prevent regressions
|
||||
- **Traceability**: Git commits and @fix_plan.md provide clear history of changes
|
||||
- **Maintainability**: Current documentation reduces onboarding time and prevents knowledge loss
|
||||
- **Collaboration**: Pushed changes enable team visibility and code review
|
||||
- **Reliability**: Consistent quality gates maintain production stability
|
||||
- **Automation**: Ralph integration ensures continuous development practices
|
||||
|
||||
**Enforcement**: AI agents should automatically apply these standards to all feature development tasks without requiring explicit instruction for each task.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue