pierre-bot/AGENTS.md

layout

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. The code does not have to be backwards compatible.

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)

# 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