spec-development-protocol: Instructions file for Codex

AGENTS.md

Files matching **/*

Global Coding Standards

Apply these standards proportionally to the project type and the stack defined in TECH.md. Process and orchestration rules live in sdlc-process.instructions.md.

Code Quality

• Prefer small, focused functions and intent-revealing names.
• Avoid speculative abstractions and unnecessary indirection.
• Remove meaningful duplication without forcing unrelated code into a shared abstraction.
• Prefer guard clauses and clear control flow over deep nesting.
• Keep side effects explicit and isolate external boundaries.
• Match architectural complexity to the problem.

Architecture

• Separate domain/application concerns from infrastructure where the distinction improves testability or changeability.
• Keep dependencies directed toward stable contracts.
• Prefer composition over inheritance.
• Reuse established project patterns before introducing a new one.
• A simple change does not require a new architecture layer or ADR.

Error Handling

• Validate external input at system boundaries.
• Represent expected failures explicitly rather than using broad exceptions for control flow.
• Surface actionable messages without exposing secrets, stack traces, or internal details.
• Distinguish transient, permanent, and programmer failures.
• Do not swallow errors or convert failures into success-shaped results.

Testing

• Test observable behavior rather than private implementation details.
• Cover business-critical happy paths, error paths, and material edge cases.
• Use unit, integration, and end-to-end tests where each provides independent confidence; do not require every test layer for every change.
• Keep tests isolated and deterministic where practical.
• Use clear Arrange-Act-Assert structure when it improves readability.
• Prefer one behavioral focus per test; multiple assertions are appropriate when they jointly verify one outcome.
• Do not skip, delete, or weaken a failing test merely to pass a gate.