---
layout: default
---

# AGENTS.md – Repository Guidelines for Pierre Bot

> This document is consulted by autonomous coding agents (including the
> Open‑Source `opencode` agent) when they read, modify, test, or lint the
> code‑base.  It contains the canonical commands for building, testing, and
> lint‑ing the project as well as a concise style guide that all Go code must
> follow.  The file is deliberately kept around **150 lines** to be readable for
> both humans and LLMs.

---

## 1️⃣ Build / Run Commands

| Command | Description |
|--------|-------------|
| `go build -o bin/pierre ./cmd/pierre/main.go` | Build the binary into `./bin/pierre`. |
| `go run ./cmd/pierre/main.go --help` | Run the CLI with the help flag (fast sanity check). |
| `./bin/pierre --version` | Verify the built binary reports its version. |

> **Tip for agents** – always prefer the `./bin/pierre` binary over invoking `go run` in CI or tests; it guarantees the same compilation flags.

---

## 2️⃣ Test Commands

The project uses the standard Go testing framework.

| Command | Use case |
|---------|----------|
| `go test ./...` | Run **all** unit and integration tests. |
| `go test ./... -run ^TestJudgePR$` | Run a **single** test (replace `TestJudgePR` with the desired name). |
| `go test -cover ./...` | Run tests and emit a coverage report. |
| `go test -run ^TestName$ -count=1 -v` | Verbose, non‑cached run for debugging a single test. |
| `go test ./... -bench .` | Execute benchmarks (if any). |

> **Agents should never** invoke `go test` with `-parallel` flags; the default parallelism is sufficient and ensures deterministic ordering for our table‑driven tests.

---

## 3️⃣ Lint / Static Analysis

We rely on two lightweight built‑in tools plus optional `golangci-lint` when
available.

| Tool | Command | Description |
|------|---------|-------------|
| `go vet ./...` | `go vet ./...` | Detect obvious bugs, misuse of `fmt.Printf`, etc. |
| `staticcheck ./...` | `staticcheck ./...` | Deeper static analysis (must be installed via `go install honnef.co/go/tools/cmd/staticcheck@latest`). |
| `golangci-lint` (optional) | `golangci-lint run` | Runs a configurable suite of linters. Install with `brew install golangci-lint` or `go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest`. |

**Agent tip** – when `golangci-lint` is present, run it after `go vet` to catch style
issues early. The CI pipeline (see `.github/workflows/*.yml` if added later) will
use the same commands.

---

## 4️⃣ Code‑Style Guidelines (Go)

All changes must satisfy the following conventions.  They are enforced by
`go fmt`, `go vet`, and the optional `golangci-lint` config.

### 4.1 Formatting & Imports
* Run `go fmt ./...` before committing.  The repository uses **tab‑indented** Go code.
* Imports are grouped in three blocks, separated by a blank line:
  1. **Standard library**
  2. **External dependencies** (e.g., `github.com/alecthomas/kong`)
  3. **Internal packages** (e.g., `github.com/yourorg/pierre/internal/...`)
* Within each block, imports are sorted alphabetically.
* Use `goimports` (or `golangci‑lint --fast`) to automatically fix import ordering.

### 4.2 Naming Conventions
| Entity | Rule |
|--------|------|
| Packages | lower‑case, no underscores or hyphens. |
| Files | snake_case (`*_test.go` for tests). |
| Types / Structs | PascalCase, descriptive (e.g., `ReviewConfig`). |
| Interfaces | End with `er` when appropriate (e.g., `ChatAdapter`). |
| Variables / Constants | camelCase for locals, PascalCase for exported. |
| Functions | PascalCase if exported, camelCase if private. |
| Constants | Use `CamelCase` for groups, `CONST_NAME` only for truly global values. |
| Test Functions | `TestXxx` and optionally `BenchmarkXxx`. |

### 4.3 Error Handling
* Errors are **never** ignored.  Use the blank identifier only when the value is truly irrelevant.
* Wrap contextual information using `fmt.Errorf("context: %w", err)` or `errors.Wrap` if the project imports `github.com/pkg/errors` (currently not used).
* Return errors **as soon as** they are detected – "guard clause" style.
* In public APIs, prefer error values over panics.  Panics are limited to unrecoverable
  programming errors (e.g., nil‑pointer dereference in `init`).

### 4.4 Documentation & Comments
* Exported identifiers **must** have a preceding doc comment beginning with the name (e.g., `// JudgePR reviews a PR and returns comments.`).
* Inline comments should be sentence‑case and end with a period.
* Use `//go:generate` directives sparingly; they must be accompanied by a test that ensures the generated file is up‑to‑date.

### 4.5 Testing Practices
* Keep tests **table‑driven** where possible; this yields concise, readable test suites.
* Use the `testing` package only; avoid third‑party test frameworks.
* Prefer `t.Fatalf` for fatal errors and `t.Errorf` for non‑fatal assertions.
* When comparing complex structs, use `github.com/google/go-cmp/cmp` (already in `go.mod`).
* Test coverage should be **≥ 80 %** for new code.
* All tests must be **deterministic** – no reliance on external services; use mocks or fakes.

### 4.6 Dependency Management
* All dependencies are managed via Go modules (`go.mod`).
* Run `go mod tidy` after adding/removing imports.
* Do not commit `vendor/` unless a vendoring strategy is explicitly adopted.

### 4.7 Logging & Output
* Use the standard library `log` package for user‑visible output.
* For structured logs (debug mode), wrap with a small helper that respects the `--debug` flag.
* CLI output must be **machine‑parsable** when `--json-output` is set (future feature).

---

## 5️⃣ Git & Pull‑Request Workflow (for agents)

1. **Branch naming** – `feature/<short‑desc>` or `bugfix/<short‑desc>`.
2. **Commits** – One logical change per commit, with a concise subject line (<50 chars) and an optional body explaining *why* the change was needed.
3. **CI** – Every PR must pass `go test ./...`, `go vet ./...`, and `golangci‑lint run` (if configured).
4. **Review** – Agents should add comments only via the LLM; do not edit code generated by the LLM unless a test fails.
5. **Rebasing** – Keep a linear history; use `git rebase -i` locally before merging.

---

## 6️⃣ Cursor / Copilot Rules (None Present)

The repository does not contain a `.cursor` directory or a `.github/copilot‑instructions.md`
file.  If such files are added in the future, agents should read them and incorporate
any additional constraints into this document.

---

## 7️⃣ Quick Reference Cheat‑Sheet (for agents)

```bash
# Build
go build -o bin/pierre ./cmd/pierre/main.go

# Run single test (replace TestFoo)
go test ./... -run ^TestFoo$ -v

# Lint & Vet
go vet ./...
staticcheck ./...
# optional
golangci-lint run

# Format & Imports
go fmt ./...
goimports -w .

# Module tidy
go mod tidy
```

---

*End of AGENTS.md*