snowgo: Instructions file for Codex

AGENTS.md

AI coding-agent execution manual for snowgo.

Go: 1.26+ (toolchain: go1.26.7).

Goal: deliver the smallest necessary, verifiably correct change without compromising correctness, security, or maintainability.

1. Instruction Precedence and Document Roles

Resolve conflicts in this order:

1. The user's current explicit request, constraints, and explicitly confirmed exceptions.
2. The hard rules in this AGENTS.md.
3. The relevant project-specific references.
4. Existing conventions in the affected module, unless they conflict with a higher-priority rule.

The user's request defines the outcome and scope, but do not infer permission to bypass generated-file, data-integrity, security, or authorization constraints. Surface the conflict and obtain explicit confirmation before treating it as a policy exception.

CODING.md defines code-level practices; ARCHITECTURE.md defines layers, data, transactions, caching, and queries; OPERATIONS.md defines security, testing, configuration, release, and review practices.

Before implementation, read only the references relevant to the affected change surface. Use the Reference Index to decide what is required. Do not read unrelated references for a small localized change; if relevance or a boundary is unclear, read the applicable reference or ask.

Material ambiguity affecting APIs, data, permissions, security, compatibility, or scope must be surfaced with viable options. Do not silently select a high-risk interpretation.

---

2. AI Coding Behavior Guidelines

Think Before Coding

For non-trivial changes, understand the requested outcome, identify material assumptions and ambiguities, consider affected boundaries and existing architecture, and define how the result will be verified. Ask when missing information would materially change the solution.

Simplicity and Existing Patterns First

• Write only the minimum code needed for the current requirement. Do not add speculative features, abstractions, configuration, compatibility layers, or extension points.
• Before introducing a pattern for dependency injection, errors, logging, transactions, caching, API responses, authorization, or configuration, search for and reuse the established project pattern unless it is insufficient.
• Add a third-party dependency only when the standard library and existing dependencies are insufficient. Assess maintenance, license, security, and operational impact; then run go mod tidy and relevant tests.