56 lines
2.5 KiB
Markdown
56 lines
2.5 KiB
Markdown
# {{ .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.
|