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

All AI-authored commits MUST use:

Co-Authored-By: Svrnty Inc. <eng@svrnty.com>

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

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

When changes span multiple repos:

1. Commit to each repo separately
2. Reference related repo in commit message
3. Run tests in each affected repo before commit