implementation-standards ยท diff
git:20260305.899a6f4 to git:20260327.17e6b46
13 added, 14 removed. Audit A to A.
---
name: implementation-standards
description: "Standard patterns and practices for code implementation. Use when writing code in the `/sddp-implement` phase to ensure consistency, safety, and maintainability."
---
# Implementation Standards
## Core Coding Principles
### 1. Defensive Coding
- - **Input Validation**: Never trust user input. Validate at the entry point (Controller/API).
+ - **Input Validation**: Validate at entry point (Controller/API). Never trust user input.
- **Fail Fast**: Check preconditions immediately. Throw specific errors, not generic 500s.
- **Null Safety**: Avoid returning `null`. Use `Option` types or explicit "Not Found" errors.
### 2. Error Handling
- - **Structured Errors**: Use a standard error response format (Code, Message, Details).
- - **Log Context**: When catching an exception, log the stack trace AND the input parameters that caused it.
- - **No Silent Failures**: Never empty `catch` blocks.
+ - **Structured Errors**: Standard format (Code, Message, Details).
+ - **Log Context**: Log stack trace AND input parameters on catch.
+ - **No Silent Failures**: No empty `catch` blocks.
### 3. Testing Mocks
- **External Dependencies**: Always mock 3rd party APIs in unit tests.
- **Determinism**: Tests must run without network access.
## Common Patterns
### Repository Pattern (Data Access)
- *Use strictly for database interactions.*
```pseudo
interface UserRepository {
findById(id: string): Promise<User | null>
save(user: User): Promise<User>
}
```
### Service Layer (Business Logic)
*Contains all domain rules. Never access DB directly from Controller.*
```pseudo
class UserService {
constructor(repo: UserRepository)
async register(email: string) {
if (await this.repo.findByEmail(email)) {
throw new DuplicateEmailError()
}
// ... logic
}
}
```
## Context-Window Efficiency
- When context window budget is tight (e.g., late in a long implementation run with many files already processed):
- - **Prefer targeted reads**: Re-read specific sections of a file rather than loading entire files when only a portion is needed.
- - **Defer optional docs**: Only load `data-model.md` and `contracts/` when the current task references them directly.
- - **Summarize, don't repeat**: When referencing earlier findings or review results, summarize the key point rather than re-including full content.
+ When context budget is tight (late in long implementation runs):
+ - **Targeted reads**: re-read specific sections, not entire files.
+ - **Defer optional docs**: load `data-model.md` and `contracts/` only when current task references them.
+ - **Summarize**: reference earlier findings by key point, don't re-include full content.
## Review Checklist for Agents
- Before confirming a task as "Complete":
- 1. **Does it compile/run?** (No syntax errors)
- 2. **Are imports clean?** (No unused imports)
- 3. **Are types explicit?** (No `any` or `var` if avoidable)
- 4. **Are comments helpful?** (Explain "Why", not "What")
+ Before confirming task "Complete":
+ 1. Compiles/runs? (No syntax errors)
+ 2. Imports clean? (No unused imports)
+ 3. Types explicit? (No `any` or `var` if avoidable)
+ 4. Comments helpful? (Explain "Why", not "What")