diff options
| author | Paul Buetow <paul@buetow.org> | 2026-02-20 21:36:00 +0200 |
|---|---|---|
| committer | Paul Buetow <paul@buetow.org> | 2026-02-20 21:36:00 +0200 |
| commit | 1900184807155c611b5ccd91fc57a57880d7908f (patch) | |
| tree | 6e9c68ba39944b86b3b13898a356ebc5d177b57b | |
| parent | 4624a5244d019ed9d266351c262531fe1e9ff0a1 (diff) | |
docs: add AGENTS.md and CLAUDE.md for AI agent instructions
| -rw-r--r-- | AGENTS.md | 57 | ||||
| -rw-r--r-- | CLAUDE.md | 1 |
2 files changed, 58 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9fc309d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,57 @@ +# AGENTS.md - AI Agent Instructions + +## Project Overview + +`goprecords` is a Go command-line program that generates uptime reports for hosts based on input record files from `uptimed`. It supports importing records into SQLite and querying for reports, or reporting directly from a stats directory. + +## Build & Test Commands + +```bash +# Build +go build -o goprecords ./cmd/goprecords +# or: mage + +# Run tests +go test ./... +# or: mage test + +# Run integration tests +./goprecords test + +# Install to GOPATH/bin +mage install +``` + +## Project Structure + +``` +goprecords/ +├── cmd/goprecords/main.go # Entry point, CLI handling +├── internal/ +│ ├── goprecords/ # Core logic (db, aggregate, report, parse, order, types) +│ └── version/version.go # Version constant +├── Magefile.go # Build automation +├── fixtures/ # Test fixtures and expected outputs +└── go.mod # Go 1.21, modernc.org/sqlite +``` + +## Code Style + +- Go 1.21 +- No comments in code unless explicitly requested +- Functions should be ~30 lines; refactor when approaching 50 lines +- Move code from main.go to ./internal package when main.go grows too large +- Follow existing patterns in the codebase + +## Categories & Metrics + +- Categories: `Host`, `Kernel`, `KernelMajor`, `KernelName` +- Metrics: `Boots`, `Uptime`, `Score`, `Downtime`, `Lifespan` +- Output formats: `Plaintext`, `Markdown`, `Gemtext` +- `Downtime` and `Lifespan` metrics only apply to `Host` category + +## Key Types + +- `Category`, `Metric`, `OutputFormat` - enums for report configuration +- `Aggregate` - per-entity stats (host, kernel, etc.) +- `HostAggregate` - extends Aggregate with LastKernel, Downtime, Lifespan diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md |