Claude boilerplate (#52)

Author: metachris

.github/workflows/claude.yaml

@@ -0,0 +1,48 @@
+name: Claude Assistant
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  pull_request:
+    types: [opened, synchronize]  # opened = new PR, synchronize = new commits pushed
+  issues:
+    types: [opened, assigned]
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+  id-token: write
+
+jobs:
+  # Interactive mode - responds to @claude mentions
+  claude-response:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_args: |
+            --model opus
+
+  # Automation mode - auto-review new PRs
+  claude-review:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_args: |
+            --model opus
+          prompt: |
+            Review this PR. Focus on:
+            - Correctness and potential bugs
+            - Code clarity and maintainability
+            - Any security concerns
+
+            Be concise. Only comment if you have substantive feedback.

AGENTS.md

@@ -1,40 +1,52 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-- Source layout: `cmd/cli` and `cmd/httpserver` are entrypoints; shared packages live in `common/`, `httpserver/`, `database/`, and `metrics/`.
-- Tests: co-located `*_test.go` files (e.g., `httpserver/handler_test.go`, `database/database_test.go`).
-- Artifacts: binaries output to `build/` via Makefile targets. Dockerfiles: `cli.dockerfile`, `httpserver.dockerfile`.
-- Go version: 1.24 (see `go.mod`). Module path: `github.com/flashbots/go-template`.
-
-## Coding Style & Naming Conventions
-- Use tabs instead of spaces for indentation.
-- Always run `make fmt` and `make lint` (and `make test`) before committing.
-- Formatting: run `make fmt` before committing. Go files must pass `golangci-lint` (config in `.golangci.yaml`).
-- Style: idiomatic Go; exported identifiers use CamelCase; packages lower-case short names; errors returned, not panicked.
-- JSON tags: prefer snake_case (configured via `tagliatelle`).
-- Logging: use `common.SetupLogger` (slog) and structured fields; respect `--log-json` and `--log-debug` flags.
-
-## Build, Test, and Development Commands
-- `make build`: builds CLI and HTTP server into `build/`.
-- `make build-cli` / `make build-httpserver`: build individual binaries.
-- `make lint`: run formatters and linters (`gofmt`, `gofumpt`, `go vet`, `staticcheck`, `golangci-lint`).
-- `make test` / `make test-race`: run tests (optionally with race detector).
-- `make fmt`: apply formatting (`gofmt`, `gci`, `gofumpt`) and `go mod tidy`.
-- `make cover` / `make cover-html`: coverage summary / HTML report.
-- Docker: `make docker-cli`, `make docker-httpserver` build images using the respective Dockerfiles.
-
-## Testing Guidelines
-- Framework: standard `testing` with `testify/require` for assertions.
-- Run: `make test` (or `go test ./...`).
-- Database tests: gated by `RUN_DB_TESTS=1` and a Postgres instance. Example:
-  - `docker run -d --name postgres-test -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres`
-  - `RUN_DB_TESTS=1 make test`
-- Coverage: aim to keep or increase coverage; use `make cover`.
-
-## Commit & Pull Request Guidelines
-- Commits: concise, imperative mood; scope prefixes like `ci:`, `docs:`, `fix:`, `feat:` when helpful. Reference issues/PRs.
-- PRs: include a clear description, linked issues, test plan (commands run), and any config notes. Ensure `make fmt lint test` pass locally.
-
-## Security & Configuration Tips
-- Configuration: prefer flags/env via `common.GetEnv` and CLI options; avoid hardcoding secrets.
-- HTTP server: `/debug` (pprof) is opt-in; do not expose publicly. Metrics on `/metrics` (Prometheus format).
+This file provides guidance to LLMs when working with code in this repository.
+
+## Build Commands
+
+```bash
+make build-cli        # Build CLI binary to ./build/cli
+make build-httpserver # Build HTTP server binary to ./build/httpserver
+make build            # Build all binaries
+```
+
+## Test Commands
+
+```bash
+make test             # Run all tests
+make test-race        # Run tests with race detector
+go test ./... -run TestName  # Run a single test
+
+# Database tests require a running Postgres instance:
+docker run -d --name postgres-test -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres postgres
+RUN_DB_TESTS=1 make test
+```
+
+## Lint and Format
+
+```bash
+make lint   # Run all linters (gofmt, gofumpt, go vet, staticcheck, golangci-lint)
+make fmt    # Format code (gofmt, gci, gofumpt, go mod tidy)
+make lt     # Run both lint and test
+```
+
+## Architecture
+
+This is a Go project template with two entry points:
+
+- **cmd/cli/main.go** - CLI application entry point using urfave/cli
+- **cmd/httpserver/main.go** - HTTP server entry point with graceful shutdown
+
+### Key Packages
+
+- **httpserver/** - HTTP server with chi router, includes `/livez`, `/readyz`, `/drain`, `/undrain` endpoints, metrics middleware, and optional pprof
+- **database/** - Postgres database layer using sqlx with sql-migrate for migrations
+- **database/migrations/** - In-memory migrations registered in `Migrations` variable
+- **metrics/** - VictoriaMetrics-based Prometheus metrics with HTTP middleware
+- **common/** - Shared utilities including structured logging setup (slog-based via httplog)
+
+### HTTP Server Pattern
+
+The server runs two HTTP servers: main API (default :8080) and metrics (default :8090). Supports graceful shutdown with configurable drain duration for load balancer compatibility.
+
+### Database Migrations
+
+Migrations are defined as Go code in `database/migrations/` and registered in `migrations.Migrations`. They run automatically on database connection unless `DB_DONT_APPLY_SCHEMA` env var is set.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md