RedditBot/agents.md

Agent Guidelines & Code Standards

Refactoring Goal

Refactor code to improve maintainability, testability, and clarity. Break down large components into smaller, single-purpose classes/modules.

Engineering Standards

1. Single Responsibility Principle (SRP)

• Avoid "God Classes" (e.g., massive Service classes that do everything).
• Extract logic into dedicated handlers, managers, or utilities.
• Example: Instead of one BotService handling login, monitoring, and messaging, split into AuthService, MonitorService, and MessagingService.

2. Design Patterns

• Dependency Injection: Pass dependencies via constructors. This makes swapping implementations (e.g., for testing) easier.
• Factory Pattern: Use factories for creating complex objects (e.g., configuring different AI models).
• Strategy Pattern: Good for interchangeable algorithms (e.g., differentsubreddit selection strategies).

3. TypeScript Best Practices

• Strict Typing: No any. Define interfaces/types for all data structures (especially API/Reddit responses).
• Zod Validation: Use zod (already in deps) to validate external data (config files, API responses).
• Async/Await: properly handle promises. Use p-queue or p-retry for rate-limited operations.

4. Test-Driven Development (TDD) — REQUIRED

All new functionality and bug fixes MUST follow the red-green-refactor cycle. This is non-negotiable.

• Red: Write a failing test FIRST that describes the desired behavior. Run it and confirm it fails for the expected reason.
• Green: Write the minimum production code needed to make the test pass. No extra features, no speculative abstractions.
• Refactor: With tests green, clean up implementation and tests. Re-run the suite after each change.

Rules:

• Never commit production code without an accompanying test that fails without it.
• Tests live in tests/ (mirroring src/ structure) and run via vitest (npm test).
• Use dependency injection so collaborators (DB, HTTP, browser, clock) can be faked — do not mock what you don't own; wrap third-party APIs in a thin interface and fake the interface.
• Prefer behavior-focused tests (inputs → outputs / observable side effects) over tests that pin internal structure.
• Bug fixes start with a regression test that reproduces the bug.
• If a change is genuinely untestable (e.g. a one-line config tweak), state that explicitly in the PR/commit rather than skipping silently.

5. Project Specifics

• Tech Stack: Node.js, TypeScript, Playwright, Express, SQLite, Vitest.
• Directories:
  • src/services/ for business logic.
  • src/web/ for Express server and UI.
  • src/browser/ for Playwright interactions.
  • tests/ for vitest specs, mirroring src/ layout.
• Logging: Use winston for structured logging. Do not use console.log in production code.

Workflow for Agents

1. Analyze: Before writing code, read the file and understand the context.
2. Plan: Identify what needs to change. Check if the change violates SRP. Identify the test(s) that will drive the change.
3. Write failing test (Red): Add a vitest spec that captures the new behavior or reproduces the bug. Run npm test and confirm it fails for the right reason.
4. Implement (Green): Write the smallest change that makes the test pass. Create new small files when SRP calls for it.
5. Refactor: Tidy the implementation and the test with the suite green. Re-run tests after each refactor step.
6. Verify: Ensure the full suite passes (npm test) and types check (npm run build or tsc --noEmit).