docs: add agent bootstrap and contract read router

This commit is contained in:
Mikhail Chusavitin
2026-04-02 13:48:36 +03:00
parent 688b87e98d
commit 1d89a4918e
22 changed files with 883 additions and 1284 deletions

View File

@@ -1,55 +1,24 @@
# {{ .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.
Read `bible/AGENT-BOOTSTRAP.md` first.
Do not read the whole `bible/` submodule by default.
Read only the contracts that `AGENT-BOOTSTRAP.md` routes you to for the current task.
## Project Architecture
Read `bible-local/` project-specific architecture.
Read `bible-local/README.md` first, then only the relevant project-specific architecture files.
Every architectural decision specific to this project must be recorded in `bible-local/`.
---
## Quick Reference (full contracts in `bible/rules/patterns/`)
## Minimum Read Path
### 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.
1. `bible/AGENT-BOOTSTRAP.md`
2. `bible-local/README.md`
3. Relevant files in `bible-local/architecture/` and `bible-local/decisions/`
4. Relevant `bible/rules/patterns/*/contract.md`
### 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.
## Default Rule
### 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: "51100 из 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.
Do not claim you "read bible" unless you actually read the relevant files.
Do not walk all shared contracts unless the task is explicitly about changing the rules library itself.

View File

@@ -0,0 +1,24 @@
# {{ .project_name }} — Instructions for Codex
## Shared Engineering Rules
Read `bible/AGENT-BOOTSTRAP.md` first.
Do not read the whole `bible/` submodule by default.
Read only the contracts that `AGENT-BOOTSTRAP.md` routes you to for the current task.
## Project Architecture
Read `bible-local/README.md` first, then only the relevant project-specific architecture files.
Every architectural decision specific to this project must be recorded in `bible-local/`.
---
## Minimum Read Path
1. `bible/AGENT-BOOTSTRAP.md`
2. `bible-local/README.md`
3. Relevant files in `bible-local/architecture/` and `bible-local/decisions/`
4. Relevant `bible/rules/patterns/*/contract.md`
## Default Rule
Do not claim you "read bible" unless you actually read the relevant files.
Do not walk all shared contracts unless the task is explicitly about changing the rules library itself.