AGENTS.md

• When a repository does not already have a strong local AGENTS.md file
• When you want starter AGENTS.md context to use through Oi API or MCP
• When a repo needs shared instructions that work across codex, chatgpt, claude, cursor, copilot, or gemini-style runtimes
• When the current AGENTS.md is weak enough that replacing it with a clean starter is easier than patching it

# AGENTS.md ## Purpose This file is the operating contract for a default coding agent working in this repository. Use it for execution behavior, editing rules, validation expectations, and delivery standards. Use product, architecture, and setup docs for repository-specific context. ## Read Order Before planning or coding, review inputs in this order: 1. Explicit user instructions in the current thread 2. Linked ticket or issue acceptance criteria 3. Product or architecture docs in this repo 4. This AGENTS.md 5. README and incidental docs If these sources conflict, follow the same precedence order. ## Core Expectations - Keep changes minimal, scoped, and testable - Prefer existing repository patterns over inventing new ones - Make the smallest change that satisfies the request and acceptance criteria - Inspect real code before proposing architecture or implementation changes - Trace the actual execution path before editing behavior - Call out assumptions when local context is incomplete - Prefer safe, reversible changes and explicit approval for destructive or external side effects - Treat merge, deploy, schema backfills, and irreversible cleanup as human approval gates unless explicitly requested ## Working Style - Fix the root cause when practical, not just the visible symptom - Preserve surrounding naming, structure, and abstractions unless the task requires change - Avoid broad refactors unless they are necessary to complete the task safely - Do not invent repository facts, requirements, or data flows - Reuse existing utilities, helpers, and patterns before adding new ones - Add comments only when they clarify non-obvious logic or important constraints - Prefer straightforward code over clever code ## Before Editing - Read the relevant files, nearby tests, types, and config first - Check whether there is existing work in progress and avoid overwriting unrelated user changes - Identify the smallest set of files that should change - Verify whether the request affects API contracts, schemas, permissions, environment config, or external integrations - If the task changes persisted data, migration flow, or public interfaces, treat that as a higher-risk change and validate accordingly ## Editing Rules - Keep diffs focused and easy to review - Do not rename, move, or delete files unless it materially improves the task outcome - Do not rewrite unrelated code just to match a preferred style - Preserve backward compatibility unless the task explicitly allows a breaking change - If introducing a new abstraction, make sure it reduces real duplication or risk - If changing generated code, update the source of truth when possible - If changing config or environment assumptions, document the impact ## Data And Migration Rules - Treat database, queue, cache, and persistence changes as production-affecting by default - Prefer forward-only migrations unless repository guidance explicitly says otherwise - Never silently change data semantics, identifiers, or default values without checking downstream impact - Consider backfills, indexing, rollout order, and compatibility with older records - Call out operational risk when a change could affect deploy order, background jobs, or live traffic ## API And Backend Rules - Check request and response contracts before changing backend behavior - Preserve error shape, auth expectations, and permission checks unless intentionally changing them - Validate new inputs close to the boundary - Consider failure modes, retries, idempotency, and observability for backend changes - Do not weaken security, auth, or data isolation for convenience ## Frontend Rules - Preserve design-system and accessibility patterns already in use - Handle loading, empty, error, and success states deliberately - Consider responsive behavior, keyboard access, focus handling, and user-visible copy - Avoid introducing UI state complexity that is not justified by the feature ## Testing And Validation - Run the smallest useful validation for the changed area - Prefer targeted tests first, then broader checks if risk warrants it - If full validation is too expensive or blocked, say what you ran and what remains unverified - Add or update tests when the change alters behavior, fixes a regression, or protects important logic - Manually validate user-facing flows when automated coverage is weak or absent ## Performance And Reliability - Consider performance when changing loops, queries, rendering, network calls, or hot paths - Consider concurrency, race conditions, and duplicate execution when changing async workflows - Avoid hidden global state, silent fallbacks, and behavior that is difficult to observe in production ## Security And Privacy - Minimize secret exposure, logging of sensitive data, and unnecessary privilege expansion - Preserve tenant and user isolation rules - Treat auth, billing, permissions, uploads, webhooks, and external integrations as high-scrutiny areas - Flag uncertainty instead of guessing when a security-sensitive change is involved ## Documentation And Artifacts - Update docs, examples, or config references when the workflow actually changes - Keep comments, READMEs, and tickets aligned with shipped behavior - If a task changes setup, deployment, migrations, or operator workflow, document that clearly ## Communication - Be concise, direct, and specific - Summarize what changed, why it changed, and how it was validated - Mention blockers, assumptions, tradeoffs, and remaining risks explicitly - Distinguish clearly between what is known, what is inferred, and what is still unknown ## Definition Of Done Work is done when: - the change matches the request and acceptance criteria - affected code paths have been reviewed end to end - validation appropriate to the risk level has been run, or gaps are called out explicitly - related docs or artifacts are updated when needed - assumptions, tradeoffs, and follow-up risks are clearly stated ## Adapt This File Customize this starter for the repository by adding: - product context and domain constraints - package- or app-specific instructions - testing and release expectations - migration, persistence, or data safety rules - deployment, observability, and environment gotchas - language- or framework-specific conventions that materially affect implementation

• Start with the repository's real workflows, risks, and constraints before drafting instructions.
• Prefer one strong shared AGENTS.md over padded or generic agent-policy prose.
• Make execution constraints, approvals, and validation expectations explicit.
• Optimize for safe execution and fast onboarding, not documentation theater.
• Keep the file broadly useful across supported agent runtimes.

Markdown