implementation-standards ยท diff
git:20260304.18c8de5 to git:20260305.899a6f4
1 added, 1 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).
- **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.
### 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. Load `quickstart.md` only during the Polish phase.
+ - **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.
## 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")