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

sdd-status

sdd-spec-impl

sdd-quality-check

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:

.spec/steering/tdd-guideline.md

.spec/steering/principles.md

.spec/steering/owasp-top10-check.md

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