Files

Michael Chus 0005f3e41a Compress always-on contracts and restore pagination fields

The always-on set is paid by every session, so it gets the tightest
form: git-sync-check shrinks to its procedural core, testing-policy
moves the table-test example to README.md and folds the agent
instructions into the rules, go-code-style inlines the error-wrapping
example. Per-session read cost drops from 403 to 336 lines.

Also restore the pagination response fields in table-management: the
previous dedup replaced them with a reference to go-api, which the
table router line does not load.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-06-12 10:05:00 +03:00

3.1 KiB

Raw Blame History

Contract: Go Code Style and Project Conventions

Version: 1.3

Source Text and Comments

Use plain ASCII in source code and comments by default.
Do not use em dash, emoji, or other decorative Unicode markers in code, comments, log messages, or user-facing fallback strings unless a feature explicitly requires non-ASCII text.
Do not leave AI-style markers in the codebase: ornamental phrasing, assistant-like filler, synthetic enthusiasm, or comments that read like generated prose instead of technical documentation.
Comments must be short, concrete, and technical. Explain intent, invariants, or non-obvious constraints; do not write marketing-style or conversational commentary.

Logging

See the go-logging contract for full rules.

Summary: use slog, log to stdout/stderr (binary console), never to browser console.

Error Handling

Always wrap errors with context: fmt.Errorf("save component %s: %w", record.ID, err). A bare return err loses context.
Never silently discard errors with _ in production paths.
Return errors up the call stack; log at the handler/task boundary, not deep in service code.

Code Formatting

Always run gofmt before committing. No exceptions.
No manual alignment of struct fields or variable assignments.

HTTP Handler Structure

Handlers are thin. Business logic belongs in a service layer.

Handler -> validates input, calls service, writes response
Service -> business logic, calls repository
Repository -> SQL queries only, returns domain types

Handlers must not contain SQL queries.
Services must not write HTTP responses.
Repositories must not contain business rules.

Startup Sequence (Go web app)

1. Parse flags / load config
2. Connect to DB; fail fast if unavailable (see go-database contract)
3. Run migrations
4. Initialize services and background workers
5. Register routes
6. Start HTTP server

Never reverse steps 2 and 5. Never start serving before migrations complete.

Configuration

Config lives in a single config.yaml file, not scattered env vars.
Env vars may override config values but must be documented.
Never hardcode ports, DSNs, or file paths in application code.
Provide a config.example.yaml committed to the repo.
The actual config.yaml is gitignored.
Secret handling and pre-commit/pre-push leak checks must follow the secret-management contract.

Template / UI Rendering

Server-rendered HTML via Go templates is the default.
htmx for partial updates; no full SPA framework unless explicitly decided.
Template errors must return 500 and log the error server-side.
Never expose raw Go error messages to the end user in rendered HTML.

Business Logic Placement

Threshold computation, status derivation, and scoring live on the server.
The UI only reflects what the server returns; it does not recompute status client-side.
Example: "critical / warning / ok" badge color is determined by the handler, not by JS.

Dependency Rules

Prefer standard library. Add a dependency only when the stdlib alternative is significantly worse.
Document the reason for each non-stdlib dependency in a comment or ADL entry.

3.1 KiB Raw Blame History