Establish AI-Assisted Development Guidelines in AI_DEVELOPMENT_GUIDELINES.md

[1amageek]

Motivation

AI-assisted development is becoming more common in this project. Based on feedback from PR #17, we should establish clear guidelines to maintain code quality and respect maintainer time.

The review feedback from PR #16 (@glbrntt and @MMcM) provided valuable insights on:

• Type safety (compiler synthesis, enum usage)
• Performance (avoiding allocations)
• API design (namespace pollution, Swift idioms)
• Code clarity (guard vs if, control flow)

These perspectives should be captured in guidelines to ensure consistency and quality across contributions.

Proposal

Create AI_DEVELOPMENT_GUIDELINES.md with initial guidelines covering:

Contribution Process

• Require GitHub issue creation before PRs
• Link PRs to issues using GitHub keywords (Fixes/Closes/Resolves #123)
• Keep PRs focused and reasonably sized (~500 lines excluding tests)

Code Style and Documentation

• Avoid emojis and unnecessary verbosity
• Follow Swift API Design Guidelines (https://www.swift.org/documentation/api-design-guidelines/)
• Keep comments concise and focused

Implementation and Review Considerations

• Type safety (prefer enums over raw values, use compiler synthesis)
• Control flow (appropriate use of guard vs if)
• Performance (avoid unnecessary allocations)
• API design (follow FDB conventions, avoid namespace pollution)
• Error handling (struct-based errors with clear messages)

Self-Review Checklist

A checklist to verify before submission

Growing the Guidelines

These guidelines will start minimal and grow through the review process. As new insights emerge from code reviews, we'll update the guidelines to capture that knowledge.