Skip to content

AGENTS.md

Latest commit

 

History

History
126 lines (86 loc) · 4.42 KB

AGENTS.md

File metadata and controls

126 lines (86 loc) · 4.42 KB

AGENTS.md

Overview

This project is a tiny Go HTTP server used as a template for building services that connect to a MariaDB database. The Agents (e.g. code‑generation or review bots) rely on this file for

  • build, lint, and test instructions
  • coding‑style rules that all authors must obey
  • any cursor or Copilot configuration that might exist

The file is intentionally ~150 lines to be readable on both terminal and browser views.

1. Build / Lint / Test commands

Action Command Notes
Build go build Builds the binary with default tags. On a CI system this is usually sufficient.
Run unit tests go test ./... Executes all tests in every package.
Run a single test go test -run TestName ./... Replace TestName with the regexp of the test you want. Example: go test -run TestHealth ./...
Lint golangci-lint run Enforces formatting, naming, and most common Go anti‑patterns.
Format go fmt ./... && go vet ./... Checks code formatting and static analysis.
CI friendly go test -v ./... && golangci-lint run Verbose output good for CI logs.

1.1. Dependencies

  • Go >= 1.24.2 (see go.mod)
  • golangci‑lint – install via go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

2. Code‑style guidelines

The goal is to keep the codebase small, readable, and idiomatic. All changes should pass the lint and format checks.

2.1. Imports

  • Imports are grouped in three sections by a blank line: standard library, third‑party packages, then local packages.
  • Within each group the packages are alphabetically sorted.
  • No dot imports – they are disallowed.
  • Wildcard imports (e.g. import "strconv") are prohibited.
import (
    "context"
    "database/sql"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/go-sql-driver/mysql"
    "github.com/gorilla/mux"

    "github.com/mmontes11/opencode-test/db"
    "github.com/mmontes11/opencode-test/handler"
)

2.2. Formatting

  • Use go fmt – it is the de‑facto formatter.
  • Line length should not exceed 100 characters; a warning will be raised by golangci‑lint.
  • Indentation uses tabs, 4 spaces per level.

2.3. Naming conventions

  • Types: PascalCase (HealthCheckResponse).
  • Functions: exportedName or unexportedName – no prefix like new or make unless it conveys intent.
  • Variables/constants: camelCase for locals, UPPER_SNAKE for package‑const.
  • Error return values: always use the idiomatic if err != nil {} pattern.

2.4. Error handling

  • All errors are returned to the caller unless they are truly unrecoverable (e.g. panic).
  • Use fmt.Errorf("context: %w", err) to add context and wrap errors.
  • Log errors with sufficient detail (log.Printf("db init failed: %v", err)).
  • Avoid silent failures – the HTTP health endpoint must return an error status if the DB ping fails.

2.5. Context usage

  • When opening a DB, use context.Background() or the background context from the main function.
  • For long‑running requests (future extension), propagate context to handlers.

2.6. Testing

  • All tests live next to the file they exercise, under the same package.
  • Table‑driven tests for different error scenarios.
  • Use testing.T for assertions, no third‑party testing libs.
  • If a test relies on a database, use a mock or a test container – do not hit a real DB in unit tests.

2.7. Dependencies

  • All external libs are listed in go.mod; the build requires no additional binaries.

3. Cursor / Copilot rules

No Cursor rules are defined in the repository.
No Copilot instructions are present.

If you wish to add rules, create a .cursor/rules/*.json file or .github/copilot-instructions.md. Place the file in the repository root or the suggested location. The rules should be JSON‑formatted and will be parsed by the relevant tooling.

4. Example usage

# Build
$ go build -o bin/server

# Run tests (all packages)
$ go test ./...

# Run only the health test (example)
$ go test -run TestHealth ./...

# Check linting
$ golangci-lint run

Note: All commands above should be run from the repository root (/home/martin/code/opencode-test).

Author: This file was autogenerated by the Project Agent on 2026‑02‑15. Feel free to adjust any guidelines to fit your team's style.