Michael Chus
0005f3e41a
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>
83 lines
3.1 KiB
Markdown
83 lines
3.1 KiB
Markdown
# 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.
|