hireme/.vibe/ai-guideline.md

AI Development Guidelines for Hireme

These guidelines provide context to AI assistants working on the hireme repository. Adhere to these principles to maintain the project's architecture and design philosophy.

1. Single Binary & Zero Dependencies

• Goal: The application must compile into a single Go binary.
• Rule: Do NOT introduce external dependencies that require separate build steps, node_modules, or static asset folders unless explicitly authorized.
• Rule: Use Go 1.22+ standard library features wherever possible (e.g., net/http ServeMux).

2. UI Philosophy (HTMX + Tailwind)

• Rule: Do NOT introduce React, Vue, or any heavy JS frameworks.
• Rule: All dynamic interactions must be handled via HTMX (hx-get, hx-post, hx-target). Endpoints should return HTML fragments, not JSON, for UI updates.
• Rule: CSS is handled via Tailwind CSS utility classes. Maintain the dark mode aesthetic using bg-slate-*, text-slate-*, and vibrant accents (indigo, emerald, rose).
• Rule: UI templates are stored as constant strings in Go files (internal/ui/template_*.go) and registered in templates.go. Do not create external .html files.

3. Database Integrity

• Rule: Use go-sqlite3 and ensure PRAGMA journal_mode=WAL; is maintained. The application heavily relies on WAL mode to allow concurrent reads (from the UI) and writes (from background workers).
• Rule: Avoid long-running transactions that could lock the database.

4. Structured Logging

• Rule: Use zap structured logging exclusively. Do NOT use the standard library log.Printf.
• Rule: Use the w methods (Infow, Debugw, Errorw) to pass key-value pairs.
  • Correct: logger.Log.Infow("User created", "component", "API", "user_id", id)
  • Incorrect: logger.Log.Infof("[API] User created: %d", id)

5. Background Workers

• Rule: Long-running tasks (Crawling, LLM Analysis) must be executed asynchronously via the internal/worker pool. Do not block HTTP request handlers. Enqueue tasks in the SQLite tasks table instead.