162 lines
6.8 KiB
Markdown
162 lines
6.8 KiB
Markdown
---
|
||
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* |