Files

T

check / check (push) Waiting to run

Details

Rewrite the agent rules from scratch, with one idea per sentence and
every file name and command in backticks. Drop the rule that models
embed `models.Base`, which no package has. Say that the linter keeps
tests in external test packages, and that an `export_test.go` file
gives them access to unexported code. Limit the rules on doc comments
and blank imports to files outside the tests. State magic numbers as
a preference, and correct the blank-line rule for `return`. State the
branch workflow: pull requests target `next` and only the owner
merges `next` into `main`. Record the three snake_case JSON tags the
HTTP API keeps.

Part of #190.

Model: fable-5-1 (writing); opus-5-5 (rework)

2026-10-27 13:56:57 +00:00

3.0 KiB

Raw Blame History

Rules for coding agents

This file holds the rules for coding agents working in this repository. CONVENTIONS.md defines the architecture. REPO_POLICIES.md defines the repository standards. Both are copies of shared documents. Do not edit them here.

Before every commit

Run make fmt.
Run make check. It runs the tests and the linter in Docker, then the format check. All three must pass with no findings.

Never run go test, golangci-lint or gofmt directly. Use the make targets instead, such as make test and make lint.

Branches and pull requests

Never commit to main or next directly. Every change is a pull request from a feature branch into next.
Only the owner merges next into main.
A pull request that closes an issue has the title Description (closes #N).
One logical change per commit.
Commit messages are in the imperative mood and short.

Code style

Follow CONVENTIONS.md.
Outside test files, every package has a package doc comment.
Outside test files, every exported type, function and variable has a doc comment.
JSON tags are camelCase. The HTTP API's last_id, pow_token and hashcash_bits stay as they are, each with a //nolint:tagliatelle comment.
Prefer named constants to magic numbers. The mnd linter checks for them outside test files.
No inline error handling such as if err := f(); err != nil. Assign the error on its own line, then test it.
A return that follows another statement in its block has a blank line before it.
A blank line between the embedded fields of a struct and its other fields.
Outside test files, every blank import has a comment saying why it is there.

Architecture

The server uses go.uber.org/fx for dependency injection. cmd/neoircd/main.go lists its fx providers, such as db.New and handlers.New.
Application packages live under internal/, one package per concern.
pkg/irc holds the IRC command names and numeric reply codes.
The web package embeds the built web client.
Each exported Handle… method of Handlers returns an http.HandlerFunc.
A request struct is defined inside the method that decodes it.
The server uses the database only through the methods of db.Database.
The database migrations live in internal/db/schema/ and are embedded with go:embed.
The database is SQLite, through the pure Go driver modernc.org/sqlite.

Testing

Prefer table-driven tests.
Use testing.T helpers, not assertion libraries.
A test file lives next to the code it tests and ends in _test.go.
The linter requires each test file to be in the package's external test package, such as handlers_test. It allows export_test.go and files ending in _internal_test.go in the package itself.
An export_test.go file gives the external tests access to the package's unexported code.

Dependencies

The required libraries are listed in CONVENTIONS.md §1.
No new dependency without a reason given in the pull request.
Prefer dependencies written in pure Go, which build without cgo.

3.0 KiB Raw Blame History