64 lines
2.9 KiB
Markdown
64 lines
2.9 KiB
Markdown
# AGENTS.md
|
||
# Guidance for AI coding agents (Codex/ChatGPT) working in this repository.
|
||
# Follow these instructions as higher priority than general preferences.
|
||
|
||
## Operating principles
|
||
- Optimize for correctness, safety, and maintainability over cleverness.
|
||
- Keep changes small and reviewable. Prefer multiple small commits/PRs over one large refactor.
|
||
- Preserve existing style, architecture, and public APIs unless explicitly asked to change them.
|
||
|
||
## Dependencies (STRICT)
|
||
- Do NOT add new external dependencies (runtime or dev) without explicit approval.
|
||
- This includes package manager installs, new requirements, new npm/pip packages, new system packages, new containers/images.
|
||
- Prefer using the standard library or existing dependencies already in the repo.
|
||
- If you believe a new dependency is truly necessary:
|
||
1) explain why,
|
||
2) propose at least one no-new-deps alternative,
|
||
3) estimate blast radius and maintenance risk,
|
||
4) STOP and ask for approval before adding it.
|
||
|
||
## Tests and verification (REQUIRED)
|
||
- For any bug fix: add/adjust a unit test that reproduces the issue and prevents regressions.
|
||
- For any new feature: add unit tests for the “happy path” and at least 1–2 edge cases.
|
||
- Prefer unit tests over integration tests unless the change is inherently integration-level.
|
||
- Run the smallest relevant test command(s) after changes:
|
||
- First: targeted tests for the changed modules.
|
||
- Then (if time/CI expectations): full unit test suite.
|
||
- If tests cannot be run in the current environment, clearly state what you would run and why.
|
||
|
||
## Commands and environment safety
|
||
- Before running commands that could modify the environment or take a long time (e.g., installs, migrations, DB changes),
|
||
explain what you intend to run and ask for approval.
|
||
- Avoid destructive operations (deleting files, dropping DBs, resetting environments) unless explicitly requested.
|
||
- Never print, log, or exfiltrate secrets. If you detect a likely secret, redact it and point it out.
|
||
|
||
## Implementation approach
|
||
- Start by understanding existing patterns:
|
||
- find similar code paths,
|
||
- follow established naming and folder conventions,
|
||
- reuse existing utilities/helpers.
|
||
- When making non-trivial changes:
|
||
1) propose a short plan (3–7 bullets),
|
||
2) list the files you expect to touch,
|
||
3) call out risks/unknowns,
|
||
4) then proceed.
|
||
|
||
## Coding standards
|
||
- Prefer clear, boring code over abstractions.
|
||
- Add types/annotations where the repo uses them.
|
||
- Add docstrings/comments only where they clarify intent, invariants, or tricky logic.
|
||
- Handle errors explicitly; don’t swallow exceptions.
|
||
|
||
## Documentation and changelog
|
||
- Update relevant docs when behavior changes (README, module docs, inline docs).
|
||
- Summarize changes at the end:
|
||
- What changed (bullets),
|
||
- Why,
|
||
- How to test (exact commands),
|
||
- Any follow-ups/todos.
|
||
|
||
## When uncertain
|
||
- Ask a direct question or present two options with tradeoffs.
|
||
- Do not make breaking changes based on guesswork.
|
||
|