template/docs/CONVENTIONS.md

Conventions

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

For project facts, see PROJECT.md. For architecture boundaries, see ARCHITECTURE.md. For task quality gates, see 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 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 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.