# CRITICAL: Load ONLY the context specified in the current task

Example for TASK-003:
**Context to Load** (~500 lines):
- specs/ (quality rules, architectural principles) (DDD section) - ~200 lines
- proposal.md - ~100 lines
- design.md (if exists) - ~150 lines
- spec.md (APENAS the Requirement for this scenario) - ~100 lines
- tasks.md (APENAS TASK-003) - ~50 lines

**Do NOT Load**:
- Full spec.md (5000+ lines)
- Other tasks from tasks.md
- Full codebase
- Other implementations

# Why this matters:
Large context = AI loses focus = hallucinations = wrong code
Small context = AI stays focused = correct code

# Read current task completely:

Task ID: TASK-003
Title: Implementar factory criar-usuario.ts
Description: Criar factory que constrói entidade Usuario
Estimated LOC: ~60 lines
Estimated Time: 1.5 hours
Dependencies: TASK-001, TASK-002 (both must be completed)
BDD Scenario: "Register new user with valid data"
DDD Components: Factory (criar-usuario)

Acceptance Criteria:
- [ ] Função criar-usuario implementada
- [ ] Inputs validados (email, senha, nome)
- [ ] Value objects criados (Email, Senha, Nome)
- [ ] Entity Usuario criada com ID (UUID)
- [ ] Domain events gerados (UsuarioCriado)
- [ ] BDD Partial: GIVEN valid data → Usuario created
- [ ] Unit test: describe('criar-usuario') passando

# Questions to answer:
1. What does this task do? (Factory that creates Usuario entity)
2. What are the inputs? (email, senha, nome)
3. What are the outputs? (Usuario entity + UsuarioCriado event)
4. What validations needed? (email format, senha strength, nome length)
5. What value objects? (Email, Senha, Nome)
6. What dependencies? (TASK-001, TASK-002 must be done)

# Before starting, verify dependencies are completed:

For TASK-003:
Dependencies: TASK-001, TASK-002

Check:
- [ ] TASK-001 (Setup DDD structure) completed?
- [ ] TASK-002 (Test setup) completed?

If dependencies NOT completed:
- STOP immediately
- Do NOT proceed with this task
- Complete dependencies first
- Return to Step 1 with dependency task

If dependencies completed:
- Proceed to Step 4

# NON-NEGOTIABLE: Test-First Development

Write test BEFORE implementation.

Example for TASK-003 (criar-usuario):

File: src/user-management/api/usuario/usuario.spec.ts

describe('criar-usuario', () => {
  it('should create user with valid data', () => {
    // GIVEN: valid inputs
    const input = {
      email: 'user@example.com',
      senha: 'SecurePass123!',
      nome: 'João Silva'
    };

    // WHEN: criar-usuario is called
    const result = criarUsuario(input);

    // THEN: user is created
    expect(result.usuario).toBeDefined();
    expect(result.usuario.id).toMatch(/^[0-9a-f-]{36}$/); // UUID
    expect(result.usuario.email.valor).toBe('user@example.com');
    expect(result.usuario.nome.valor).toBe('João Silva');

    // AND: domain event is generated
    expect(result.eventos).toHaveLength(1);
    expect(result.eventos[0].tipo).toBe('UsuarioCriado');
  });

  it('should throw error for invalid email', () => {
    const input = {
      email: 'invalid-email',
      senha: 'SecurePass123!',
      nome: 'João Silva'
    };

    expect(() => criarUsuario(input)).toThrow('Email inválido');
  });

  // Add more test cases for senha validation, nome validation, etc.
});

# Run test (should FAIL - RED):
npm test usuario.spec.ts

# Expected: Test fails because criar-usuario doesn't exist yet

# Implement the MINIMUM code to make tests pass

File: src/user-management/api/usuario/criar-usuario.ts

import { v4 as uuidv4 } from 'uuid';
import { Usuario } from './Usuario';
import { Email } from './Email';
import { Senha } from './Senha';
import { Nome } from './Nome';
import { UsuarioCriado } from './UsuarioCriado';

interface CriarUsuarioInput {
  email: string;
  senha: string;
  nome: string;
}

interface CriarUsuarioOutput {
  usuario: Usuario;
  eventos: DomainEvent[];
}

export function criarUsuario(input: CriarUsuarioInput): CriarUsuarioOutput {
  // 1. Validate inputs by creating value objects
  const email = new Email(input.email); // Will throw if invalid
  const senha = new Senha(input.senha); // Will throw if invalid
  const nome = new Nome(input.nome);   // Will throw if invalid

  // 2. Generate UUID for entity
  const id = uuidv4();

  // 3. Create Usuario entity
  const usuario = new Usuario({
    id,
    email,
    senha,
    nome,
    criadoEm: new Date()
  });

  // 4. Generate domain event
  const evento = new UsuarioCriado({
    usuarioId: id,
    email: email.valor,
    nome: nome.valor,
    ocorridoEm: new Date()
  });

  // 5. Return usuario + eventos
  return {
    usuario,
    eventos: [evento]
  };
}

