|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +> Project instructions for AI assistants working on activerecord-null gem |
| 4 | +
|
| 5 | +## Agent OS Documentation |
| 6 | + |
| 7 | +### Product Context |
| 8 | +- **Mission & Vision:** @.agent-os/product/mission.md |
| 9 | +- **Technical Architecture:** @.agent-os/product/tech-stack.md |
| 10 | +- **Development Roadmap:** @.agent-os/product/roadmap.md |
| 11 | +- **Decision History:** @.agent-os/product/decisions.md |
| 12 | + |
| 13 | +### Development Standards |
| 14 | +- **Code Style:** @~/.agent-os/standards/code-style.md |
| 15 | +- **Best Practices:** @~/.agent-os/standards/best-practices.md |
| 16 | + |
| 17 | +### Project Management |
| 18 | +- **Active Specs:** @.agent-os/specs/ |
| 19 | +- **Spec Planning:** Use `@~/.agent-os/instructions/create-spec.md` |
| 20 | +- **Tasks Execution:** Use `@~/.agent-os/instructions/execute-tasks.md` |
| 21 | + |
| 22 | +## Workflow Instructions |
| 23 | + |
| 24 | +When asked to work on this codebase: |
| 25 | + |
| 26 | +1. **First**, check @.agent-os/product/roadmap.md for current priorities |
| 27 | +2. **Then**, follow the appropriate instruction file: |
| 28 | + - For new features: @~/.agent-os/instructions/create-spec.md |
| 29 | + - For tasks execution: @~/.agent-os/instructions/execute-tasks.md |
| 30 | +3. **Always**, adhere to the standards in the files listed above |
| 31 | + |
| 32 | +## Important Notes |
| 33 | + |
| 34 | +- Product-specific files in `.agent-os/product/` override any global standards |
| 35 | +- User's specific instructions override (or amend) instructions found in `.agent-os/specs/...` |
| 36 | +- Always adhere to established patterns, code style, and best practices documented above |
| 37 | + |
| 38 | +## Project-Specific Guidelines |
| 39 | + |
| 40 | +### This is a Ruby Gem Library |
| 41 | + |
| 42 | +This is NOT a Rails application - it's a library gem that extends ActiveRecord. Keep this context in mind: |
| 43 | + |
| 44 | +- No application hosting, database hosting, or asset hosting |
| 45 | +- Focus is on library code quality, API design, and compatibility |
| 46 | +- Tests use SQLite3 in-memory database |
| 47 | +- Must maintain backward compatibility within major versions |
| 48 | + |
| 49 | +### Code Style Enforcement |
| 50 | + |
| 51 | +Before committing, ALWAYS run: |
| 52 | +```bash |
| 53 | +bundle exec standardrb --fix |
| 54 | +``` |
| 55 | + |
| 56 | +All code must pass Standard linting. No exceptions. |
| 57 | + |
| 58 | +### Testing Requirements |
| 59 | + |
| 60 | +- Use Minitest (not RSpec) |
| 61 | +- All new features must have comprehensive test coverage |
| 62 | +- Run tests with: `rake test` (default rake task) |
| 63 | +- Tests are in `test/` directory following Minitest conventions |
| 64 | + |
| 65 | +### Release Process |
| 66 | + |
| 67 | +This gem uses Reissue for release management: |
| 68 | + |
| 69 | +1. Use git trailers for changelog entries in commits |
| 70 | +2. Run `rake build:checksum` to build gem and generate checksums |
| 71 | +3. Run `rake release` to create git tag, push commits/tags, and push to RubyGems |
| 72 | +4. Reissue automatically increments version and updates changelog |
| 73 | + |
| 74 | +**Never manually edit:** |
| 75 | +- `lib/activerecord/null/version.rb` (managed by Reissue) |
| 76 | +- `CHANGELOG.md` (generated from git trailers) |
| 77 | + |
| 78 | +### ActiveRecord Compatibility |
| 79 | + |
| 80 | +- Minimum ActiveRecord version: 7.0 |
| 81 | +- Minimum Ruby version: 3.0.0 |
| 82 | +- Test against multiple ActiveRecord versions if adding complex features |
| 83 | +- Be mindful of ActiveRecord's reflection API and association internals |
| 84 | + |
| 85 | +### Design Philosophy |
| 86 | + |
| 87 | +From @.agent-os/product/decisions.md: |
| 88 | + |
| 89 | +1. **Drop-in Replacement:** Null objects should work anywhere real records work |
| 90 | +2. **Singleton Pattern:** One null object instance per model class |
| 91 | +3. **Zero Configuration:** Associations and attributes work automatically |
| 92 | +4. **Simple API:** Creating null objects should be easy and obvious |
| 93 | + |
| 94 | +### Current Phase |
| 95 | + |
| 96 | +Per @.agent-os/product/roadmap.md, we are in **Phase 1: Edge Case Exploration** |
| 97 | + |
| 98 | +Focus areas: |
| 99 | +- Finding and fixing edge cases |
| 100 | +- Testing complex association scenarios |
| 101 | +- Ensuring production-ready stability |
| 102 | +- Documenting limitations and known issues |
| 103 | + |
| 104 | +When proposing new features, consider whether they: |
| 105 | +1. Fix an edge case or bug |
| 106 | +2. Improve compatibility with Rails ecosystem |
| 107 | +3. Maintain API simplicity |
| 108 | +4. Are backwards compatible |
0 commit comments