62 lines
4.2 KiB
Markdown
62 lines
4.2 KiB
Markdown
# Agent Guidelines & Code Standards
|
|
|
|
## Required orientation and documentation maintenance
|
|
|
|
Before changing code, read [`docs/README.md`](docs/README.md) and the documents it routes to for the area you are touching. Treat the source code, tests, generated API reference, and migrations as authoritative when a document disagrees with implementation.
|
|
|
|
Documentation is part of the change, not a follow-up task:
|
|
|
|
- Update the relevant file in `docs/` whenever behavior, architecture, configuration, data ownership, API contracts, operations, safety boundaries, or development workflow changes.
|
|
- Update `docs/README.md` when adding, renaming, or removing a document.
|
|
- Run `npm run docs:api` after changing `src/web/api-catalog.ts`; verify with `npm run docs:api:check`.
|
|
- Prefer durable explanations and links to owning source files over copied implementation details, line counts, credentials, production IDs, or other facts likely to drift.
|
|
- During final review, explicitly check whether the documentation still describes the code that will be committed.
|
|
|
|
Do not start, restart, deploy, or otherwise enable live outreach unless the user explicitly authorizes that operational action. A code or documentation request does not imply permission to run the bot. Never expose `.env`, imported account dumps, cookies, Matrix tokens, dashboard tokens, private media, or database contents.
|
|
|
|
## 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. Testing
|
|
- TDD is not required. Agents may implement changes before writing or updating tests.
|
|
- Add or update tests when they provide useful coverage for new functionality or bug fixes.
|
|
- Tests live in `tests/` (mirroring `src/` structure) and run via `vitest` (`npm test`).
|
|
- Prefer behavior-focused tests (inputs → outputs / observable side effects) over tests that pin internal structure.
|
|
|
|
### 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. **Orient**: Read `docs/README.md`, the relevant topic documents, and the owning code/tests.
|
|
2. **Analyze**: Before writing code, read the file and understand the context.
|
|
3. **Plan**: Identify what needs to change and check if the change violates SRP.
|
|
4. **Implement**: Make the scoped change. Create new small files when SRP calls for it.
|
|
5. **Test**: Add or update useful tests as appropriate for the change.
|
|
6. **Document**: Update the routed documentation for any changed contract or workflow.
|
|
7. **Refactor**: Tidy the implementation and tests while preserving behavior.
|
|
8. **Verify**: Run the relevant tests, documentation checks, and type checks (`npm run build` or `tsc --noEmit`) in proportion to the change.
|
|
|
|
When Dokploy access is explicitly requested, use the credentials in the ignored `.env` file. Do not print, copy, commit, or blindly source that file.
|