template/docs/CONVENTIONS.md

# Conventions

This document defines project engineering standards. It should remain practical,
specific, and enforceable.

For project facts, see [PROJECT.md](PROJECT.md).
For architecture boundaries, see [ARCHITECTURE.md](ARCHITECTURE.md).
For task quality gates, see [CHECKLISTS.md](CHECKLISTS.md).

## Naming

Use names that expose intent and domain meaning.

- Prefer domain terms over technical shorthand.
- Avoid abbreviations unless they are widely understood in the project.
- Name booleans as predicates, such as `isEnabled`, `hasPermission`, or
  `canRetry`.
- Name commands by action and object, such as `CreateInvoice` or
  `syncCustomer`.
- Name events in past tense when they represent something that happened.

Add language-specific naming rules here:

- `{{LANGUAGE_NAMING_RULE}}`

## File Organization

Files should have one clear responsibility.

- Keep files small enough to review comfortably.
- Co-locate tests with the tested module when that matches the stack convention.
- Separate generated files from hand-written source.
- Avoid catch-all utility files that collect unrelated behavior.

Project-specific rules:

- `{{FILE_ORGANIZATION_RULE}}`

## Folder Organization

Folders should communicate ownership and architecture boundaries.

- Organize by feature or module when domain ownership matters.
- Organize by technical layer only when it improves clarity for the project.
- Keep public interfaces easy to find.
- Keep infrastructure details out of domain folders unless deliberately chosen.

Project-specific folder map:

| Folder | Rule |
| --- | --- |
| `{{FOLDER}}` | `{{FOLDER_RULE}}` |

## Dependency Injection

Use dependency injection to make boundaries explicit and tests practical.

- Inject external resources, clocks, random generators, HTTP clients, file
  systems, queues, and database access.
- Avoid service locators unless the framework requires them.
- Keep object lifetimes explicit.
- Do not inject dependencies that are pure values or local implementation
  details.

Project-specific DI rules:

- `{{DEPENDENCY_INJECTION_RULE}}`

## Logging

Logging should support operations and debugging without leaking sensitive data.

- Use structured logs when the platform supports them.
- Include correlation or request identifiers.
- Log decisions and external failures at meaningful boundaries.
- Do not log secrets, access tokens, passwords, private keys, or full payment
  data.
- Avoid noisy logs inside tight loops or high-volume paths.

Project-specific logging rules:

- `{{LOGGING_RULE}}`

## Validation

Validation should happen at the correct boundary.

- Validate transport shape at the interface boundary.
- Validate business invariants in the domain or application layer.
- Validate persistence constraints before relying on database failures for
  expected user errors.
- Return actionable validation feedback where appropriate.

Project-specific validation rules:

- `{{VALIDATION_RULE}}`

## Error Handling

Errors should be explicit, observable, and safe.

- Use typed or structured errors where the language supports them.
- Do not swallow exceptions without a recovery path.
- Map internal errors to stable user-facing or client-facing responses.
- Preserve diagnostic context for logs.
- Avoid exposing stack traces or implementation details to users.

Project-specific error rules:

- `{{ERROR_HANDLING_RULE}}`

## DTO Rules

DTOs represent boundary contracts.

- Keep DTOs separate from domain models when they change for different reasons.
- Do not put business rules in DTOs.
- Version public contracts deliberately.
- Validate DTO shape before mapping to domain commands or queries.
- Avoid leaking persistence models through public APIs.

Project-specific DTO rules:

- `{{DTO_RULE}}`

## Repository Rules

Repositories, gateways, or data access abstractions should express persistence
intent without hiding important consistency behavior.

- Keep query methods specific enough to reveal purpose.
- Avoid generic repositories when they obscure domain behavior.
- Document transaction boundaries.
- Make idempotency explicit for write operations where retries are possible.

Project-specific repository rules:

- `{{REPOSITORY_RULE}}`

## Service Rules

Services should coordinate use cases, not become unbounded containers.

- Prefer cohesive application services around use cases.
- Keep domain rules in domain objects or domain services.
- Keep infrastructure calls behind clear interfaces.
- Avoid services named only after technical actions such as `Manager`,
  `Helper`, or `Processor` unless the meaning is precise in context.

Project-specific service rules:

- `{{SERVICE_RULE}}`

## Testing

Tests should match risk and behavior.

- Unit test domain logic and pure transformations.
- Integration test database, queue, file, network, and framework boundaries.
- End-to-end test critical user journeys.
- Regression test bugs before or with the fix.
- Keep tests deterministic and independent where practical.

Project-specific testing rules:

- `{{TESTING_RULE}}`

## Git Workflow

Use [branching.md](branching.md) for branch strategy.

Default expectations:

- Keep commits focused and reviewable.
- Write commit messages that describe the reason and outcome.
- Rebase or merge according to the project branch policy.
- Do not mix unrelated refactors with behavior changes.

## Pull Requests

Pull requests should explain what changed, why it changed, and how it was
validated.

Recommended PR sections:

- Summary.
- Scope.
- Validation.
- Risks.
- Screenshots or recordings for UI changes.
- Migration or deployment notes when relevant.

Use [CHECKLISTS.md](CHECKLISTS.md) before requesting review.

## Code Reviews

Reviews should prioritize correctness and maintainability.

Review for:

- Behavior and edge cases.
- Security and authorization.
- Data integrity.
- Architecture boundaries.
- Test quality.
- Operational impact.
- Readability.

Style comments should reference documented conventions or automated tooling
where possible.