dotnet-cqrs/CLAUDE.md

Development Guidelines

Universal development practices for all Svrnty/a-gent repositories.

Engineering Principles

KISS (Keep It Simple)

• Prefer straightforward control flow over clever meta-programming
• Keep error paths obvious and localized

YAGNI (You Aren't Gonna Need It)

• Do not add features without concrete accepted use case
• Do not introduce speculative abstractions

DRY + Rule of Three

• Duplicate small logic when it preserves clarity
• Extract shared utilities only after 3+ repeated patterns

SRP + ISP (Single Responsibility + Interface Segregation)

• Keep each module focused on one concern
• Avoid "god modules" mixing multiple responsibilities

Fail Fast + Explicit Errors

• Prefer explicit errors for unsupported states
• Document fallback behavior when intentional

Secure by Default

• Deny-by-default for access boundaries
• Never log secrets or sensitive payloads

Agent Workflow

1. Read before write - Inspect existing code before editing
2. Define scope - One concern per PR
3. Implement minimal patch - Apply KISS/YAGNI explicitly
4. Validate - Run lint, format, test before commit
5. Document impact - Note behavior changes and risks

Branch Strategy

• All repos use JP branch for active development
• Always verify current branch before committing

Commit Rules

Allowed Authors

Only these emails are permitted for commits:

• jp@svrnty.io (Jean-Philippe Brule)
• mathias@svrnty.io (Mathias Beaulieu-Duncan)

Configure with: git config user.email jp@svrnty.io

AI-Assisted Commits

All AI-authored commits MUST include:

Co-Authored-By: Svrnty Inc. <jp@svrnty.io>

NEVER use third-party AI tool/company names in commits.

Git Hooks Setup

Install lefthook to enforce commit standards:

brew install lefthook
lefthook install

The hooks automatically:

• Validate author email is in allowed list
• Append Co-Authored-By footer
• Warn on conventional commit format violations

PR Discipline

• Clear, scoped commit messages
• Small PRs preferred
• Never commit personal/sensitive data
• Reference related repos for cross-repo changes

Validation

Run before every commit:

• Format check (language-specific)
• Lint check (language-specific)
• Test suite

Anti-Patterns

• Do NOT add heavy dependencies for minor convenience
• Do NOT mix formatting-only with functional changes
• Do NOT modify unrelated modules "while here"
• Do NOT bypass failing checks without explanation

Cross-Repo Changes

• Each repo is standalone with its own build configuration
• Reference related repos in commit messages for cross-repo changes
• Coordinate multi-repo changes via matching branch names
• Test each repo independently before pushing