# Run test again (should PASS - GREEN):
npm test usuario.spec.ts

# Expected: All tests pass

# Refactor code to improve quality while keeping tests GREEN

Refactoring checklist:
- [ ] Remove duplication
- [ ] Improve naming
- [ ] Extract complex logic into functions
- [ ] Add comments where needed
- [ ] Ensure code follows specs/ (quality rules, architectural principles) principles

# After each refactor, run tests:
npm test usuario.spec.ts

# Tests must STAY green after refactoring

# Check ALL acceptance criteria for current task:

For TASK-003:
- [x] Função criar-usuario implementada ✅
- [x] Inputs validados (email, senha, nome) ✅
- [x] Value objects criados (Email, Senha, Nome) ✅
- [x] Entity Usuario criada com ID (UUID) ✅
- [x] Domain events gerados (UsuarioCriado) ✅
- [x] BDD Partial: GIVEN valid data → Usuario created ✅
- [x] Unit test: describe('criar-usuario') passando ✅

# If ANY criterion is NOT met:
- Task is NOT complete
- Continue implementation
- Return to Step 5

# If ALL criteria are met:
- Task is complete
- Proceed to Step 8

# Update tasks.md progress tracker:

## 📊 Progress Tracker

- **Total**: [x] 1/12 tasks completed (8%)
- **Phase 0**: [x] 2/2 (Setup) ← TASK-001, TASK-002 done
- **Phase 1**: [x] 1/6 (Core Requirements) ← TASK-003 done
- **Phase 2**: [ ] 0/2 (Error Handling)
- **Phase 3**: [ ] 0/3 (Tests)
- **Phase 4**: [ ] 0/2 (Quality)

**Status**: 🟡 In Progress

# Mark current task as completed in task list:

### TASK-003: Implementar factory criar-usuario.ts ✅ COMPLETED
**Priority**: P1
**Estimated LOC**: ~60 lines
**Actual LOC**: 58 lines
**Estimated Time**: 1.5 hours
**Actual Time**: 1.3 hours
...

# Identify next task from tasks.md:

Next task: TASK-004 (Implementar repository persistir-usuario.ts)
Dependencies: TASK-003 (just completed ✅)

# Return to Step 1 with TASK-004
# Load ONLY the context for TASK-004
# DO NOT load context from TASK-003 or other tasks

# Continue task-by-task until:
- [ ] All Phase 0 tasks complete (Setup)
- [ ] All Phase 1 tasks complete (Core Requirements)
- [ ] All Phase 2 tasks complete (Error Handling)
- [ ] All Phase 3 tasks complete (Tests)
- [ ] All Phase 4 tasks complete (Quality & Compliance)

# Total progress: 12/12 tasks completed (100%)
# Status: 🟢 Complete

# Then proceed to Phase 5 (Review)

src/[bounded-context]/[container]/[component]/
  ├── index.ts                 # Aggregate root (public exports)
  ├── criar-[entity].ts        # Factory
  ├── persistir-[entity].ts    # Repository
  ├── [action]-[entity].ts     # Use case (e.g., registrar-usuario)
  ├── [Entity].ts              # Entity (aggregate root)
  ├── [ValueObject].ts         # Value objects (Email, CPF, Nome)
  ├── [Event].ts               # Domain events (UsuarioCriado - past tense)
  └── [component].spec.ts      # Tests

Example:
src/user-management/api/usuario/
  ├── index.ts                 # Export public API
  ├── criar-usuario.ts         # Factory
  ├── persistir-usuario.ts     # Repository
  ├── registrar-usuario.ts     # Use case
  ├── Usuario.ts               # Entity
  ├── Email.ts                 # Value object
  ├── Senha.ts                 # Value object
  ├── Nome.ts                  # Value object
  ├── UsuarioCriado.ts         # Domain event
  └── usuario.spec.ts          # Tests

// Email.ts - Value Object
export class Email {
  private readonly _valor: string;

  constructor(valor: string) {
    // Validation in constructor
    if (!this.isValid(valor)) {
      throw new Error('Email inválido');
    }
    this._valor = valor.toLowerCase();
  }

  get valor(): string {
    return this._valor;
  }

  private isValid(email: string): boolean {
    const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return regex.test(email);
  }

  // Value objects are compared by value
  equals(other: Email): boolean {
    return this._valor === other._valor;
  }
}

// Value Objects are:
// - Immutable (no setters)
// - Self-validating (validation in constructor)
// - Compared by value (not by ID)

// Usuario.ts - Entity (Aggregate Root)
export class Usuario {
  private readonly _id: string;
  private _email: Email;
  private _senha: Senha;
  private _nome: Nome;
  private readonly _criadoEm: Date;

  constructor(props: {
    id: string;
    email: Email;
    senha: Senha;
    nome: Nome;
    criadoEm: Date;
  }) {
    this._id = props.id;
    this._email = props.email;
    this._senha = props.senha;
    this._nome = props.nome;
    this._criadoEm = props.criadoEm;

    // Validate invariants
    this.validate();
  }

