SDD Implementation Guidelines

Execute implementation following TDD methodology, SOLID principles, and security best practices.

Prerequisites

Before implementing:

1. Tasks must be approved (use sdd-status to verify)
2. Review tasks in .spec/specs/{feature}/tasks.md
3. Understand the design in .spec/specs/{feature}/design.md

Implementation Workflow

Step 1: Load Context

1. Use sdd-status MCP tool to verify all phases approved
2. Read the tasks document for current implementation
3. Identify the next task to implement

Step 2: Execute TDD Cycle

For each task:

┌─────────────────────────────────────────────────────────────┐
│  1. RED: Write Failing Test                                 │
│     - Define expected behavior                              │
│     - Run test, confirm it FAILS                           │
│                                                             │
│  2. GREEN: Write Minimal Code                               │
│     - Just enough to pass the test                         │
│     - No extra features                                     │
│     - Run test, confirm it PASSES                          │
│                                                             │
│  3. REFACTOR: Improve Code                                  │
│     - Clean up without changing behavior                    │
│     - Run tests, confirm still PASSING                     │
│                                                             │
│  REPEAT for each test case                                  │
└─────────────────────────────────────────────────────────────┘

Step 3: Apply SOLID Principles

S - Single Responsibility Principle

// GOOD: One class, one job
class UserValidator {
  validate(user: User): ValidationResult { ... }
}

class UserRepository {
  save(user: User): Promise<void> { ... }
}

// BAD: Class doing too much
class UserManager {
  validate(user: User) { ... }
  save(user: User) { ... }
  sendEmail(user: User) { ... }
  generateReport() { ... }
}

O - Open/Closed Principle

// GOOD: Open for extension, closed for modification
interface PaymentProcessor {
  process(amount: number): Promise<Result>;
}

class StripeProcessor implements PaymentProcessor { ... }
class PayPalProcessor implements PaymentProcessor { ... }

// BAD: Modifying existing code for new payment types
class PaymentService {
  process(type: string, amount: number) {
    if (type === 'stripe') { ... }
    else if (type === 'paypal') { ... }
    // Adding new type requires modifying this class
  }
}

L - Liskov Substitution Principle

// GOOD: Subtypes are substitutable
class Bird {
  move(): void { /* fly or walk */ }
}

class Sparrow extends Bird {
  move(): void { this.fly(); }
}

class Penguin extends Bird {
  move(): void { this.walk(); }
}

// BAD: Subtype breaks expected behavior
class Bird {
  fly(): void { ... }
}

class Penguin extends Bird {
  fly(): void { throw new Error("Can't fly!"); }
}

I - Interface Segregation Principle

// GOOD: Specific interfaces
interface Readable {
  read(): Data;
}

interface Writable {
  write(data: Data): void;
}

class FileHandler implements Readable, Writable { ... }
class ReadOnlyFile implements Readable { ... }

// BAD: Fat interface forcing unnecessary implementation
interface FileOperations {
  read(): Data;
  write(data: Data): void;
  delete(): void;
  execute(): void;
}

D - Dependency Inversion Principle

// GOOD: Depend on abstractions
interface IUserRepository {
  findById(id: string): Promise<User>;
}

class UserService {
  constructor(private repo: IUserRepository) {}
}

// BAD: Depend on concrete implementations
class UserService {
  private repo = new PostgresUserRepository();
}

Step 4: Security Checklist (OWASP Top 10)

Before marking implementation complete, verify:

1. Broken Access Control

• Enforce access control on every request
• Deny by default
• Validate user owns the resource

2. Cryptographic Failures

• Use strong encryption (AES-256, RSA-2048+)
• Never store passwords in plain text (use bcrypt/argon2)
• Use HTTPS for all communications

3. Injection

• Use parameterized queries for database
• Validate and sanitize all user inputs
• Escape output in templates

4. Insecure Design

• Apply threat modeling
• Implement defense in depth
• Fail securely

5. Security Misconfiguration

• Remove default credentials
• Disable unnecessary features
• Keep dependencies updated

6. Vulnerable Components

• Use dependency audit tools (e.g., npm audit, pip-audit, cargo audit, snyk)
• Update vulnerable packages
• Remove unused dependencies

7. Authentication Failures

• Implement proper session management
• Use MFA where appropriate
• Implement account lockout

8. Software Integrity

• Verify package integrity
• Use lockfiles (e.g., package-lock.json, Cargo.lock, poetry.lock, go.sum)
• Sign commits if required

9. Logging & Monitoring

• Log security events
• Don't log sensitive data
• Implement alerting

10. SSRF (Server-Side Request Forgery)

• Validate and sanitize URLs
• Use allowlists for external calls
• Disable redirects or validate them

Step 5: Code Quality Standards

Naming

// GOOD
const userEmail = user.email;
function calculateTotalPrice(items: Item[]): number { ... }

// BAD
const e = user.email;
function calc(i: any): any { ... }

Comments

// GOOD: Explain WHY, not WHAT
// Use retry because the external API has rate limits
const result = await retryWithBackoff(fetchData);

// BAD: Obvious comments
// Get the user
const user = getUser(id);

Error Handling

// GOOD: Specific, informative errors
class UserNotFoundError extends Error {
  constructor(userId: string) {
    super(`User with ID ${userId} not found`);
    this.name = 'UserNotFoundError';
  }
}

// BAD: Generic errors
throw new Error('Error');

Step 6: Update Task Status

After implementing each task:

1. Mark task as complete in tasks.md
2. Verify test coverage >= 80%
3. Run sdd-quality-check MCP tool on new code

MCP Tool Integration

Tool	When to Use
sdd-status	Check all phases approved before implementing
sdd-spec-impl	Execute specific tasks with TDD
sdd-quality-check	Validate code quality after implementation

Definition of Done

• All acceptance criteria met
• All tests pass
• Code coverage >= 80%
• No lint/type errors
• Security checklist verified
• SOLID principles applied
• Code self-documenting or commented where needed

Steering Document References

Apply these steering documents during implementation:

Document	Purpose	Key Application
.spec/steering/tdd-guideline.md	Test-Driven Development	Follow Red-Green-Refactor cycle for all code
.spec/steering/principles.md	SOLID, DRY, KISS, YAGNI	Apply SOLID principles, keep code simple and focused
.spec/steering/owasp-top10-check.md	Security checklist	Verify all OWASP Top 10 security requirements before completion

Critical Implementation Rules:

1. TDD First: Never write production code without a failing test
2. SOLID Always: Apply all five principles (SRP, OCP, LSP, ISP, DIP)
3. Security Required: Complete OWASP checklist before marking done

Common Anti-Patterns to Avoid

Anti-Pattern	Problem	Solution
God Class	Class does too much	Split by responsibility
Feature Envy	Method uses another class's data extensively	Move method to that class
Primitive Obsession	Using primitives for domain concepts	Create value objects
Magic Numbers	Unexplained numeric literals	Use named constants
Deep Nesting	Multiple levels of if/loops	Extract methods, early returns
Long Methods	Methods doing too much	Split into smaller methods