air/AGENTS.md

AGENTS

Guidelines for contributors and AI coding agents working in this repository.

Goals

• Keep changes minimal, focused, and idiomatic to Go.
• When adding changes, do NOT break existing behavior.
• Make changes small and easy to review.
• Code and comments must be written in English.
• Prefer root-cause fixes over band-aids; do not refactor unrelated code.
• Maintain user-facing behavior and CLI flags unless explicitly changing them.

Project Snapshot

• Language: Go (modules enabled; go 1.25 in go.mod).
• Module path: github.com/air-verse/air.
• Entry: main.go.
• Core package: runner/ (watcher, engine, flags, config, proxy).
• Docs: README*.md, air_example.toml, docs/.
• Tooling: Makefile, hack/check.sh, hooks/pre-commit, .golangci.yml.
• Default config file: .air.toml (generated by air init).

Repository Layout

• main.go: CLI entrypoint and flag parsing.
• runner/engine.go: build/run loop and watcher orchestration.
• runner/config.go: config schema, defaults, parsing, validation.
• runner/flag.go: CLI flag wiring.
• runner/watcher.go: fsnotify vs polling watcher selection.
• runner/proxy*.go: live-reload proxy, SSE stream, embedded JS.
• runner/util*.go: platform helpers, process control, misc utilities.
• runner/*_test.go: unit tests and platform-specific tests.
• hack/check.sh: goimports + golangci-lint driver.
• hooks/pre-commit: runs hack/check.sh on staged files.

Build / Lint / Test

• Install tools + hook: make init (goimports + golangci-lint v2.6.1).
• Format + lint staged Go files: make check.
• Format + lint all Go files: make check scope=all.
• Build binary: make build (runs make check first).
• Install locally: make install (runs make check first).
• CI prep (module tidy): make ci.
• Full test suite: go test ./... or make test (race + timeout).
• CI tests: make test-ci (CI=true, longer timeout).
• Pre-commit hook: runs ./hack/check.sh on staged files.

Single Test Recipes

• Single package: go test ./runner -v.
• Single test: go test ./runner -run '^TestName$' -count=1 -v.
• Subtest: go test ./runner -run '^TestName$/Subcase$' -count=1.
• All packages, one test: go test ./... -run '^TestName$' -count=1.
• Add -race or -timeout=3m when debugging flakiness.

Code Style (Go)

• Formatting: run goimports (it also applies gofmt).
• Imports: let goimports group stdlib, third-party, local imports.
• Naming: CamelCase for exported, lowerCamel for unexported.
• Initialisms: use standard forms (ID, URL, HTTP, JSON).
• Receivers: keep receiver names short and consistent (cfg, e, p).
• Types: prefer concrete types over any; avoid needless interfaces.
• Constants: use const for defaults; use 0o755 style perms.
• Zero values: design structs so zero values are valid when possible.
• Early returns: avoid deeply nested else blocks.
• Paths: use filepath for OS-safe path handling.
• Shelling out: prefer exec.Command with args; use /bin/sh -c only when needed.
• Platform code: maintain *_linux.go, *_windows.go, build tags parity.
• Comments: keep short, English, and explain "why" more than "what".
• Use time.Duration for timeouts and backoffs.
• Prefer value receivers unless mutation or large copies require pointers.
• Avoid globals except for constants and small immutable vars.
• Treat nil slices as empty; do not rely on non-nil defaults.
• Keep TOML/JSON tags aligned with field names and usage strings.

Error Handling & Logging

• Wrap errors with context: fmt.Errorf("read config: %w", err).
• Use errors.Is/As for comparisons, errors.Join for aggregates.
• Avoid panics in packages; log.Fatal only at CLI entrypoints.
• Log via mainLog, buildLog, runnerLog, watcherLog in runner.
• Keep log output concise and consistent with existing prefixes.

Concurrency & State

• Guard shared state with sync.Mutex or sync/atomic.
• Avoid data races; keep goroutines bounded and cancellable.
• Use channels for signaling (see buildRunCh in runner/engine.go).
• Use context and timeouts for operations that may block on I/O.

Tests

• Location: alongside code as *_test.go.
• Style: table-driven tests with t.Run where it improves clarity.
• Parallelism: use t.Parallel() only for isolated tests.
• Helpers: use t.Helper, t.TempDir, t.Setenv, t.Cleanup.
• Assertions: use testify/require for fatal checks, testify/assert for soft checks.
• Fixtures: prefer _testdata and temp dirs; avoid network dependencies.
• OS coverage: use *_windows_test.go, *_linux_test.go for platform behavior.

Config / CLI Discipline

• Config fields: edit runner/config.go, update parsing/defaults/tests.
• CLI flags: update runner/flag.go, sync help text, update README usage.
• Keep air_example.toml aligned with any config changes.
• Behavior changes must include README updates and tests.

Documentation

• Update README.md for user-visible changes (flags, config, examples).
• Keep docs/ content accurate when behavior changes.
• Add concise migration notes for breaking or behavioral changes.
• Mention new environment variables or defaults in docs.

Tooling and Linters

• make check runs hack/check.sh -> goimports + golangci-lint.
• Enabled linters include: errcheck, revive, staticcheck, testifylint, unused.
• Fix lint warnings rather than suppressing unless clearly justified.
• Keep changes compatible with the current Go version in go.mod.

Scope and Safety

• Avoid touching vendor/, third_party/, or generated files.
• Do not change CLI output or flags unless explicitly requested.
• Avoid broad refactors; keep changes localized to the feature/bug.
• Prefer root-cause fixes over temporary workarounds.
• Do not add dependencies unless there is a clear, reviewed need.
• Assume offline mode; no external network usage.

Cursor / Copilot Rules

• No .cursor/rules/, .cursorrules, or .github/copilot-instructions.md found.
• If any are added later, follow them and copy key points here.

For AI Coding Agents (Codex CLI)

• For multi-step tasks, maintain an explicit plan and mark progress.
• Keep edits in a single focused patch per logical change.
• Briefly state what you are about to do before running commands.
• Prefer rg for searches and keep file reads to small chunks.
• Validate with make check and go test ./... when changes touch Go code.
• Avoid touching unrelated files; do not reformat the repo wholesale.

Release Notes (maintainers)

• Follow the README "Release" section for tagging; CI performs builds.

Review guidelines

• Review all code changes in this pull request against the style guide. Also check for possible bugs. Diffs are important, but read the full file for proper context. Make it clear that all suggestions are optional and the final decision belongs to the human reviewer.

• Only report real style guide violations. Do not complain about else statements when early returns are already used correctly. However, you may point out excessive nesting.

• Use simple and concise English. Keep sentences short and easy to understand.

• Only create comments for actual issues. If the code follows the guidelines and no issues are found, comment only: lgtm

---

Questions or uncertain scope? Open an issue or ask for clarification before implementing.