  // Getters (expose state)
  get id(): string { return this._id; }
  get email(): Email { return this._email; }
  get nome(): Nome { return this._nome; }

  // Business methods (encapsulate behavior)
  alterarEmail(novoEmail: Email): UsuarioAlterado {
    this._email = novoEmail;
    return new UsuarioAlterado({ usuarioId: this._id, novoEmail });
  }

  // Protect invariants
  private validate(): void {
    if (!this._id) throw new Error('ID é obrigatório');
    if (!this._email) throw new Error('Email é obrigatório');
    if (!this._senha) throw new Error('Senha é obrigatória');
    if (!this._nome) throw new Error('Nome é obrigatório');
  }
}

// Entities:
// - Have identity (ID)
// - Can change state (mutable attributes)
// - Protect invariants
// - Encapsulate business logic

// UsuarioCriado.ts - Domain Event
export class UsuarioCriado {
  readonly tipo: string = 'UsuarioCriado';  // Event type
  readonly usuarioId: string;
  readonly email: string;
  readonly nome: string;
  readonly ocorridoEm: Date;

  constructor(props: {
    usuarioId: string;
    email: string;
    nome: string;
    ocorridoEm: Date;
  }) {
    this.usuarioId = props.usuarioId;
    this.email = props.email;
    this.nome = props.nome;
    this.ocorridoEm = props.ocorridoEm;
  }
}

// Domain Events:
// - Named in past tense (UsuarioCriado, PedidoConfirmado)
// - Immutable (readonly fields)
// - Contain minimal data needed by subscribers
// - Timestamp when event occurred

# Load ONLY what current task specifies
TASK-003 Context:
- specs/ (quality rules, architectural principles) (DDD section) - ~200 lines
- proposal.md - ~100 lines
- spec.md (APENAS requirement) - ~100 lines
- tasks.md (APENAS TASK-003) - ~50 lines
Total: ~450 lines

# This keeps AI focused and deterministic

# Load everything (causes hallucinations)
- Full spec.md (5000+ lines)
- All tasks.md (1000+ lines)
- Entire codebase (10000+ lines)
Total: 16000+ lines

# This causes AI to lose focus and hallucinate

// Integration test with real database
describe('persistir-usuario (integration)', () => {
  let db: Database;

  beforeEach(async () => {
    db = await createTestDatabase(); // Real DB
  });

  afterEach(async () => {
    await db.close();
  });

  it('should persist user to database', async () => {
    const usuario = criarUsuario({ ... });

    await persistirUsuario({ usuario });

    // Verify in actual database
    const saved = await db.query('SELECT * FROM users WHERE id = ?', [usuario.id]);
    expect(saved).toBeDefined();
  });
});

// Unit test with mocks (less valuable)
describe('persistir-usuario (mocked)', () => {
  it('should call database.insert', () => {
    const mockDb = { insert: jest.fn() };
    const usuario = criarUsuario({ ... });

    persistirUsuario({ usuario, db: mockDb });

    expect(mockDb.insert).toHaveBeenCalled(); // Only tests mock, not real behavior
  });
});

BAD:
"Let me implement the entire user registration system"
- Loads full spec.md (5000 lines)
- Tries to implement all features at once
- No clear acceptance criteria
- High chance of hallucinations

PROBLEM: Too much context = AI loses focus = incorrect code

BAD:
1. Write all implementation code
2. Skip writing tests
3. "Tests can be added later"

PROBLEM: No way to verify correctness, high chance of bugs

BAD:
TASK-004 depends on TASK-003
But Developer starts TASK-004 before TASK-003 is complete

PROBLEM: TASK-004 will fail or be incorrect because it depends on TASK-003 output

BAD:
"Let me load the entire codebase to understand everything"
- Loads 50+ files
- 10000+ lines of context
- Multiple unrelated modules

PROBLEM: AI gets confused, hallucinates, produces incorrect code

// usuario.spec.ts
describe('criar-usuario', () => {
  it('should create user with valid data', () => {
    const result = criarUsuario({
      email: 'user@example.com',
      senha: 'SecurePass123!',
      nome: 'João Silva'
    });

    expect(result.usuario.id).toBeDefined();
    expect(result.eventos).toHaveLength(1);
  });
});

// Run: npm test → FAILS (criar-usuario doesn't exist)

// criar-usuario.ts
export function criarUsuario(input: CriarUsuarioInput): CriarUsuarioOutput {
  const email = new Email(input.email);
  const senha = new Senha(input.senha);
  const nome = new Nome(input.nome);
  const id = uuidv4();

  const usuario = new Usuario({ id, email, senha, nome, criadoEm: new Date() });
  const evento = new UsuarioCriado({ usuarioId: id, email: email.valor, nome: nome.valor, ocorridoEm: new Date() });

  return { usuario, eventos: [evento] };
}

// Run: npm test → PASSES

Progress: 3/12 tasks (25%)
TASK-003: ✅ COMPLETED
Next: TASK-004