chat/AGENTS.md

AGENTS.md — Rules for AI Agents

Before Every Commit

1. Format: gofmt -s -w . and goimports -w .
2. Lint: golangci-lint run --config .golangci.yml ./... — zero issues
3. Test: go test -race ./... — all passing
4. Build: go build ./cmd/chatd — compiles clean

No commit lands on main with lint errors, test failures, or formatting issues.

Code Style

• Follow CONVENTIONS.md exactly — it defines the architecture
• All exported types, functions, methods, and vars must have doc comments
• All packages must have a package doc comment
• JSON tags use camelCase (not snake_case)
• No magic numbers — use named constants
• No inline error handling (if err := ...; err != nil) — use plain assignment
• Blank line before every return statement
• Blank line separating embedded fields from regular fields in structs
• Blank imports must have a justification comment

Git Workflow

• Never commit directly to main — always feature branches + PRs
  • Exception: initial scaffolding and AGENTS.md/CONVENTIONS.md updates
• PR titles: Description (closes #N) when closing an issue
• One logical change per commit
• Commit messages: imperative mood, concise

Architecture

• Dependency injection via Uber fx — all components are fx providers
• internal/ for all application packages — one package per concern
• Handlers return http.HandlerFunc using the closure pattern
• Request/response structs defined inside handler closures
• Models embed models.Base for database access to relation methods
• Database migrations in internal/db/schema/ — embedded via go:embed
• SQLite by default (pure Go driver: modernc.org/sqlite)

Testing

• Table-driven tests preferred
• Use testing.T helpers, not assertion libraries
• Test files live next to the code they test
• _test.go suffix, same package for white-box testing

Dependencies

• Required libraries are listed in CONVENTIONS.md §1
• No new dependencies without justification
• Pure Go preferred (no CGO)