Skip to content

code-editor-rules.md

Latest commit

 

History

History
224 lines (195 loc) · 8.04 KB

code-editor-rules.md

File metadata and controls

224 lines (195 loc) · 8.04 KB

FavKit Project Rules

Project Context

FavKit is a modern Rust library and CLI tool for managing macOS Finder favorites, replacing the abandoned mysides tool.

Architecture

  1. Clean Architecture

    • Domain Layer (finder/):
      • Pure business logic and types
      • Rich domain model (not anemic)
      • Type-driven development
      • Business rules encoded in types
      • Domain invariants enforced at compile time
    • Implementation Layer (system/):
      • Technical details and infrastructure
      • Adapters for external systems
      • Implementation details

  2. Testing Strategy

    • Outside-In TDD approach:
      1. Start with acceptance tests
      2. Use integration tests with mocks for external APIs
      3. Work inward with unit tests
      4. Implement minimal code to pass
      5. Refactor without changing behavior
    • Test Coverage:
      • Unit tests for all modules
      • Mocks only for outermost layer (macOS API)
      • Thorough error case testing
      • Prefer Result over unwrap

  3. Project Structure

    src/
├── finder/                 # Domain layer
├── system/                 # Implementation layer
    ├── core_foundation.rs  # CF wrappers
    ├── favorites/          # macOS API wrapper
    └── macos/              # Low-level API calls
tests/                      # Tests
├── mock/                   # Test doubles
docs/                       # Documentation
└── adr/                    # ADRs

AI Agent Rules

  1. Rule Acknowledgment

    • State which rule(s) you're following in responses
    • Abbreviate rule descriptions to single words/phrases

  2. Change Management

    • ALWAYS read the file content before making changes
    • Make only explicitly requested changes
    • Stay focused on the specific task
    • Follow existing patterns
    • Document changes clearly
    • Keep conversation context
    • Don’t revert approved changes

  3. Communication

    • Propose improvements after requested changes
    • Wait for user approval
    • Provide clear examples
    • Explain rationale
    • Ask for clarification when in doubt
    • Encourage explicit feedback from the user when uncertain.

  4. Architecture Review

    • Ensure Clean Architecture compliance
    • Follow KISS, DRY, YAGNI, SOLID principles
    • Verify domain isolation
    • Check separation of concerns
    • Review and update ADRs

  5. Response Validation and Reasoning

    • Validate all responses against .cursorrules before presenting them.
    • Include reasoning in the response:
      • Summary: What the response addresses.
      • Validation: State which rules are adhered to.
      • Rationale: Explain why the response is correct or necessary.
    • If a response violates any rules:
      1. Explicitly flag the inconsistency.
      2. Propose fallback or alternative solutions.
      3. Log the issue for refinement.
    • If the model is unsure or lacks information to provide a correct answer:
      • Clearly state: "I do not know the answer."
      • Avoid speculating or guessing.
      • Suggest next steps or alternative approaches to find the answer.

  6. Prompt Handling Best Practices

    • The AI must interpret user prompts clearly and effectively by:
      1. Identifying unclear or vague requests and asking clarifying questions.
      2. Suggesting structured approaches for multi-step tasks.
      3. Providing outputs in the format requested by the user (e.g., examples, summaries, or detailed explanations).
    • For complex prompts, break the response into logical parts and guide the user step by step.
    • Avoid speculation or guessing; if the task or solution is unclear:
      • Explicitly state: "The requested task is ambiguous" or "I need more information."
      • Suggest steps the user can take to refine their request.

  7. Error Handling in Responses

    • If validation fails, responses must:
      1. Explicitly describe the error.
      2. Propose fallback or alternative solutions.
      3. Log inconsistencies for future refinement.

  8. Dynamic Updates

    • Periodically review and update .cursorrules based on evolving project needs and real-world usage feedback.

Technical Requirements

  1. Tech Stack

    [toolchain]
rust = "nightly"
edition = "2024"
components = [
  "rustc", "rust-std", "rust-src",
  "rust-analyzer", "rust-docs",
  "rustfmt", "cargo", "clippy",
  "llvm-tools-preview"
]

[dependencies]
core-foundation = "*"  # https://docs.rs/core-foundation/latest/core_foundation/
core-services = "*"    # https://docs.rs/core-services/latest/core_services/
thiserror = "*"       # https://docs.rs/thiserror/latest/thiserror/
dirs = "*"            # https://docs.rs/dirs/latest/dirs/

[dev-dependencies]
cargo-nextest = "*"   # https://github.com/nextest-rs/nextest
cargo-llvm-cov = "*"  # https://github.com/taiki-e/cargo-llvm-cov
bacon = "*"           # https://github.com/Canop/bacon

  2. Rust Development

    • Type System Usage:
      • Express domain concepts through types
      • Encode business rules in the type system
      • Prevent invalid states at compile time
      // WRONG: Stringly-typed API
fn add_favorite(path: String) -> Result<(), Error>

// RIGHT: Domain concepts in types
struct Target {
    path: ValidPath,
    kind: TargetKind,
}
    • Standard Library Traits:
      • Avoid custom conversion methods like convert or map.
      • Use From, TryFrom, or AsRef for idiomatic conversion and reference operations.
      // WRONG: Custom conversion methods
fn url_to_target() -> Target
fn as_string() -> String
fn into_bytes() -> Vec<u8>

// RIGHT: Standard library traits
impl From<Url> for Target
impl TryFrom<&str> for Url
impl AsRef<str> for Type
impl Into<Vec<u8>> for Type
    • Code Organization:
      • Separate data from behavior
      • Use traits for abstraction
      • Prefer functional style over OOP
      • Use Rust idioms effectively
    • Error Handling:
      • thiserror for definitions
      • Custom error types per module
      • Result for fallible operations
    • Testing the Code:
      • Run the make test command to ensure the code compiles and all tests pass.
      • If errors or test failures occur:
        1. Validate the output to identify the issue.
        2. Apply necessary fixes and re-run the tests.
        3. Confirm all issues are resolved before presenting the final result.

  3. Documentation

    • Clear README
    • API examples
    • Up-to-date ADRs
    • Usage examples
    • Error conditions

  4. Git Commits

    • Follow the Conventional Commits specification.
    • Format: <type>[optional scope]: <description> 
      feat[scope]: Add new CLI option

BREAKING CHANGE: The `-x` flag was removed.

Core Foundation Rules

  1. Memory Management

    • Safe handling of raw pointers
    • Proper memory management in test doubles
    • Prevent dangling pointers
    • Balance CFRetain/CFRelease calls
    • Use system/core_foundation.rs wrappers for additional safety

    Core Foundation Documentation:

  2. Core Foundation Types

    • Type-safe wrappers for:
      • CFType
      • CFString
      • CFArray
      • CFUrl

  3. Mocks

    • Track owned objects in mock structures
    • Retain objects you need to keep
    • Release objects when the mock is dropped