Skip to content

AGENTS.md

Latest commit

 

History

History
52 lines (38 loc) · 3.71 KB

AGENTS.md

File metadata and controls

52 lines (38 loc) · 3.71 KB
Raw

AI Agent Guidelines (Engineering Best Practices)

This repository provides provider-neutral engineering practices and deterministic Go analysis. As an AI agent working in this repository or producing changes, follow these rules.

1. Top 8 Golden Rules (Always Active)

  1. Small & Hermetic Tests: Keep unit tests fast (<100ms), single-process, deterministic, and isolated. Never use time.Sleep() for test synchronization.
  2. Favor Real/Fakes over Mocks: Use real objects or high-fidelity in-memory fakes. Only use mocks when unavoidable, and only verify state-changing method calls.
  3. Flat Control Flow & Early Returns: Minimize nesting depth. Use guard clauses and return early. Never use redundant else blocks after a terminal statement (return/panic/throw).
  4. One Map Key, One Lookup: Pay the map lookup / hashing cost exactly once. Never check existence and immediately index into the map again.
  5. Positive Booleans: Name flags and boolean functions with positive semantics (isValid, isEnabled) to avoid confusing double-negatives (!isNotDisabled).
  6. Construct with Collaborators, Call with Work: Pass persistent services/clients into constructors; pass per-request data into methods.
  7. Let Code Speak for Itself: Do not write comments that describe what the code does. Reserve comments strictly for explaining why (non-obvious trade-offs, external constraints).
  8. Small & Focused Changes (Prefactoring): Refactor first to make the change easy, then add the new feature in a separate commit/PR.

2. On-Demand Skill Routing

When performing specialized tasks, consult the corresponding Skill documentation:

Task / Context Skill to Activate Key Topics
General Engineering just-good-practices Cross-language workflow, correctness, maintainability, verification
Writing / Fixing Tests testing-practices Test sizing, Fake vs Mock, Flakiness, Narrow Assertions, SMURF
Refactoring & Clean Code code-health Nesting reduction, Positive booleans, Functional core, Map lookup
API & Architecture Design api-design Hard-to-misuse APIs, Collaborators vs Work, Premature DRY, Value objects
PR & Code Review code-review Small PRs, Prefactoring, Commit context, Review etiquette
Zero-Slop Policy zero-slop High-density comments, concise commits, no filler, review protocol
Go go-practices Go APIs, toolchain gates, deterministic tests, gojgp
C++ cpp-practices Ownership, lifetimes, private boundaries, test-runtime mechanics
Java java-practices JVM boundaries, presenters, resources, collaborators
Shell shell-practices Small orchestration, quoting, cleanup, failure propagation

3. Automated Tooling & Deterministic Enforcement (gojgp)

Whenever writing or refactoring Go code:

  1. Run go run cmd/gojgp/main.go check (or ./bin/gojgp check) to run unit tests and verify compliance with all Best Practices.
  2. Run go run cmd/gojgp/main.go ./... to check specific files/packages with the native Go AST analyzer.
  3. Fix any reported linter violations deterministically before completing your task.

4. Metadata Registry Reference

For the full index of all 147 cataloged Best Practices, inspect: