bible/rules/ai/claude/CLAUDE.template.md

{{ .project_name }} — Instructions for Claude

Shared Engineering Rules

Read bible/ — shared rules for all projects (CSV, logging, DB, tables, background tasks, code style). Start with bible/rules/patterns/ for specific contracts.

Project Architecture

Read bible-local/ — project-specific architecture. Every architectural decision specific to this project must be recorded in bible-local/.

---

Quick Reference (full contracts in bible/rules/patterns/)

Go Code Style (go-code-style/contract.md)

• Handler → Service → Repository. No SQL in handlers, no HTTP writes in services.
• Errors: fmt.Errorf("context: %w", err). Never discard with _.
• gofmt before every commit.
• Thresholds and status logic on the server — UI only reflects what server returns.

Logging (go-logging/contract.md)

• slog, stdout/stderr only. Never console.log as substitute for server logging.
• Always log: startup, task start/finish/error, export row counts, ingest results, any 500.

Database (go-database/contract.md)

• CRITICAL: never run SQL on the same tx while iterating a cursor. Two-phase: read all → close → write.
• Soft delete via is_active = false.
• Fail-fast DB ping before starting HTTP server.
• No N+1: use JOINs or batch WHERE id IN (...).
• GORM: gorm:"-" = fully ignored; gorm:"-:migration" = skip migration only.

REST API (go-api/contract.md)

• Plural nouns: /api/assets, /api/components.
• Never 200 OK for errors — use 422 for validation, 404, 500.
• Error body: {"error": "message", "fields": {"field": "reason"}}.
• List response always includes total_count, page, per_page, total_pages.
• /health and /api/db-status required in every app.

Background Tasks (go-background-tasks/contract.md)

• Slow ops (>300ms): POST → {task_id} → client polls /api/tasks/:id.
• No SSE. Polling only. Return 202 Accepted.

Tables, Filtering, Pagination (table-management/contract.md)

• Server-side only. Filter state in URL params. Filter resets to page 1.
• Display: "51–100 из 342".

Modals (modal-workflows/contract.md)

• States: open → submitting → success | error.
• Destructive actions require confirmation modal naming the target.
• Never close on error. Use 422 for validation errors in htmx flows.

CSV Export (import-export/contract.md)

• BOM: \xEF\xBB\xBF. Delimiter: ;. Decimal: , (1 234,56). Dates: DD.MM.YYYY.
• Stream via callback — never load all rows into memory.
• Always call w.Flush() after the loop.